Configuration

This document describes how to configure a Natural Subprogram Server for z/OS (Batch).

This document covers the following topics:

Configuration Requirements
External Security Configuration
Configuration File
Configuration Parameters
Configuration File Example
Natural Subprogram Server Datasets

Configuration Requirements

A Natural Subprogram Server for z/OS (Batch) requires the following z/OS language environment parameter configuration:

Parameter	Definition
`POSIX(ON)`	Enables a Natural Subprogram Server to access the POSIX functionality of z/OS. If you start a Natural Subprogram Server with `POSIX(OFF)`, it terminates immediately with a `U4093` user abend and the `EDC5167` system message. IBM supplies the default OFF.
`TRAP(ON,NOSPIE)`	Defines the abend handling of the LE/370 environment: `ON` Enables the Language Environment condition handler. `NOSPIE` Specifies that the Language Environment will handle program interrupts and abends via an `ESTAE`. This means the Natural abend handler will receive control to handle program interrupts and abends. If you do not specify `TRAP(ON,NOSPIE)`, the Natural abend handling will not work properly. IBM supplies the default `(ON,SPIE)`.
`TERMTHDACT(UADUMP)`	Defines the level of information that is produced in case of an abend. The `UADUMP` option generates a Language Environment, `CEEDUMP`, and system dump of the user address space. The `CEEDUMP` does not contain the Natural relevant storage areas. IBM supplies the default (`TRACE`).
`ENVAR(TZ=…)`	The `ENVAR` option enables you to set Linux environment variables. The only environment variable applicable for the Natural Subprogram Server is `TZ` (time zone). This variable allows you to adjust the timestamp within the Natural Subprogram Server's trace file to your local time. Example (minus 1 hour daylight saving time): `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 Subprogram Server startup job. The length of the options is constrained by the maximum length of the PARM parameter.
Assemble an LE/370 runtime option module CEEUOPT and link it to the Natural Subprogram Server load module.

External Security Configuration

If you configure the Natural Subprogram Server to impersonate the clients in the Natural Subprogram Server (configuration parameter SECURITY_MODE set to IMPERSONATE_LOCAL), the Natural Subprogram Server must run "program-controlled". Under RACF, the following definitions are required for the Natural Subprogram Server:

The BPX.SERVER resource must be defined and the Natural Subprogram Server account must have READ access to this resource

The LOAD datasets defined in the startup job definition must be defined to the program class "**"

