Natural Web Server Extensions - Initialization File

#### Search Results

Search

# Natural Web Server Extensions - Initialization File

This section covers the following topics:

- About the Initialization File

- RPC Parameters

- PAL Parameters

- Natural Web Server Extension Settings

- Data Transfer Settings

- HTTP Server Variables

- Additional Variables

- Error Templates

## About the Initialization File

The Natural Web Server Extension processes runtime parameters from an initialization file. The executable file looks for an initialization file with the same name and extension .ini in the current working directory.

The names of the variables are not case sensitive, as all variables used on the WWW. Variables are limited to 72 characters; blanks are recognized as characters, so parameters can be specified multiple times.

## RPC Parameters

These parameters are required for communication with EntireX RPC.

Parameter | Description
--- | ---
`RPC_CLASS_NAME` | Defines the class of the service used. Always use RPC.
`RPC_ETB_ID_NAME` | Name of the EntireX Broker to be called.
`RPC_NO_LOGON` | Logon to the library specified at the URL. Default is 0.
`RPC_SERVER_NAME` | Name of the called Broker Service.
`RPC_SERVICE_NAME` | Defines the called service. Always use CALLNAT.
`RPC_TIME_OUT` | Defines the timeout for the call. Default is 7000.
`RPC_USER_ID` | User ID used for the RPC. If not specified, either `NWW_USER_ID` is used or `REMOTE_USER` is used, if `REMOTE_USER` is set to 1
`RPC_PASSWORD` | User password used for the RPC. If not specified `NWW_PASSWORD` is used.
`RPC_SSL_PARAMETER` | Connect string for RPC using SSL.

## PAL Parameters

These parameters are required for communication with the SPoD (PAL) interface.

Parameter | Description
--- | ---
`PAL_SERVER_NODE` | Name of the called PAL server node.
`PAL_SERVER_PORT` | Number of the called PAL server port.
`PAL_SESSION_PARAMETER` | If dynamic parameters are required for your server, specify the session parameters using single quotes ('...').

## Natural Web Server Extension Settings

This group of parameters defines the settings of the Natural Web Server Extension.

