Configuring the Natural Web I/O Interface Server

This document describes how to configure a Natural Web I/O Interface server.

Where applicable, specific information for z/OS, z/VSE or BS2000 is provided.

The following topics are covered:

• Configuration Requirements for z/OS

• Configuration Requirements for z/VSE

• SMARTS Configuration File for BS2000

• Web I/O Interface Server Configuration File for z/OS and z/VSE

• Web I/O Interface Server Configuration Parameters

• Web I/O Interface Server Configuration File Example

• Web I/O Interface Server Data Sets for z/OS, z/VSE

• Web I/O Interface Server User Exits

Configuration Requirements for z/OS

The following topics are covered:

• Language Environment Parameter Settings

• External Security Configuration

• SSL Support

Language Environment Parameter Settings

A Natural Web I/O Interface server requires the following z/OS language environment parameter configuration:

ENVAR(TZ=CET-1DST) CET

You can set the z/OS language environment parameters:

• With the PARM parameter specified in the EXEC card of the Natural Web I/O Interface server startup job. The length of the options is limited by the maximum length of the PARM parameter.

• Assemble an LE/370 runtime option module CEEUOPT and link it to the Natural Web I/O Interface server load module.

External Security Configuration

If you configure the Web I/O Interface server to impersonate the Web I/O Interface clients in the server (Web I/O Interface server configuration parameter SECURITY_MODE=IMPERSONATE or IMPERSONATE_LOCAL), the Web I/O Interface server must run "program-controlled". Under RACF, the following definitions are required for the Web I/O Interface server:

• The resource BPX.SERVER must be defined and the Web I/O Interface server account must have READ access to this resource.

