Appendix B: Compiling CGI Programs Created on NetExpress

If you want to compile and run on a UNIX system a CGI program that was created on NetExpress, there are certain steps that have to be taken. On NetExpress Version 2, these steps are taken for you by the UNIX Option. The UNIX Option enables you to automatically rebuild a CGI program, created using NetExpress, on a UNIX system. Instructions on how to use the UNIX option are provided in NetExpress Version 2 in the Unix Option User Guide (uopubb01.htm) . NetExpress Version 2 also provides additional information on creating and deploying Internet and intranet applications in the Internet Applications (pipubb01.htm) book.

For NetExpress Version 1, you need to manually transfer a NetExpress created program to a UNIX system, and then rebuild the program on that system. The help documentation for NetExpress Version 1 contains instructions on how to transfer and rebuild programs. However, with this version of Object COBOL for UNIX, the instructions for manually transferring and rebuilding programs has changed slightly. If you want to transfer and rebuild programs using this version of Object COBOL, ignore the instructions documented in NetExpress Version 1, and use the instructions documented here instead.

B.1 Manually Deploying NetExpress Created CGI programs to UNIX systems

The NetExpress COBOL system has extensions to the COBOL language that enable you to create Internet applications. The UNIX COBOL systems do not directly support this syntax; however, the Htmlpp preprocessor provides this support. To recompile and run a CGI application on the UNIX system:

Copy the source code from NetExpress to your UNIX system.
Re-compile the source code using the Htmlpp preprocessor (see the section Compiling CGI Programs for details).

When you create an Internet application on NetExpress, the executable CGI program is called directly. When you transfer the program to UNIX, the CGI program must be called by a script that first sets up the environment and run-time system. This means that you must edit the form that calls the CGI program so that it calls the script instead.

B.2 Compiling CGI Programs

You compile a CGI program using the command:

cob cgiprg.cbl -C "preprocess(htmlpp)"

where cgiprg is the name of your CGI program. If you use another preprocessor during compilation (for example, a separate SQL preprocessor), then that preprocessor can be specified in addition to the Htmlpp processor; for example:

cob cgiprg.cbl -C "preprocess(htmlpp) preprocess(otherpp)"

If you prefer, you can generate a fully preprocessed source file on one platform and compile that source file on another system. First, create the preprocessed source file:

cob cgiprg.cbl -C "noint preprocess(htmlpp) out(cgiprg.dst)"

Then on the target system, compile the resulting file:

cob -k cgiprg.dst

See your Object COBOL User Guide for detailed information on the cob command.

B.2.1 Preprocessor options

The following options are available with the Htmlpp preprocessor:

Option	Default	Description
[NO]AUTOFORMAT	NOAUTOFORMAT	Do not assume that .htm copy files are free format source. If COBOL is compiled fixed format then only columns 8 through 72 are read in .htm files.
[NO]CONFIRM	NOCONFIRM	Preprocessor echoes directives when CONFIRM is set.
DEBUG		Output extra debugging information to the output file specified by DEBUGFILE or OUT.
[NO]DEBUGFILE	NODEBUGFILE	This directive is used for diagnosing preprocessor problems. DEBUGFILE causes the preprocessor to output a file source.deb where source is the name of your source file. This file contains the expanded source code produced by the preprocessor.
[NO]WARN	WARN	Suppress any warning messages that Htmlpp might produce.
OUT(name)		Create a fully preprocessed output source file with the name name.
PREPROCESS(name)		Specify a nested preprocessor to read source files and process COPY statements.
[NO]STEPEXEC	NOSTEPEXEC	A synonym for STEPHTML
[NO]STEPHTML	NOSTEPHTML	When you are animating an EHTML program, STEPHTML causes each separate line of HTML to be output as one Animator step. Setting NOSTEPHTML outputs an entire EXEC HTML ... END-EXEC block as a single step.
TRACE	Off	This directive is used for diagnosing preprocessor problems. TRACE causes the preprocessor to output a file source.trc where source is the name of your source file. This file contains a trace of information passed between the preprocessor and the COBOL compiler.

If neither the DEBUGFILE nor the OUT options are specified, by default a precompiled source listing is not produced. If both options are specified, only one output file is created, and the filename is that specified by the last-used option; for example, the options OUT "MYOUT.TXT" DEBUGFILE create filename.deb and not myout.txt.

Some options can be abbreviated; the abbrevations are indicated by the bold characters in the table above. For example, AUTOFORMAT can be abbreviated to AF, or NOAF. However, in the case of WARN, only NOWARN can be abbreviated (to NW).

