Natural Web Server Extensions - Initialization File

#### Search Results

Search

# Natural Web Server Extensions - Initialization File

This section covers the following topics:

- General Information

- RPC Parameters

- Natural Web Server Extension Settings

- HTTP Server Variables

- Additional Variables

- Error Templates

## General Information

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.

## 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` | Note Use these parameters with SYSWEB only. Defines the amount of the transferred data. These parameters define the dimension of the parameter Out_Page of the IDL file. Used IDL File:
    DEFINE DATA PARAMETER
    1 Version-Nr (A15) In
    1 Log-Time (A30) In
    1 Out_Page (A RPC_INOUT_FORMAT 1:RPC_INOUT_LENGTH) In Out
    1 Out_Page_Count(I04) In Out
    1 Result (I04) Out END-DEFINE
`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.

## 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

- General Information
- RPC Parameters
- Natural Web Server Extension Settings
- HTTP Server Variables
- Additional Variables
- Error Templates