Installing Natural CGI

Com-plete supports the Natural runtime system as documented in the Natural documentation in the section for Com-plete.

Follow the steps for installing Natural under this environment as required.

The Natural installation should be complete and working in the environments where the HTTP server is to run before attempting to support the Natural CGI processing.

The Natural Web Interface is supported by Natural version 3.1 and above.

This document covers the following topics:

Natural Tasks

A number of additional tasks are required to ensure that the Natural CGI processing operates successfully. Note that the HNANSHEL program delivered with the product is a Natural program itself and an integral part of the Natural CGI processing logic.

Follow the next steps carefully:

  1. Ensure that the HTPvrs Natural library has been INPLed as part of the installation process.

  2. Copy the Natural subprograms USR0050N, USR0330N, USR1025N and USR2013N from the SYSEXT Natural library to the SYSTEM library on FNAT.

    As an alternative to this step, when Natural Security is installed, make SYSEXT a STEPLIB in the Natural environment.

  3. If Natural Security is installed, copy the Natural Security Interface Subprogram NSCLI to the SYSTEM library on FUSER.

Relationship to the HTTP Server Configuration

The following parameters specified in the HTTP server configuration are directly associated with the use of Natural CGI:

Parameter Description
HTTPUSER The default user ID for a user who is able to issue a Natural CGI request. The user ID is passed on to Natural and must therefore be defined, for example, if Natural Security is installed Note: Applies only when running under Com-plete.
LOGON If the HTTP server is running with security, Natural is passed either the default user ID as specified by HTTPUSER or the user ID for which the user provided a valid user ID and password. Once again, there may be Natural Security or other implications. Note: Applies only when running under Com-plete.
NATLIB Name of the Natural library where the HTTP server tells Natural to look for a Natural program specified on an HTTP request when no Natural library is specified.
NATPARM Where appropriate or necessary, Natural parameters may be specified here to override parameters generated in the Natural parameters in the nucleus. The 'STACK ' parameter is ignored if specified in this string.
NATTHRD The name of the Natural front-end driver module used to start Natural in Com-plete.

A useful way to provide Natural parameters is to specify NATPARM=’PROFILE=HTTP’ (or any other profile name) and set all parameters in that profile in Natural.

RPC=(RPCSIZE=32) Required.
OUTDEST=CONSOLE When running as NATCGI, Natural is in “asynchronous” mode, i.e., without a terminal. OUTDEST=CONSOLE tells Natural to write error messages which would normally go to the terminal to the console and the Com-plete joblog.
SENDER=HTTPERR Natural in asynchronous mode occasionally requires a destination for certain error output (even with OUTDEST=CONSOLE), otherwise it will complain “NAT1500 Open for print file HC failed (Invalid destination)”. Specifying SENDER=HTTPERR causes Natural to send this output to the imaginary printer HTTPERR (or choose any other name). If you specify a name that is not a real printer, the error messages remain in the spool file and can be viewed using the Com-plete utility USPOOL or via the Com-plete web UI.
CM=OFF When running as NATCGI, Natural must not attempt to read any commands.
MENU=OFF When running as NATCGI, Natural must not use menu mode.
IMSG=ON,ITERM=ON If Natural cannot start up cleanly, it should report the problems and terminate. Otherwise obscure subsequent errors might occur. Also, ITERM=ON terminates Natural when a program attempts reading terminal input, what would be illogical in this environment, and has even been observed to cause infinite loops flooding Com-plete’s spool file.
AUTO=ON Tells Natural to obtain the userID from Com-plete, i.e., either the user’s userID if he logged in, otherwise the one set in HTTP server parm HTTPUSER.

Invoking a Natural CGI Program

A Natural CGI program is invoked using the standard browser URL

http://ip-addr:port/natcgi/program

where 'program' is the Natural program you want to run, which exists in the Natural library specified in the NATLIB configuration parameter.

If you want to provide a Natural library name, use the URL

http://ip-addr:port/natcgi/library/program

where 'library' is the Natural library where 'program' resides.

Note:
All programs to be run using Natural CGI must be cataloged; that is, they must be in object format.

Installation Verification

To test the installation:

  1. Invoke a program that does nothing.

    Such a program is provided in the HTPvrs Natural INPL file delivered with Com-plete as HNANWTOP .

  2. Stow the program HNANWTOP in your NATCGI library.

  3. Try to invoke it from a web browser using the URL

    http://ip-addr:port/natcgi/hnanwtop

    You will receive no output at your browser; however, the message in the program should be written to the operator console.

  4. If this is successful, test the sample Natural CGI program:

  • Ensure that the HNANSAMP program is stowed or cataloged in the default CGI library specified by the NATLIB configuration parameter.

  • Invoke the URL

http://ip-addr:port/htpvrs/srce/hhannatt.htm

When you enter your name, the HNANSAMP program should be invoked and echo your name back to the browser.

Additional Notes

The following should also be taken into consideration when installing Natural CGI:

  1. The Natural start-up program in all environments must be linked with AMODE=31 .

  2. There must be no start-up errors from Natural as this will force Natural to try to write to the terminal or CMPRINT about the errors, which in turn can cause unpredictable results. This will also cause the Natural CGI request to fail.

Using the Natural Web Interface

Note:
This information is provided for compatibility reasons only. The recommended interface between Natural and the HTTP server is CALL HAANUPR.

Required Tasks

The Natural CGI processing, as described above, must be installed and working correctly, before sucessful operation of the Natural Web Interface is ensured.

Also ensure that the Natural parameter RPC=(size=32) is present in the string specified for the 'NATPARM' HTTP server parameter.

The programs NWWAPS and W3APSENV INPLed to the SYSWEB library are an integral part of the Natural Web Interface processing.

Invoking a Natural Web Interface Program

To invoke a Natural Web Interface program, use the standard browser URL 

http://ip-addr:port/natcgi/sysweb/nwwaps/library/subprogram

where

library is the Natural library where 'subprogram' resides
subprogram is the Natural subprogram you want to run

If running with Natural Security, you can also call NWWAPS by defining SYSWEB as a steplib of the library named in the URL. For example: 

http://ip-addr:port/natcgi/userlib/nwwaps/userlib/usercgi

If SYSWEB is defined in Natural Security as a steplib of USERLIB, then NWWAPS can be called. This is useful, as with Natural security installed, the NWWAPS program cannot call a subprogram from a different library (unless the subprogram is in a steplib of SYSWEB). That is, if the second library named in the URL is different to the first it will be ignored. It is possible to just specify the following: 

http://<ip-addr>:<port>/natcgi/userlib/nwwaps/usercgi

Any NWI subprogram that resides in a steplib of USERLIB can also be called.

Note:
All programs to be run using the Natural Web Interface must be cataloged; that is, they must be in object format.

Additional Notes

For additional information about the Natural Web Interface, refer to the Natural documentation.