
	Version 4.2.6 for Mainframes (Update)	SEARCH INDEX CONTENTS \| PDF PAGE PDF BOOKS \| HOME UP PREV NEXT

— Web Technology —

Natural Web Server Extensions - Initialization File

This section covers the following topics:

General Information
RPC Parameters
DCOM 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.

DCOM Parameters

This parameter is required for the communication with DCOM (on Windows platforms only).

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 2005] nwwcgi.exe 04.02.05 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
` `	`-->\| (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.

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 on variables, see http://hoohoo.ncsa.illinois.edu/cgi/env.html.

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.software-ag.de: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>

SEARCH INDEX CONTENTS | PDF PAGE PDF BOOKS | HOME UP PREV NEXT