Running CGI Programs under Com-plete

#### Search Results

Search

# Running CGI Programs under Com-plete

This section provides information about running application programs under Com-plete in the supported environments.

This document covers the following topics:

- The Com-plete Environment

- Thread Storage Considerations

- COBOL Considerations

- PL/1 Considerations

- S/390 Assembler Considerations

## The Com-plete Environment

Programs that comply with the HTTP server CGI requirements can use any of the mechanisms available under Com-plete to access data.

It is currently possible to access Adabas , DB2 , and VSAM data from this environment.

Refer to the appropriate Com-plete documentation for more information about accessing data from this environment.

This section provides information about running programs under Com-plete.

### Linking the Program for Com-plete

An application program may only be run under Com-plete if it is available to the Com-plete address space. To make an application program available to the Com-plete address space, link the program into a dataset in the COMPLIB concatenation under z/OS, or to one of the libraries in the z/VSE search chain. Always link a reentrant module with the 'RENT' option .

Sample jobs HJBNCOBC and HJBNPL1C are provided on the HTPvrs.JOBS dataset to do this once an object module has been created. Creation of the object modules is covered in the appropriate language-specific section of this section.

Note
Since high-level languages like Natural, COBOL, and PL/1 load the Com-plete-provided CGI extensions, COBOL and PL/1 programs must be linked into a dataset in the COMPLIB concatenation whereas no additional processing is required for Natural.

## Thread Storage Considerations

Depending on the programming language you plan to use for writing CGI programs, and a number of other factors, you must ensure that there is enough memory available in the threads where your programs will run. Unfortunately, some environments require considerable amounts of memory in the threads below the line, as listed in the following table:

Environment | Thread size required below 16MB
--- | ---
IBM LE with z/VSE | 200 - 400 kByte, can be reduced using customized CEEUOPT/CEEROPT (see IBM Language Environment Considerations in section Software Interfaces in the Com-plete System Programming documentation)
IBM LE with z/OS 1.4 or above | 8-32 kByte
Natural 3 | 4 kByte
Assembler, Natural 4 | 0

### General Rules for Saving Thread Storage

- Build your modules with the attributes RENT and RMODE=ANY.

- On z/OS, specify Com-plete sysparm APPLYMOD=78.

### The Thread Root Program PAENSTRT

By design of the HTTP server, the root program started in any thread used by the HTTP server is PAENSTRT. This module, in turn, loads the actual CGI programs into the same thread and executes them. Therefore, if your CGI programs require memory below the 16MB line, you must catalog PAENSTRT in ULIB, specifying the size as necessary. Also, make sure there is a thread group and subgroup available big enough to hold this size.

### Determining the Required Thread Size

If you get errors indicating that there is not enough memory available to the CGI programs, like abends U4093 with LE, proceed as follows:

- Ensure the thread size above the 16MB line is large enough. THSIZEABOVE=2048 should be sufficient in most cases.

- Start off with a thread size below the line of 400K (both THREAD-GROUP and PAENSTRT).

- Run your programs, and use UCTRL function TU to watch how much memory they really use.

- Reduce the sizes for THREAD-GROUP and PAENSTRT accordingly.

## COBOL Considerations

COBOL programs must be compiled and linked as if for the batch environment on the operating system where they will run. Once compiled and available to the Com-plete address space or partition, COBOL programs may simply be run as documented earlier in this documentation.

### Sample Programs and Jobs

The following table describes the various HTTP server COBOL samples that are provided on the HTPvrs.SRCE dataset.

Member | This is a sample ...
--- | ---
HHANCOBT | HTML page that drives the HOANSAMP COBOL program using a form and the HTTP GET method. It may be referenced using the following URL. Refer to the installation verification procedure for more information about interpreting this URL. http://your.ip.address:port/htpvrs/srce/hhancobt.htm
HJBNCOBC | JCL member to compile and link the sample COBOL CGI program HOANSAMP.
HOANCONV | COBOL program that uses the conversational features of the HTTP server to enable it to converse with a WWW browser over a series of HTML pages. It may be started using the following URL. Refer to the installation verification procedure for more information about interpreting this URL. http://ip-addr:port/cgi/hoanconv
HOANSAMP | COBOL CGI program that is driven by the HHANCOBT HTML page.

### COBOL and the Com-plete CGI Extensions

COBOL programs may use the Com-plete CGI extensions by issuing a call to the appropriate extension module as follows:

    call 'HAANUPR' using HTPCGI-STATUS, function, parm1, parm2, <..>, parmn.

The HTPCGI-status must be defined as follows in COBOL:

    01 HTPCGI-STATUS.
       03 HTPCGI-RETURN-CODE pic 9(4)COMP.
       03 HTPCGI-REASON-CODE pic 9(4)COMP.

The following describes the COBOL format required for the other parameters:

Name | COBOL Format | Description
--- | --- | ---
field | pic x(<length>) | Must be an alpha field ending in a blank character
variable | pic x(<length>) | Must be an alpha field ending in a blank character
value | pic x(<length>) | Must be an alpha field of length 'length'
length | pic 9(4) COMP | Must be a two-byte binary field containing a length
data | no defined format | The start of an area (normally alpha) of length 'length'

## PL/1 Considerations

PL/1 programs must be compiled and linked as if for the batch environment on the operating system where they will be running. Once compiled and available to the Com-plete address space or partition, PL/1 programs may be run as documented earlier in this documentation.

### Sample Programs and Jobs

The following table describes the HTTP server PL/1 samples that are provided on the HTPvrs.SRCE dataset.

Member | This is a sample ...
--- | ---
HHANTPL1T | HTML page that drives the HPANSAMP PL/1 program using a form and the HTTP GET method. It may be referenced using the following URL. Refer to the installation verification procedure for more information about interpreting this URL. http://ip-addr:port/htpvrs/srce/hhancget.htm
HJBNPLIC | JCL to compile and link the sample PL/1 CGI program HPANSAMP.
HPANSAMP | PL/1 CGI program that is driven by the HHANPL1T HTML page.

### PL/1 and the Com-plete CGI Extensions

PL/1 programs may use the Com-plete CGI extensions by issuing a call to the appropriate extension module as follows:

    CALL 'HAANUPR' using HTPCGI-status, function, parm1, parm2, <..>, parmn.

The parameters required by this interface is described in the section Com-plete CGI Extensions.

The HTPCGI-status must be defined as follows in PL/1:

    DCL 1 HTPCGI-STATUS,
          2 HTPCGI-RETURN-CODE FIXED BINARY(15),
          2 HTPCGI-REASON-CODE FIXED BINARY(15);

The following describes the PL/1 format required for the other parameters:

Name | PL/1 Format | Description
--- | --- | ---
field | CHAR(<length>) | Must be an alpha field ending in a blank character
variable | CHAR(<length>) | Must be an alpha field ending in a blank character
value | CHAR(<length>) | Must be an alpha field of length 'length'
length | FIXED BINARY(15) | Must be a two-byte binary field containing a length
data | no defined format | The start of an area (normally alpha) of length 'length'

## S/390 Assembler Considerations

### Assembler and the Com-plete CGI Extensions

Software AG recommends that Assembler programs use the standard Com-plete API to handle CGI requests.

### On this page

- The Com-plete Environment
- Thread Storage Considerations
- COBOL Considerations
- PL/1 Considerations
- S/390 Assembler Considerations