B.3 Creating a script that sets the environment for CGI programs

When a form calls the CGI program on a UNIX system, the environment must be set up so that the CGI program will run correctly.

You should follow these rules to set the environment:

If you have rebuilt the RTS to include the HTML support, it must be placed in the cgi-bin directory on your UNIX machine.
COBPATH should point to the location of your application code, or the code must be placed in the cgi-bin directory.
Application output HTML forms must be placed in the cgi-bin directory. Alternatively you can place them in any directory you require, and then set the COBDATA environment variable to point to the directory containing the forms.
Note: COBDATA affects how the RTS locates all data files used by your application.

For example, the script shown below (cobcgi) is typical of the script that needs to be executed. It sets up the COBOL environment and runs a program called cgiapp. If you are running the program on a system with a COBOL version earlier than Version 4.1, then you run it using the rebuilt RTS. Otherwise, you can use cobrun.

# Setup COBDIR and COBPATH to locate the COBOL product 
# to run the program 

# set the location of the COBOL system 
COBDIR=/usr/test/cobol 

# Set the COBOL program search path 
COBPATH=:/usr/test/cobol/progs 

# Place these variables in your environment 
export COBPATH COBDIR COBDATA 

# Run cgiapp becomes 
cobrun cgiapp $*

B.4 How Htmlpp Differs from NetExpress CGI Processing

Htmlpp accepts a superset of the syntax and functionality provided by the NetExpress:

Htmlpp allows the use of the COUNT IN clause on any data description entry within an external form, not just those descriptions that have an OCCURS clause associated with them. This can be useful in determining if a data value has been provided as input to the CGI program.
Htmlpp allows arbitrary numeric data items to be a receiving field. For example, a PIC S99V99 COMP-5 IDENTIFIED BY item accepts 2 bytes of display data (PIC S99v99 COMP-5 defines 2 bytes of storage) and converts the input (display) numeric into COMP-5 format for storage in the receiving data item.

If you have developed a program for use with the Htmlpp preprocessor, and the logic of that program relies on any of the features in the above list, and you want to port your code back to Net Express or to a different UNIX environment, then you should also use the Htmlpp preprocessor provided by this Object COBOL system in that environment.

To create a fully functioning Htmlpp preprocessor on another system, you should:

Recompile htmlpp.int on that system to create a generated file. htmlpp.int is provided with this version of Object COBOL for UNIX
If the target system is NetExpress, rename the generated code file to htmlppx.gnt and place this file in the COBOL system directory ($COBDIR). Change your preprocessor command line or $SET directives to specify preprocess(htmlppx) .
If the target system is a UNIX system which does not provide the Htmlpp preprocessor, place the generated code file htmlpp.gnt in the COBOL system directory ($COBDIR). Preprocessor settings in your source and build commands do not have to change.

B.5 Errors flagged by Htmlpp

The following errors are flagged by the Htmlpp preprocessor:

Continuation line in string but no starting quote. Quote assumed.
End of file encountered while parsing string. String terminated.
Name is too long, extra chars ignored.
String is too long, extra chars ignored.
Numeric literal is too long, extra chars ignored.
String not terminated and not continued. Terminated at end of line.
EXTERNAL-FORM must be an 01 level.
Invalid preprocessor option encountered on command line.
Invalid preprocessor option value.
Cannot find specified preprocessor for source input.
Cannot find default preprocessor for source input (cp or precgicp).
Cannot write to specified debug/output file.
Cannot determine constant value of name.
IDENTIFIED BY data item is length zero.
EOF reached before 'END-EXEC'. END-EXEC assumed

B.5.1 Fatal errors for Htmlpp

Unable to read input file.
Cannot parse picture string.
Unable to find second byte of DBCS character (in DBCS environments)

B.6 Known Restrictions

The following restrictions apply to the Htmlpp preprocessor:

Htmlpp relies upon the existence of nested preprocessors to handle the actual reading of source files and copyfile handling. The search order for these is:
1. User defined nested preprocessor
2. Preprocessor name cp (default supplied by Micro Focus)
3. Preprocessor name CP
If none of these are found Htmlpp will abort.
The GLOBAL attribute is not recognized on EXTERNAL-FORMs. If a form is required in a nested program, it must be defined in that nested program.
Behavior when using this preprocessor with programs containing Object Oriented syntax is undefined..
String literals are limited to 160 character positions.

Micro Focus Environment Variables

EBCDIC/ASCII Translation Tables