Parameter | Description
--- | ---
`ECHO_ENVIRONMENT` | This parameter is only useful if the default error page is used. If this parameter is specified and set to 1, equal to the `$NWW_ENVIRONMENT` of the user-defined error page, all environment variables will be written as comment lines to the error page.
`ERROR_LOG_FILE` | Defines a file for error logging. If this parameter is not specified, the log is disabled. Each log entry has the same layout and can easily be located in the error-log file by searching for the CGI string. Sample Log Entry: `[Thu Jun 28 10:51:19 2013] nwwcgi.exe 04.02.13 Win32: processing of /cgi-bin/nwwcgi.exe failed for Lib:{library} Sub:{subprogram} Path:{path_info}, for natweb.software-ag.de reason NWW0001 No subprogram and library specified.`
`ERROR_STDERR` | If this parameter is set to 1, all errors are logged via stderr. The location of the log file depends on the HTTP server used and the way it has been parameterized. See also `ERROR_LOG_FILE`. Some HTTP servers do not support the use of stderr.
`ERROR_TEMPLATE` | Defines an error template file. If this parameter is not specified, a default error page will be generated. See Error Templates below.
`NWW_INOUT_FORMAT` `NWW_INOUT_LENGTH` | Default values for the SYSWEB3 interface are: `NWW_INOUT_FORMAT=0` `NWW_INOUT_LENGTH=0`
`NWW_PASSWORD` | Defines the password for the user ID.
`NWW_PATH_INFO` | To test the Natural Web Server Extension in stand-alone mode (test environment), set this parameter to specify the library and program name. If you use the Natural Web Server Extension in the regular mode (with HTTP-Server) you must disable this parameter. Example: `NWW_PATH_INFO=/syshtml/nat-env`
`NWW_PATHINFO_PREFIX` | This parameter can only be used in conjunction with the ISAPI interface. If the interface is defined as application mapping (e.g. for directory nww and the extension .nww), the `PATH_INFO` variable delivers a prefixed URL with directory and file name (e.g. /nww/my.nww/sysweb/nat-env). This prefix (shown in italics) has to be removed. Use this parameter to remove the specified prefix. Example: `NWW_PATHINFO_PREFIX=/nww/my.nww`
`NWW_OUT_CSS` | Replaces the strings with the specific character(s):
String | Character
`&#09;` | `-->| (Tab)`
`&#64;` | `@`
`&#91;` | `[`
`&#92;` | `\`
`&#93;` | `]`
`&#123;` | `{`
`&#124;` | `/`
`&#125;` | `}`
This setting can be useful if cascading style sheets are used and the RPC server is placed on a computer which uses the EBCDIC code. Default is 0. Use 1 to activate.
`NWW_OUT_CSS_TRANSLATE` | Replaces the specified characters with the corresponding hexadecimal values: (Default value for ASCII)
Character | Hexadecimal value
`-->| (Tab)` | `09`
`@` | `40`
`[` | `5B`
`\` | `5C`
`]` | `5D`
`{` | `7B`
`|` | `7C`
`}` | `7D`
Example for English EBCDIC (Code Page 37): `#(tab), @, [, \, ], {, |, }` `NWW_OUT_CSS_TRANSLATE=05,7C,AD,61,BD,C0,4F, D0`
`NWW_USER_ID` | User ID used for the RPC.
`NWW_RETRY` | If an error (NAT3009 Transaction aborted) occurs, this parameter defines how often the program will be called again. Default is 3.
`INI_RELOAD` | Load initialization file only once during the first call. Not for CGI interface. Default is 1.
`REMOVE_USER_DOMAIN` | IIS server on NT delivers as `REMOTE_USER` the username prefixed with the name of the domain the user belongs to. Natural can only handle user names with a maximum length of 8 characters. If `USE_REMOTE_USER` is set to 1 and `REMOVE_USER_DOMAIN` is set to 1 also, the used domain name from the given `REMOTE_USER` name is removed. This means the information after the last "/" is delivered to Natural as the user name.
`TRACE_FILE` | If a file name is specified, the last pages returned to the HTTP server will be saved to this file. If this parameter is specified, no output is written.
`USE_REMOTE_USER` | Replace the `RPC_USER_ID` with the given `REMOTE_USER`. Set to 1 to activate it.

## Data Transfer Settings

This group of parameters defines the data transfer to the Natural server.

Parameter | Description
--- | ---
`SETMIMETYPE` | This parameter defines the transfer type for an incoming mime-type. The definition contains the name of a mime-type and the appropriate transfer type. The mime-type can contain asterisks as wildcard for one or any character. The application always uses the first matching mime-type. Valid transfer types are `binary` or `alpha`. Examples: `SETMIMETYPE=text/*;*charset*=*utf-16 binary` `SETMIMETYPE=text/* alpha` `SETMIMETYPE=image/svg alpha` `SETMIMETYPE=image/* binary` `SETMIMETYPE=multipart/form-data* binary` `SETMIMETYPE=* alpha` Note The line `SETMIMETYPE=* alpha` defines the default setting, for all unknown mime-types, if not set, `alpha` is used.

## HTTP Server Variables

All HTTP server variables that are to be transferred to the called program must be specified. To do this, specify the variable `ENV` with the name of the variable to be transferred. The `ENV` variable can be specified multiple times.

Some useful variables:

`ENV=REMOTE_HOST`
`ENV=REMOTE_ADDR`
`ENV=SCRIPT_NAME`
`ENV=HTTP_REFERER`
`ENV=HTTP_HOST`
`ENV=HTTP_COOKIE`

For further information see https://docs.microsoft.com/en-us/iis/web-dev-reference/server-variables.

## Additional Variables

With the Natural Web Server Extension, it is possible to transfer additional variables to the called program. To do this, specify the variable SETENV with the name of the variable followed by := and the value to be transferred. The SETENV variable can be specified multiple times.

Example:
`SETENV=PICTURES:=/pictures`

## Error Templates

