Natural Web Server Extensions - Initialization File

This section covers the following topics:

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.

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 ('...').

DCOM Parameters

This parameter is required for the communication with DCOM.

Parameter Description
DCOM_SERVER_NAME

Name of the called DCOM Server.
Specify only if the Natural Server is not running on the same computer.

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
	 -->| (Tab)
@ @
[ [
\ \
] ]
{ {
| /
} }

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>