• The LOAD data sets defined in the Web I/O Interface server startup job definition must be defined to the program class "**".

  ralt program ** addmem('natural load library') uacc(read)
  ralt program ** addmem('NWO load library'//NOPADCHK) uacc(read)
  ralt program ** addmem('user load library'//NOPADCHK) uacc(read)
  

• SETR WHEN(PROGRAM) REFRESH

Additionally, each client connecting to the server must be defined in RACF and must be granted to use the z/OS Unix System Services.

SSL Support

• SSL over AT-TLS
• Maintenance of Certificates under z/OS
• Using RACF Key Rings
• Using Key Databases
• How to configure TCP/IP for AT-TLS?
• How to Verify AT-TLS Configuration?
• Frequently Asked Questions
• Generation of a Natural Web I/O Interface Server Certificate

SSL over AT-TLS

SSL support for the Natural Web I/O Interface server is based on the z/OS Communication Server component AT-TLS (Application Transparent-Transport Layer Security).

AT-TLS provides TLS/SSL encryption as a configurable service for sockets applications. It is realized as an additional layer on top of the TCP/IP protocol stack, which exploits the SSL functionality in nearly or even fully transparent mode to sockets applications. AT-TLS offers three modes of operation. See z/OS Communications Server, IP Programmer’s Guide and Reference. Version 1, Release 9, Chapter 15, IBM manual SC31-8787-09.

These modes are:

• Basic

  The sockets application runs without modification in transparent mode, unaware of performing encrypted communication via AT-TLS. Thus legacy applications can run in secured mode without source code modification.

• Aware

  The application is aware of running in secured mode and is able to query TLS status information.

• Controlling

  The sockets application is aware of AT-TLS and controls the use of AT-TLS encryption services itself. This means, the application is able to switch between secured and non secured communication.

Natural Web I/O Interface server uses the Basic mode for its SSL implementation. That is, a server configured as SSL server rejects requests from non-secured clients.

Maintenance of Certificates under z/OS

Certificates, which are to be used with AT-TLS, can be maintained in two ways under z/OS. They are stored either in RACF key rings or in key databases, which are located in the z/OS UNIX file system. Which of these proceedings actually applies is defined in the AT-TLS Policy Agent Configuration file for the z/OS TCP/IP stack, which is used by the Natural HTTPS client.

IBM delivers a set of commonly used CA root certificates with each z/OS system delivery. If key rings are going to be used to hold server certificates, those root certificates must be manually imported into the key rings by the system administrator. If IBM delivers newer replacements for expired root certificates, all affected key rings have to be updated accordingly.

Unlike key rings, key databases contain the current set of root certificates automatically after they have been newly created. However, the need for maintaining always the latest set of root certificates applies to the key database alternative as well.

Using RACF Key Rings

In RACF, digital certificates are stored in so called key rings. The RACF command RACDCERT is used to create and maintain key rings and certificates, which are contained in those key rings.

See z/OS Security Server RACF Security Administrator’s Guide, IBM manual SA22-7683-11, and z/OS Security Server RACF Command Language Reference, IBM manual SA22-7687-11.

Using Key Databases

Alternatively to RACF, certificates can be kept in key databases, which reside in the z/OS UNIX services file system. For the creation and maintenance of key databases, the GSKKYMAN utility has to be used.

See z/OS Cryptographic Services PKI Services Guide and Reference, IBM manual SA22-7693-10.

How to configure TCP/IP for AT-TLS?

Proceed as follows:

1. In the TCP/IP configuration file, set the option TTLS in the TCPCONFIG statement.

2. Configure and start the AT-TLS Policy Agent. This agent is called by TCP/IP on each new TCP connection to check if the connection is SSL.

3. Create the Policy Agent file containing the AT-TLS rules. The Policy Agent file contains the rules to stipulate which connection is SSL.

See also z/OS Communications Server: IP Configuration Guide, Chapter 18 Application Transparent Transport Layer Security (AT-TLS) data protection.

The Sample Policy Agent file defines the server with the job name starting with NWODEV and listening at port 4843 to use SSL.

The sample expects the certificate database on the HFS file /u/admin/CERT.kdb.

TTLSRule                          ConnRule01~1
{
  LocalAddrSetRef                 addr1
  RemoteAddrSetRef                addr1
  LocalPortRangeRef               portR1
  RemotePortRangeRef              portR2
  Jobname                         NWODEV*
  Direction                       Inbound
  Priority                        255
  TTLSGroupActionRef              gAct1~NWO_Server
  TTLSEnvironmentActionRef        eAct1~NWO_Server
  TTLSConnectionActionRef         cAct1~NWO_Server
} 
TTLSGroupAction                   gAct1~NWO_Server
{ 
  TTLSEnabled                     On
} 
TTLSEnvironmentAction             eAct1~NWO_Server
{ 
  HandshakeRole                   Server
  EnvironmentUserInstance         0
  TTLSKeyringParmsRef             keyR1
} 
TTLSConnectionAction              cAct1~NWO_Server
{ 
  HandshakeRole                   Server
  TTLSCipherParmsRef              cipher1~AT-TLS__Silver
  TTLSConnectionAdvancedParmsRef  cAdv1~NWO_Server
} 
TTLSConnectionAdvancedParms       cAdv1~NWO_Server
{ 
  CertificateLabel                NDV_TEST_CERT
} 
TTLSKeyringParms                  keyR1
{ 
  Keyring                         /u/admin/CERT.kdb
  KeyringStashFile                /u/admin/CERT.sth
} 
TTLSCipherParms                   cipher1~AT-TLS__Silver
{
  V3CipherSuites                  TLS_RSA_WITH_DES_CBC_SHA
  V3CipherSuites                  TLS_RSA_WITH_3DES_EDE_CBC_SHA
  V3CipherSuites                  TLS_RSA_WITH_AES_128_CBC_SHA
} 
IpAddrSet                         addr1
{ 
  Prefix                          0.0.0.0/0
} 
PortRange                         portR1
{ 
  Port                            4843
} 
PortRange                         portR2
{ 
  Port                            1024-65535
}

How to Verify AT-TLS Configuration?

Check Policy-Agent job output JESMSGLG for:

EZZ8771I PAGENT CONFIG POLICY PROCESSING COMPLETE FOR <your TCP/IP address space>: TTLS

This message indicates a successful initialization.

Check Policy-Agent job output JESMSGLG for:

EZZ8438I PAGENT POLICY DEFINITIONS CONTAIN ERRORS FOR <your TCP/IP address space>: TTLS

This message indicates errors in the configuration file. Check the syslog.log file for further information.

Does the configuration rule cover the server?

Try to connect the server and check syslog.log for:

EZD1281I TTLS Map   CONNID: 00018BED LOCAL: 10.20.91.61..4843 REMOTE: 10.20.160.47..4889 JOBNAME: NWODEVvr USERID: NWOSRV TYPE: InBound STATUS: Enabled RULE: ConnRule01~1 ACTIONS: gAct1 eAct1~NWO_Server cAct1~NWO_Server

The above entry indicates that the connection to Port 4843 is SSL enabled.

Frequently Asked Questions

Is there more information about problem determination?

See also z/OS V1R8.0 Comm Svr: IP Diagnosis Guide: 3.23, Chapter 29 Diagnosing Application Transparent Transport Layer Security (AT-TLS)

How to switch on P-agent trace?

See Comm Svr: IP Configuration Reference, Chapter 20 Syslog deamon and Comm Svr: IP Configuration Guide, Chapter 1.5.1 Configuring the syslog daemon (syslogd)

Error at connection establishment

Find return code RC and corresponding GSK_ function name in P-agent trace.

See System SSL Programming and locate the RC in Chapter 12.1 SSL Function Return Codes.

Sample trace with trace=255:

EZD1281I TTLS Map   CONNID: 00002909 LOCAL: 10.20.91.61..1751 REMOTE: 10.20.91.117..443 JOBNAME: KSP USERID: KSP TYPE: OutBound STATUS: A
EZD1283I TTLS Event GRPID: 00000003 ENVID: 00000000 CONNID: 00002909  RC:    0 Connection Init 
EZD1282I TTLS Start GRPID: 00000003 ENVID: 00000002 CONNID: 00002909 Initial Handshake ACTIONS: gAct1 eAct1 AllUsersAsClient HS-Client   
EZD1284I TTLS Flow  GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:    0 Call GSK_SECURE_SOCKET_OPEN - 7EE4F718 
EZD1284I TTLS Flow  GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:    0 Set GSK_SESSION_TYPE -  CLIENT 
EZD1284I TTLS Flow  GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:    0 Set GSK_V3_CIPHER_SPECS -  090A2F 
EZD1284I TTLS Flow  GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:    0 Set GSK_FD - 00002909 
EZD1284I TTLS Flow  GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:    0 Set GSK_USER_DATA - 7EEE9B50 
EZD1284I TTLS Flow  GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:  435 Call GSK_SECURE_SOCKET_INIT - 7EE4F718 
EZD1283I TTLS Event GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:  435 Initial Handshake 00000000 7EEE8118  
EZD1286I TTLS Error GRPID: 00000003 ENVID: 00000002 CONNID: 00002909 JOBNAME: KSP USERID: KSP RULE: ConnRule01  RC:  435 Initial Handshake
EZD1283I TTLS Event GRPID: 00000003 ENVID: 00000002 CONNID: 00002909  RC:    0 Connection Close 00000000 7EEE8118 

Generation of a Natural Web I/O Interface Server Certificate

Under z/OS, SSL certificates can be produced with the UNIX System Services utility GSKKYMAN. The following steps have to be executed for the production of a new certificate, which is to be used for the SSL secured communication between Natural Web I/O Interface client and server:

1. Start a shell session out of TSO or connect via telnet to the z/OS UNIX shell.

2. Start GSKKYMAN.

3. Create a new – or open an existing key database.

4. Create a self-signed certficate, for example, of type "User or server certificate with 2048-bit RSA key".

5. Export the certificate to a (HFS) file. Choose Base64 ASN.1 DER as export format.

This generated file can now be copied to the Natural Web I/O Interface client(s) using FTP with ASCII transfer format. On the client side, the received file should be stored with the file name suffix .CER. The certificate can now be used by the Natural Web I/O Interface client.

If certificates are kept in a RACF key ring, the generated certificate has to be imported into the appropriate key ring using the RADCERT command.

Certificates, which are produced on a different platform, for example, on a Windows PC, can be imported into a RACF key ring or into a key database as well.

Detailed information about the use of the GSKKYMAN utility can be found in the IBM Communications server documentation, e.g in the following manuals:

z/OS Communications Server IP Configuration Guide Version 1 Release 2 (IBM manual SC31-8775-01

or

z/OS Communications Server Cryptographic Services System Secure Sockets Layer Programming (IBM manual SC24-5901-04).

For the generation of certificates under Windows, a free downloadable utility named Ikeyman is available on several websites. Ikeyman is an IBM product as well and maps the functionality of GSKKYMAN to the Windows platform.

Configuration Requirements for z/VSE

The following topics are covered below:

• SMARTS SYSPARM Parameters

• SYSPARM Example for the Natural Web I/O Interface Server

SMARTS SYSPARM Parameters

The Natural Web I/O Interface server requires the following SMARTS SYSPARM parameters:

You can set the SMARTS SYSPARM parameters in the file SMARTS.CONFIG which must reside on one of your accessed disk.

SYSPARM Example for the Natural Web I/O Interface Server

For z/VSE:

* ------------------ ADABAS PARMS -----------------------------* 
ADACALLS=20 CALLS BEFORE ROLL
ADASVC=47 ADABAS SVC NUMBER
* ------------------ BUFFERPOOL PARMS -------------------------*
BUFFERPOOL=(064,030,20,ANY)
BUFFERPOOL=(128,064,64,ANY)
BUFFERPOOL=(256,010,10,ANY)
BUFFERPOOL=(512,032,10,ANY)
BUFFERPOOL=(1K,032,32,ANY)
BUFFERPOOL=(6K,005,02,ANY)
BUFFERPOOL=(8K,016,16,ANY)
* ------------------ ROLLING PARMS ----------------------------*
ROLL-BUFFERPOOL=(048K,04,04,DS) ESA DATA SPACE
ROLL-BUFFERPOOL=(064K,04,04,DS) ESA DATA SPACE
ROLL-BUFFERPOOL=(128K,04,04,DS) ESA DATA SPACE
ROLL-BUFFERPOOL=(256K,04,04,DS) ESA DATA SPACE
ROLL-BUFFERPOOL=(800K,02,02,DS) ESA DATA SPACE
*
* ------------------ NWO Server to launch at startup ----------*
* STARTUPPGM='NATRNWO NWOS1'
*

*
TASK-GROUP=(DEFAULT,6)
THREAD-GROUP=(DEFAULT,(DEFAULT,252,06,15,28,N))
*
THSIZEABOVE=1024
*
SERVER=(NCFNATvr,NCFNATvr)   NATvr BUFFER POOL
*
CDI_DRIVER=('TCPIP,PAACSOCK,MINQ=10,MAXQ=20')
*
RESIDENTPAGE=NATRNWO
RESIDENTPAGE=NWONCFvr
RESIDENTPAGE=NATNUCvr
RESIDENTPAGE=NATMONI

Where vr is the current product version and release number.

Where vr or vrs is the current product version and release number.

SMARTS Configuration File for BS2000

The Natural Web I/O Interface server reads its configuration parameters from a file which resides as an S-type member in the NWO-JOBS library.

Notes:

1. Translation tables are used to convert characters when sending or receiving data to or from a host while working with a terminal emulation, see Adapting Translation Tables for Natural Web I/O Interface Server under BS2000 in the Natural for Windows (Natural Studio) documentation.
2. The SMARTS configuration is contained as an S-type member which resides in the NWO-JOBLIB. It has to be passed to the system in the startup procedure parameter NWO-SYSPARM.

The following topics are covered below:

• SMARTS SYSPARM Parameters

• SMARTS Server Environment Configuration Parameters

• SMARTS Sample Configuration

SMARTS SYSPARM Parameters

The Natural Web I/O Interface server requires the following SMARTS SYSPARM parameters:

Note:
The parameter values printed in italics (SERVERID, JOBNAME, PFS, nnn, etc.) are to be specified by the user.

SMARTS Server Environment Configuration Parameters

The following general parameter descriptions are adapted excerpts from the original SMARTS documentation. The text is provided for background information only. Therefore, not all of the information contained therein applies to the Natural Web I/O Interface server under SMARTS on BS2000.

• ADASVC
• RESIDENTPAGE
• SERVER
• TASK-GROUP
• THREAD-GROUP
• THSIZEABOVE
• WORKLOAD-AVERAGE, WORKLOAD-MAXIMUM

ADASVC

This parameter is for internal use only. Do not change the Adabas SVC number.

RESIDENTPAGE

All modules are assumed to be reentrant, and are loaded into the address space automatically at first reference.

The program must be fully reentrant. If it is not marked reentrant, a warning message is issued on the operator's console at SMARTS initialization time.

The program must reside in the APS-LIB or in the NWO-MOD library of the SMARTS initialization procedure.

SERVER

The server-information has the format

(serv-id,init-mod,p1,p2,pn)

- where

Specifying the SERVER parameter causes SMARTS to build a server directory entry (SDE) for the specified server and pass control to the initialization routine specified to initialize the server.

TASK-GROUP

- where

Important:
For SMARTS, only the TASK-GROUP DEFAULT is available. Software AG strongly recommends that you use the default definition. If other products running on SMARTS require changes to the defaults or allow the definition of their own TASK-GROUPs, that will be indicated in the relevant documentation.

Notes:

1. A maximum of 8 task groups may be defined.
2. Task-group names are converted to uppercase prior to being processed; therefore, a parameter entered in lowercase is treated as, and appears in, uppercase letters.
3. If more than one specification appears for a task group, the last valid specification is used.
4. The task group DEFAULT must always exist in the system. If it is not explicitly defined by the installation, the task group is built by the system with the default values.
5. Note that the total number of tasks to be attached must not exceed the MAXTASKS specification. This is not checked until the task groups are being built; however, exceeding the value leads to task-group allocation errors as against parameter errors.

THREAD-GROUP

The format for the value is

(grp,(sub,size,num,cpu, real, key),...,(sub,size,num,cpu,real,key))

- where

Note:
The user may also specify a value in the range 1 to 15 inclusive to allocate a thread to that key explicitly.

The default value is

THREAD-GROUP=(DEFAULT,($DEFAULT,8,num))

- where num is calculated dynamically based on the size of the installation.

Important:
For SMARTS, only THREAD-GROUP DEFAULT is available. Software AG strongly recommends that you use the default definition. If other products running on SMARTS require changes to the defaults or allow the definition of their own THREAD-GROUPs, that will be indicated in the relevant documentation.

Notes:

1. A maximum of 8 thread groups may be defined.
2. A maximum of 8 subgroups can be allocated per thread group. The subgroups may be defined on one line or on different lines. When a second THREAD-GROUP statement is used, the same group name must be specified to relate the subgroup entries.
3. Thread group and subgroup names are converted to uppercase prior to being processed; therefore, a parameter entered in lowercase is treated as, and appears in, uppercase letters.
4. If more than one specification appears for a thread subgroup of a thread group, the last valid specification is used.
5. The amount of storage specified on the THSIZEABOVE parameter is allocated above the line for each thread defined as a result of the THREAD-GROUP parameter.
6. The thread group DEFAULT must always exist in the system. If it is not explicitly defined by the installation, the thread group is built by the system with the default values. If it is defined, the system ensures that a thread subgroup with a thread size at least as large as that required by DEFAULT is allocated. If not, the system allocates an additional subgroup for the group. If too many subgroups have been defined, the last one defined is overwritten to allow for the default specification.
7. The keyword data is processed from left to right. If more than one thread subgroup is defined on one line and the line contains an error, even if an error message is issued for the line, any subgroups processed up to the error are still accepted. That is to say, if the first subgroup is correct and the second is not, an error message is issued but the first thread subgroup is defined while the second and subsequent specifications in the same statement are ignored.

THSIZEABOVE

WORKLOAD-AVERAGE, WORKLOAD-MAXIMUM

The WORKLOAD-AVERAGE parameter specifies a normal workload value, and the WORKLOAD-MAXIMUM parameter specifies a maximum workload value. SMARTS uses these values togther with the region sizes above and below the 16 MB line to configure itself.

These parameters are not required, but tuning them may improve performance.

SMARTS Sample Configuration

ADASVC=249
DATA-MAXIMUM=160   
CODE-MAXIMUM=34
THSIZEABOVE=4096      
THREAD-GROUP=(DEFAULT,(DEFAULT,0,4)
TASK-GROUP=(DEFAULT,2)  
WORKLOAD-AVERAGE=8 
WORKLOAD-MAXIMUM=40
RESIDENTPAGE=NATSOCK
RESIDENTPAGE=NATMONI
RESIDENTPAGE=NATRNWO
RESIDENTPAGE=NCFSERV
RESIDENTPAGE=NvrLPRRB
*********************SERVERS ****************************
SERVER=(POSIX,PAENKERN,CONF=PAANCONF)
SERVER=(NCFNATvr,NCFNATvr,1,2048,2,100,4,2048)
SERVER=(NWONATv,PAENAPPS,NATRNWO,'NWOS01')
*********************CDI-DRIVERS*************************
CDI_DRIVER=('file,PA2SFIO,SIOTSK=HSFSIO')
CDI_DRIVER=('console,PAANCNIO')
CDI_DRIVER=('tcpip,PAAZSOCK,SOCKTSK=HSSOCTA2,TRACE=1')
CDI_DRIVER=('CIO,PAAQBIO,PFSTSK=HSPFS,TRACE=N')              
CDI_DRIVER=('PFS,PAANPFS,LRECL=4096,CONTAINER=CIO:NWO/ROOT/SERVER1/')
MOUNT_FS=('PFS://','/')

Web I/O Interface Server Configuration File for z/OS and z/VSE

A configuration file is allocated to the name <serverid>C (for example, NWOS1C) or STGCONFG alternatively.

The configuration file is a text file located on a data set or on an HFS file under z/OS and a librarian member under z/VSE.

The configuration file contains the server configuration parameters in the form of a keyword=value syntax. In addition, it may contain comments whose beginning is marked with a hash symbol (#).

See also the Web I/O Interface Server Configuration File Example shown below.

Web I/O Interface Server Configuration Parameters

The following Web I/O Interface server configuration parameters are available:

• COMPATIBILITY_MODE

• FORCE_IPV4

• FRONTEND_NAME

• FRONTEND_OPTIONS

• FRONTEND_PARAMETER

• HANDLE_ABEND

• HOST_NAME

• HTPMON_ADMIN_PSW

• HTPMON_PORT

• HOST_NAME

• IGNORE_PRESENT_SERVER

• INITIAL_USERID

• KEEP_TCB

• O4I

• PASSWORD_MIXEDCASE

• PORT_NUMBER

• SECURITY_MODE

• SESSION_PARAMETER

• THREAD_NUMBER

• THREAD_SIZE

• TRACE_FILTER

• TRACE_LEVEL

• UPPERCASE_SYSTEMMESSAGES

COMPATIBILITY_MODE

The current version of NWO presumes to run with the most recent version of Natural. An error NAT7729 NWO and Natural version do not agree is issued when running with older Natural versions. This is because NWO must negotiate a subset of functionality with the client at a time when the involved Natural version is not already known.

If you want to run NWO with a previous version of Natural, you can set this parameter to YES. It is recommended that you leave this parameter at its default value if you intend to run your NWO with the most recent version of Natural, because in this case COMPATIBILITY_MODE=YES would unnecessarily limit the functionality.

Example:

COMPATIBILITY_MODE=YES

FORCE_IPV4

This parameter is only available with Natural Web I/O Interface Version 8.3 or above and applies to z/OS and z/VSE.

This parameter allows you to enforce the use of communication method IPV4.

FRONTEND_NAME

This configuration parameter specifies the name of the Natural front-end to be used to start a Natural session. The front-end resides on a PDS member.

No default value is provided.

Example:

FRONTEND_NAME=NATvrsSV

FRONTEND_OPTIONS

This configuration parameter applies to z/OS only.

The values of this configuration parameter may be used to specify additional options for the Natural front-end.

You may combine the above options as desired in that you add their values and set the result as shown in the example below.

Example:

FRONTEND_OPTIONS=07

The setting in this example enables the Options 01, 02 and 04.

FRONTEND_PARAMETER

This configuration parameter applies to z/OS only.

This optional configuration parameter contains additional Natural front-end parameters as specified in the Startup Parameter Area.

FRONTEND_PARAMETER = 'MSGCLASSX       '

No default value is provided.

For further information, refer to the section Natural in Batch Mode in the Natural Operations for Mainframe documentation.

Example:

FRONTEND_PARAMETER='MSGCLASSX       '

The setting in this example specifies that the default output class for CMPRINT is "X".

HANDLE_ABEND

If an abend occurs in the server processing outside the Natural processing the abend is not trapped by the Natural abend handling. For this reason the NWO server has its own abend recovery.

It is recommended that you leave this parameter on its default value in order to limit the impact of an abend to a single user. If you set the value of this parameter to NO, any abend in the server processing terminates the complete server processing. That is, it affects all users running on that server.

Example:

HANDLE_ABEND=NO

HOST_NAME

This configuration parameter applies to z/OS and z/VSE.

This optional configuration parameter is necessary only if the server host supports multiple TCP/IP stacks.

No default value is provided.

Example:

HOST_NAME=node1

or

HOST_NAME=157.189.160.55

HTPMON_ADMIN_PSW

This configuration parameter applies to z/OS, z/VSE and BS2000.

This configuration parameter defines the password required for some monitor activities (e.g. Terminate Server) performed by the HTML Monitor Client.

No default value is provided.

Example:

HTPMON_ADMIN_PSW=GHAU129B

HTPMON_PORT

This configuration parameter applies to z/OS, z/VSE and BS2000.

A Web I/O Interface server can be configured to host an HTTP monitor task which serves the HTML Monitor Client running in a web browser. It is not required to run this monitor task on each server. A single task allows you to monitor all servers running at one node.

This configuration parameter defines the TCP/IP port number under which the server monitor task can be connected from a web browser.

No default value is provided.

Example:

HTPMON_PORT=3141

HOST_NAME

This configuration parameter applies to z/VSE and BS2000.

This configuration parameter defines the host name of the Web I/O Interface server.

IGNORE_PRESENT_SERVER

This configuration parameter applies to z/OS and z/VSE in conjunction with the Web I/O Interface server CICS Adapter.

A Web I/O Interface (NWO) server allocates a so-called "server environment" which contains the server dependent common resources.

This environment is unique for each NWO server and relates to the server name. If an NWO server with Web I/O Interface Server CICS Adapter ends abnormally, it might leave a stuck NWO server environment within the CICS region. This causes that a restart of the server fails with error message NAT9913.

If you start an NWO server with IGNORE_PRESENT_SERVER=YES, it might damage an already running server which is using the same server name and the same CICS region.

Example:

IGNORE_PRESENT_SERVER=YES

INITIAL_USERID

At server initialization, the Natural Web I/O Interface server creates a temporary Natural session to obtain the properties of the installed Natural environment.

This configuration parameter specifies the user ID to be used for this Natural session.

Example:

INITIAL_USERID=NWOINITU

See also Web I/O Interface clients must be defined to Natural Security in the operating-system-specific Natural Web I/O Interface server Installation section.

KEEP_TCB

This configuration parameter applies to z/OS only.

By default, the remote Natural session of a mapped environment terminates its TCB whenever you switch the focus within Natural Studio to a different mapped environment. If you toggle the focus back, the remote session is dispatched using a different TCB.

The maximum number of active TCBs is equal to the number of connected clients.

The configuration parameter KEEP_TCB specifies whether the remote Natural session should use the same TCB during its entire lifetime. This is required if you use Adabas and the Adabas parameter ADANAME is set to ADAUSER or if you want to access DB2. It could also be required if you access 3GL programs which need to be executed under the same TCB for successive calls.

Example:

KEEP_TCB=YES

O4I

Note:
This parameter is only available with Natural Web I/O Interface Version 8.3 or above.

This parameter allows you to collect server data for Optimize for Infrastructure.

Example:

O4I=YES

PASSWORD_MIXEDCASE

This configuration parameter applies to z/OS and z/VSE.

This parameter allows you to define whether passwords specified in the connection dialog are translated into upper case or not.

This parameter does only apply with SECURITY_MODE=IMPERSONATE, IMPERSONATE_LOCAL or IMPERSONATE_REMOTE.

Example:

PASSWORD_MIXEDCASE=YES

PORT_NUMBER

This configuration parameter defines the TCP/IP port number under which the server can be connected.

No default value is provided.

Example:

PORT_NUMBER=3140

Note:
Under BS2000, some port numbers are privileged and reserved for certain system services. Ask your BS2000 system administrator for the port number range available to you.

SECURITY_MODE

This configuration parameter applies to z/OS and z/VSE.

The Natural Web I/O Interface server offers a security concept that also covers the operating system resources. The client credentials are validated at the operating-system-depending security system and the client request is executed under the client's account data.

Using the SECURITY_MODE parameter, you can specify at which rank (in batch mode z/OS, z/VSE or under CICS) you want to impersonate the activities of a Web I/O Interface client.

No default value is provided.

Example:

SECURITY_MODE=IMPERSONATE

SESSION_PARAMETER

This optional configuration parameter defines session parameters that precede the parameter string specified in the connection dialog of the Natural Web I/O Interface client.

No default value is provided.

Example 1:

  SESSION_PARAMETER='NUCNAME=NATNUCvr' +
  'PROFILE=(NWOPARM,18006,48),ADAMODE=0,' +
  'BPI=(TYPE=NAT,SIZE=6044),BPI=(TYPE=EDIT,SIZE=2048)', + 
  'BPI=(TYPE=SORT,SIZE=1024)'

Example 2:

SESSION_PARAMETER=FNAT=(10,930)

The setting in the second example defines that every session on this Natural Web I/O Interface server is started with the session parameter FNAT=(10,930) appended to the user-specified parameters or the definitions in the configuration parameter DEFAULT_PROFILE.

THREAD_NUMBER

This configuration parameter applies to z/OS only.

This configuration parameter specifies the number of physical storage threads to be allocated by the Natural front-end, that is, the number of sessions that can be executed in parallel.

Note:
This parameter is obsolete when the Natural Web I/O Interface Server CICS Adapter or Natural Web I/O Interface Server IMS Adapter is used.

Example:

THREAD_NUMBER=5

THREAD_SIZE

This configuration parameter applies to z/OS only.

This configuration parameter specifies the size of each physical storage thread which contains the Natural session data at execution time.

Note:
This parameter is obsolete when the Natural Web I/O Interface Server CICS Adapter or Natural Web I/O Interface Server IMS Adapter is used.

Example:

THREAD_SIZE=800

TRACE_FILTER

This optional configuration parameter enables you to restrict the trace by a logical filter in order to reduce the volume of the server trace output, for example:

TRACE_FILTER="Client=(KSP P*)"

Each request of the user ID "KSP" and each request of the user IDs starting with a "P" are traced.

See Trace Filter in the section Operating the Natural Web I/O Interface Server.

TRACE_LEVEL

Example:

TRACE_LEVEL=0x00000011

or alternatively

TRACE_LEVEL=31+27

The setting in the example switches on Bits 31 and 27.

UPPERCASE_SYSTEMMESSAGES

This configuration parameter is used to enable or disable the translation of all NWO error messages and trace outputs to uppercase. This feature is for customers who are using character sets with no lowercase characters defined.

Web I/O Interface Server Configuration File Example

For z/OS:

 
# This is a comment
SESSION_PARAMETER=profile=(stgqa,10,930) fuser=(10,32) CFICU=ON
THREAD_NUMBER=2
THREAD_SIZE=700
FRONTEND_NAME=NATOSvrL       # and another comment
PORT_NUMBER=4811

Where vr is the current product version and release number.

For z/VSE:

# This is a comment
SESSION_PARAMETER=profile=(stgqa,10,930) fuser=(10,32) CFICU=ON
DEFAULT_PROFILE=DEFPROF
FRONTEND_NAME=NATNCF       # and another comment
PORT_NUMBER=4711

For BS2000:

SESSION_PARAMETER = 'NUCNAME=NvrLPRRB' +                             
  ' PROFILE=(NWOPARM,18006,58),ADAMODE=0,' +                         
  'FNAT=(18006,58),FUSER=(18006,19),FDIC=(18006,11),' +              
  'FSPOOL=(18006,58),FSEC=(18006,58),CFICU=ON,MENU=OFF,CP=EDF03IRV'  
THREAD_NUMBER = 3                                                    
THREAD_SIZE = 900                                                    
FRONTEND_OPTIONS = 0X01                                              
FRONTEND_NAME = NCFSERV                                              
PORT_NUMBER = 4811                                                   
MONITOR=Y       

Where vr is the current product version and release number.

Web I/O Interface Server Data Sets for z/OS, z/VSE

The Natural Web I/O Interface server requires the following data sets:

Alternately, you can qualify each data set name by the server ID. Under z/VSE, this is necessary if you want to start different Natural Web I/O Interface servers under a single SMARTS address space.

Web I/O Interface Server User Exits

The Natural Web I/O Interface server offers the following user exit:

User Exit NSECUX01

This user exit is applicable only when the parameter SECURITY_MODE is set to IMPERSONATE_LOCAL or IMPERSONATE.

This user exit allows you to adapt the user ID used for the RACF login. It is useful if the RACF user IDs and the user IDs used in Natural differ according to a standardized rule. For example, each RACF user ID is the corresponding Natural user ID preceded by two dollar signs ($$).

If the exit (the load module NSECUX01) is found in the NWO load library concatenation, it is called before the user is validated against RACF.

The following parameters are passed to the exit:

The exit is called using standard linkage conventions.

Sample user exit implemented in C:

#include <string.h>
#include <stdio.h>

#  pragma linkage (NSECUX01, FETCHABLE)

void NSECUX01(char sUid[64])
{
char sUidTemp[64];

  printf("Uex got usid:%s\n", sUid);
  strcpy(sUidTemp, sUid);
  sprintf(sUid, "$$%s", sUidTemp);
  printf("Uex ret usid:%s\n", sUid);
  return;
}

The exit above extends each user ID by two preceding dollar signs ($$) when it is used for RACF login.