### Default Error Report

If parameter ERROR TEMPLATE is not specified, a default is used.

This is an example of a default error report:

nwwcgi.exe Error Report
Natural Web Interface NWW5100c Win32
The following error has been logged in the error log file: |
/cgi-bin/nwwcgi.exe: | `processing of subprogram/method NAT-INFO` `at library/class SYSWEB failed.`
reason: |
    NWW0011 ERX error 80010014 occurred.

      Severity    = Error
      Facility    = 65536
      Returncode  = 20
      Subfacility = 3
      Location    = 0

      Message:
      ERX_E_SERVICE_NOT_AVAILABLE - ETB error code 02150148
for: | `pcnatweb.softwareag.com:80`
path: | `/sysweb/nat-info`
NWW Error - Fri Mar 15 10:20:28 2005 | Natural

### Specifying Your Own Error Template

You can also specify your own error template. The error template is basically a normal return page. As for all return pages, the content type must be set. The only addition is the replacement of variables. To do this, specify the environment variable beginning with a $ sign. See Example of an Error Template below.

The following "environment variables" are additionally available for error templates:

Environment Variable | Description
--- | ---
`NWW_LOGTIME` | Time and date the error will be logged if an `ERROR_LOG_FILE` is specified.
`NWW_VERSION` | Version number of the Natural Web Server Extension.
`NWW_RUN` | Name of the program that was called.
`NWW_ERROR` | Number of the error that has occurred.
`NWW_LIBRARY` `NWW_CLASS` | Name of the library/class that was called.
`NWW_SUBPROGRAM` `NWW_METHOD` | Name of the subprogram/method that was called.
`NWW_ENVIRONMENT` | All environment variables will be written as comment lines to the error page.

### Example of an Error Template

    <!DOCTYPE HTML PUBLIC '-//W3C//DTD HTML 3.2//EN'>
    <HTML>
    <HEAD>
     <META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
     <TITLE>$NWW_RUN Error Report - $NWW_LOGTIME</TITLE>
    </HEAD>
    <BODY bgcolor="#FFFFFF" text="#000000">
    <TABLE border="0" width="100%" cellspacing="0" cellpadding="5">
     <TR bgcolor="#CCFFCC">
       <TD><H2 align="center">
            $NWW_RUN Error Report
         </H2>
         <P align="center">
         <I><SMALL>Natural Web Server Extension Interface: $NWW_VERSION</SMALL></I></TD>
     </TR>
     <TR>
       <TD><B>The following error has been logged in the error log file:</B></TD>
     </TR>
    </TABLE>
    <TABLE border="0" width="100%" cellspacing="15" cellpadding="0">
     <TR valign="top">
       <TD align="right"><B>$SCRIPT_NAME:</B></TD>
       <TD><TT>processing of subprogram/method <B>$RPC_SUBPROGRAM</B><BR>
         at library/class <B>$RPC_LIBRARY</B> failed.</TT></TD>
     </TR>
     <TR valign="top">
       <TD align="right"><B>reason:</B></TD>
       <TD><PRE>$RPC_ERROR
    </PRE>
       </TD>
     </TR>
     <TR valign="top">
       <TD align="right"><B>for:</B></TD>
       <TD><TT>$SERVER_NAME:$SERVER_PORT</TT></TD>
     </TR>
     <TR valign="top">
       <TD align="right"><B>path:</B></TD>
       <TD><TT>$PATH_INFO</TT></TD>
     </TR>
    </TABLE>
    <TABLE border="0" width="100%" cellspacing="0" cellpadding="5">
     <TR bgcolor="#CCFFCC">
       <TD>NWW Error Template - $NWW_LOGTIME</TD>
       <TD align="right">Natural</TD>
     </TR>
    </TABLE>
    <P>
    $NWW_ENVIRONMENT
    </BODY></HTML>

### On this page

- About the Initialization File
- RPC Parameters
- PAL Parameters
- Natural Web Server Extension Settings
- Data Transfer Settings
- HTTP Server Variables
- Additional Variables
- Error Templates