ralt program ** addmem('natural load library') uacc(read)
ralt program ** addmem('NPI 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 be granted to use the z/OS Linux System Services.

Configuration File

A configuration file is allocated to the name STGCONFG.

The configuration file is a text file located on a dataset or on an HFS file under z/OS.

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

For more information, see the Configuration File Example section below.

Configuration Parameters

The following configuration parameters are available:

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. It needs to be linked re-entrant or re-usable.

Value Explanation

Value	Explanation
`frontend-name`	Natural front-end to be used. Maximum length is 8 characters. No default value is provided.

frontend-name

Natural front-end to be used. Maximum length is 8 characters.

No default value is provided.

Example:

FRONTEND_NAME=NATvrsSV

where vrs stands for the version, release, and system maintenance number.

FRONTEND_OPTIONS

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

Value	Explanation
`40`	Do not use Clone. To accelerate the Natural session initialization, each new session is cloned from the master session created at server initialization. If you activate this option, each new session is initialized from scratch. This will have a significant impact on the response time of the server.

Example:

FRONTEND_OPTIONS=40

FRONTEND_PARAMETER

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

Value Explanation

Value	Explanation
`parameter-name`	You can define multiple parameters. Each parameter specification is a pair of 8-character strings, with the first containing the parameter keyword and the second containing the parameter value. No default value is provided.

parameter-name

You can define multiple parameters. Each parameter specification is a pair of 8-character strings, with the first containing the parameter keyword and the second containing the parameter value.

No default value is provided.

Example:

FRONTEND_PARAMETER='MSGCLASSX       '

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

For more information, see Operations > Natural as a Server.

HANDLE_ABEND

If an abend occurs during server processing outside of Natural processing, Natural abend handling does not trap the abend. For this reason, the Natural Subprogram Server has its own abend recovery.

Value Explanation

Value	Explanation
`YES`	Traps abends in the server processing, write a snap dump and abort the affected user. This is the default value. It is recommended to use the default value to limit the impact of an abend to a single user.
`NO`	Suspends the server abend handling. Any abend in the server processing terminates the complete server processing, affecting all users on that server.

YES

Traps abends in the server processing, write a snap dump and abort the affected user.

This is the default value. It is recommended to use the default value to limit the impact of an abend to a single user.

NO Suspends the server abend handling. Any abend in the server processing terminates the complete server processing, affecting all users on that server.

Example:

HANDLE_ABEND=NO

HOST_NAME

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

Value Explanation

Value	Explanation
`host_name`	If `HOST_NAME` is specified, the server listens on the particular stack specified by `HOST_NAME`, otherwise the server listens on all stacks. No default value is provided.

host_name

If HOST_NAME is specified, the server listens on the particular stack specified by HOST_NAME, otherwise the server listens on all stacks.

No default value is provided.

Example:

HOST_NAME=node1

HOST_NAME=157.189.160.55

IGNORE_PRESENT_SERVER

A Natural Subprogram Server allocates a so-called server environment which contains the server dependent common resources. This environment is unique for each server and relates to the Natural Subprogram Server name.

If a Natural Subprogram Server ends abnormally, it may leave the server environment in an inconsistent state, causing subsequent server restarts to fail with a NAT9913 error.

If you start a Natural Subprogram Server with IGNORE_PRESENT_SERVER=YES, it might damage an already running server which is using the same server name.

Value	Explanation
`YES`	Terminates the existing server environment.
`NO`	Aborts server initialization if a server environment already exists. This is the default value.

Example:

IGNORE_PRESENT_SERVER=YES

INITIAL_USERID

At server initialization, the Natural Subprogram 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.

Value	Explanation
`userid`	The specified value must not exceed 8 characters, otherwise it is truncated.
`SYSTEM`	This is the default value.

Example:

INITIAL_USERID=NPIINITU

See also Natural API Server > Natural Subprogram Server on z/OS > Installation > Installation of Natural Subprogram Server on z/OS > Step 5: Clients must be defined in Natural Security.

PORT_NUMBER

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

Value Explanation

Value	Explanation
`1 - 65535`	TCP/IP port number. No default value is provided.

1 - 65535

TCP/IP port number.

No default value is provided.

Example:

PORT_NUMBER=3140

SECURITY_MODE

The Natural Subprogram Server offers a security concept that also covers the operating system resources. The client credentials are validated at the operating-system-dependent security system and the client request is executed under the client's account data.

Using the SECURITY_MODE parameter, you can specify whether clients run impersonated on z/OS. In this case, the client’s subtask runs under the client’s account.

Value Explanation

Value	Explanation
`IMPERSONATE_LOCAL`	Impersonation is done within the Natural Subprogram Server environment. The client must be defined in the external security system of the Natural Subprogram Server (for example, RACF). No default value is provided.

IMPERSONATE_LOCAL

Impersonation is done within the Natural Subprogram Server environment. The client must be defined in the external security system of the Natural Subprogram Server (for example, RACF).

No default value is provided.

Notes:

The SECURITY_MODE parameter requires Natural Security (NSC).
Applicable to Natural for DB2 (Batch Server only): In order to run the Natural Subprogram Server with impersonation enabled, you must have the DSNRLI DB2 interface module (instead of DSNALI) linked to the Natural nucleus.

Example:

SECURITY_MODE=IMPERSONATE

SESSION_PARAMETER

This optional configuration parameter defines dynamic session parameters that apply to all sessions running in the Natural Subprogram Server.

Value Explanation

Value	Explanation
`parameter-string`	This string may extend across several lines. A plus sign (+) at the end of a string line denotes that another line follows. No default value is provided.

parameter-string

This string may extend across several lines. A plus sign (+) at the end of a string line denotes that another line follows.

No default value is provided.

Example:

SESSION_PARAMETER='NUCNAME=NATNUCvr,' +
'FNAT=(10,930),FSEC=(10,310),' +
'FUSER=(10,32),' +
'PROFILE=(NPIPARM,18006,48),ADAMODE=1,' +
'BPI=(TYPE=NAT,SIZE=6044)'

where vr stands for the version and release number.

THREAD_NUMBER

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.

Value	Explanation
`thread-number`	Number of physical storage threads to be allocated. Note This number does not limit the number of sessions within the server, but the number of sessions which can be in execution status concurrently. The number of sessions is limited by the size of the Natural swap medium.
`3`	This is the default value.

Example:

THREAD_NUMBER=5

THREAD_SIZE

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

Value	Explanation
`thread-size`	Size (in KB) of each physical storage thread.
`500`	This is the default value.

Example:

THREAD_SIZE=800

TRACE_LEVEL

Value	Explanation
`trace-level`	See Natural API Server > Natural Subprogram Server on z/OS > Operation > Runtime Trace Facility > Trace Level.
`0`	This is the default value.

Example:

TRACE_LEVEL=0x00000011

TRACE_LEVEL=31+27

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

WORKER_DELAY

This configuration parameter specifies the time (in seconds) a worker waits for successive requests. See also Worker Pool.

Value	Explanation
`worker-delay`	Value (in seconds) a worker waits for successive requests.
`0`	This is the default value. No worker pool is used.

Example:

WORKER_DELAY=10

Configuration File Example

 # This is a comment
SESSION_PARAMETER= +
'profile=(npiqa,10,930),' +
'fuser=(10,32)'
THREAD_NUMBER=2
THREAD_SIZE=700
FRONTEND_NAME=NATOS92L       # and another comment
PORT_NUMBER=4711

Natural Subprogram Server Datasets

The Natural Subprogram Server requires the following datasets:

`STGCONFG`	Defines the server configuration file.
`STGTRACE`	The server trace output.
`STGSTDO`	The stdo dataset.
`STGSTDE`	The stde error output.

Configuration

Configuration Requirements

External Security Configuration

Configuration File

Configuration Parameters

FRONTEND_NAME

FRONTEND_OPTIONS

FRONTEND_PARAMETER

HANDLE_ABEND

HOST_NAME

IGNORE_PRESENT_SERVER

INITIAL_USERID

PORT_NUMBER

SECURITY_MODE

SESSION_PARAMETER

THREAD_NUMBER

THREAD_SIZE

TRACE_LEVEL

WORKER_DELAY

Configuration File Example

Natural Subprogram Server Datasets

On this page