Configuring the Natural Development Server

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

The following topics are covered:


Configuration Requirements

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

Parameter Definition
POSIX(ON) Enables a Natural Development Server to access the POSIX functionality of z/OS. If you start a Natural Development Server server with POSIX(OFF), it terminates immediately with a user abend U4093 and the system message EDC5167. 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, that is, 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 does not work properly. IBM supplies the default (ON,SPIE).
TERMTHDACT(UADUMP) Defines the the level of information that is produced in case of an abend. The option UADUMP 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 UNIX environment variables. The only environment variable applicable for the Natural Development Server is TZ (time zone). This variable allows you to adjust the timestamp within the Natural Development 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 Development 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 Development Server load module.

External Security Configuration

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

  • The resource BPX.SERVER must be defined and the NDV server account must have READ access to this resource.

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

    ralt program ** addmem('natural load library') uacc(read)
    ralt program ** addmem('NDV 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.

NDV Configuration File

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

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

See also the NDV Configuration File Example shown below.

NDV Configuration Parameters

The following NDV configuration parameters are available:

DBG_CODEPAGE

This optional configuration parameter specifies the translation table to be used by the remote debugger. By default, the remote debugger uses the code page IBM-1047, whereas the Natural Development Server uses TABA1/2.

Value Explanation
USER Use the Natural translation tables TABA1/2.

No default value is provided.

Example:

DBG_CODEPAGE=USER

DEFAULT_PROFILE

This optional configuration parameter defines a default profile.

Value Explanation
string The following syntax applies:
profile-name,dbid,fnr,password,cipher-code

Note:
Specifying a parameter string in the Session Parameters text box of the Map Environment dialog box in Natural Studio overwrites this default profile.

No default value is provided.

Example:

DEFAULT_PROFILE=RDEVS,10,930

The setting in the example defines that, if no parameters are defined in the Map Environment dialog box of Natural Studio, the session is started with the Natural profile parameter PROFILE=(RDEVS,10,930).

Related parameter: SESSION_PARAMETER.

FORCE_IPV4

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

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

Value Explanation
YES Enforce the use of communication method IPV4.
NO First try communication method IPV6. If this fails give an error message and use communication method IPV4. This is the default value.

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.

Value Explanation
frontend-name Natural front-end to be used. Maximum length: 8 characters.

No default value is provided.

Example:

FRONTEND_NAME=NATvrsSV

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

Note:
When working with the CICS Adapter FRONTEND_NAME=NATCSRFE is mandatory. When working with the IMS Adapter FRONTEND_NAME=NATISRFE is mandatory.

FRONTEND_OPTIONS

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

Value Explanation
01 Do not use the Roll Server. This is the default value.
02 Clean up roll file at server termination.
04 Write GTF trace.
08 Write ETRACE.
10 Front-end automatic termination.
20 Write console information.

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 optional configuration parameter contains additional Natural front-end parameters as specified in the Startup Parameter Area.

Value Explanation
parameter-name You can define multiple parameters. Each parameter specification is a pair of 8-character strings, the first containing the parameter keyword and the second the parameter value, for example:
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 NDV 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.

Value Explanation
YES Trap abends in the server processing, write a snap dump and abort the affected user. This is the default value.
NO Suspend the server abend handling.

Example:

HANDLE_ABEND=NO

HOST_NAME

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

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.

Example:

HOST_NAME=node1

or

HOST_NAME=157.189.160.55

HTPMON_ADMIN_PSW

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

Value Explanation
any character string The password to be entered at the HTML Monitor Client for some monitor activities.

No default value is provided.

Example:

HTPMON_ADMIN_PSW=GHAU129B

HTPMON_PORT

An NDV 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.

Value Explanation
1 - 65535 TCP/IP port number.

No default value is provided.

Example:

HTPMON_PORT=3141

IGNORE_PRESENT_SERVER

An NDV 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 NDV server name.

If an NDV server with NDV CICS Adapter ends abnormally, it might leave a stuck NDV server environment within the CICS region. This causes that a restart of the server fails with error message NAT9913.

If you start an NDV 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.

Value Explanation
YES Terminate existing CICS server environment.
NO Abort server initialization if a CICS server environment already exist. This is the default value.

Example:

IGNORE_PRESENT_SERVER=YES

INITIAL_USERID

At server initialization, the Natural Development 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.
STARGATE This is the default value.

Example:

INITIAL_USERID=NDVINITU

See also NDV Clients must be defined to Natural Security (in the Natural Development Server Installation documentation).

KEEP_TCB

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.

Value Explanation
YES The remote Natural session uses the same TCB during its entire lifetime.
NO This is the default value.

Example:

KEEP_TCB=YES

MINIMUM_STUDIO_VERSION

This parameter defines a minimum version of Natural Studio which is required to operate with the NDV server. This parameter assists in performing a preliminary validation if all clients use a minimum Natural Studio version. This can be useful to smoothly upgrade to a NDV version that does not support clients whose version is below the minimum Natural Studio version.

Value Explanation
vvmmpp The Studio Version (5-6 digits), where:
vv Version number (1 or 2 digits).
mm System maintenance level (2 digits).
pp Patch level (2 digits).
61100 This is the default value.

Example:

MINIMUM_STUDIO_VERSION=62100

O4I

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

Value Explanation
YES Collect server data for Optimize for Infrastructure.
NO Do not collect server data for Optimize for Infrastructure. This is the default value.

Example:

O4I=YES

PASSWORD_MIXEDCASE

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

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

Value Explanation
YES Passwords remain in mixed case.
NO Passwords are translated into upper case. This is the default value.

Example:

PASSWORD_MIXEDCASE=YES

PORT_NUMBER

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

Value Explanation
1 - 65535 TCP/IP port number.

No default value is provided.

Example:

PORT_NUMBER=3140

SECURITY_MODE

The Natural Development 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 (Batch or CICS) you want to impersonate the activities of an NDV client.

Note concerning Natural for DB2: In oder to be able to run the Natural Development Server with impersonation enabled, you must have linked the DB2 interface module DSNRLI (instead of DSNALI) to the Natural nucleus.

Value Explanation
IMPERSONATE_LOCAL Impersonation is done within the Natural Development Server environment. If the session is dispatched in a remote TP environment (for example, in CICS using the NDV CICS Adapter), it is still executed anonymous. The client must be defined in the security system of the NDV server. It is not required to define the client in a remote TP environment. See also External Security Configuration.
IMPERSONATE_REMOTE No impersonation is done within the Natural Development Server environment. If the session is dispatched in a remote TP environment, the client is impersonated. The client must be defined in the security system of the remote TP environment. See also NDV security exit NATUXRFE and the section Product Interaction in the Natural Development Server CICS Adapter documentation.

Note:
Under CICS, please verify the correct installation of the module NATUXRFE. A Map Environment attempt with a valid user ID and an invalid password should fail with a NAT0873 error.

Note:
Not supported with NDV IMS Adapter.

IMPERSONATE Impersonation is done within the Natural Development Server environment and in a remote TP environment. The client must be defined in the security system of the NDV server and in the remote TP environment.

Note:
For a batch server SECURITY_MODE=IMPERSONATE and SECURITY_MODE=IMPERSONATE_LOCAL are the same.

No default value is provided.

Example:

SECURITY_MODE=IMPERSONATE

SESSION_PARAMETER

This optional configuration parameter defines session parameters that precede the parameter string either specified in the Map Environment dialog of Natural Studio or defined by default by the configuration parameter DEFAULT_PROFILE.

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.

Example 1:

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

- where vr stands for the version and release number.

Example 2:

SESSION_PARAMETER=FNAT=(10,930)

The setting in the second example defines that every session on this Natural Development 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.

SESSION_PARAMETER_MIXED_CASE

This optional configuration parameter can be used to allow session parameters and URL specifications in mixed case.

Value Explanation
YES Session parameters remain in mixed case.
NO Session parameters are translated into upper case. This is the default value.

SESSION_TIMEOUT

Cancel inactive sessions when the SESSION_TIMEOUT parameter is met. Check for sessions inactive longer then n minutes once a day at HH:MM (24 hours) or every n minutes.

The server will not start if an invalid SESSION_TIMEOUT parameter is given.

Value Explanation

hh:mm,n <numeric value greater than 0> or

m <numeric value greater than 0>,n <numeric value>0>

If format is hh:mm, check once a day at hh:mm for sessions more than n minutes inactive.

or

If format is a numeric value, check every m minutes for sessions more than n minutes inactive.

Examples:

SESSION_TIMEOUT=19:30,480

Every day at 19:30 cancel sessions more than 480 minutes inactive.

SESSION_TIMEOUT=360,480

Every 360 minutes cancel sessions more than 480 minutes inactive.

TERMINAL_EMULATION

This configuration parameter defines the terminal emulation to be used for processing the Natural I/O. This definition applies to all clients using that server.

Value Explanation
WEBIO Use the Web I/O Interface as terminal emulation.
3270 Use the 3270 terminal emulation. This is the default value.

Example:

TERMINAL_EMULATION=WEBIO

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.

Note:
This parameter is obsolete when the Natural Development Server CICS Adapter or the Natural Development Server IMS Adapter is used.

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.

Note:
This parameter is obsolete when the Natural Development Server CICS Adapter or the Natural Development Server IMS Adapter is used.

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

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 Development Server.

TRACE_LEVEL

Value Explanation
trace-level See Trace Level in the section Operating the Natural Development Server.
0 This is the default value.

Example:

TRACE_LEVEL=0x00000011

or alternatively

TRACE_LEVEL=31+27

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

UNICODE_SOURCE

This configuration parameter is used to define whether the NDV server accepts source files in Unicode or not.

Sources transmitted in unicode are not converted using the Natural ASCII-to-EBCDIC translation tables TABA1/TABA2. All characters in the source file are supported without maintaining the Natural translation tables.

A transmission in Unicode, however, increases the CPU consumption of the server significantly.

Value Explanation
YES Transfer sources in Unicode.
NO Transfer sources in ASCII. No code page support for Natural sources. This is the default value.

Example:

UNICODE_SOURCE=YES

UPPERCASE_SYSTEMMESSAGES

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

Value Explanation
YES Enable uppercase translation.
NO Disable uppercase translation. This is the default value.

NDV Configuration File Example

 # This is a comment
SESSION_PARAMETER=profile=(stgqa,10,930) fuser=(10,32)
DEFAULT_PROFILE=DEFPROF
THREAD_NUMBER=2
THREAD_SIZE=700
FRONTEND_NAME=NATOS31L       # and another comment
PORT_NUMBER=4711

NDV Server Datasets

The Natural Development 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.

Alternatively, you can qualify each dataset name by the server ID.

NDVS1C Defines the server configuration file for the server NDVS1.
NDVS1T The server trace output for the server NDVS1.
NDVS1O The stdo dataset for the server NDVS1.
NDVS1E The stde error output for the server NDVS1.

NDV User Exits (Coded in Natural)

Natural Single Point of Development provides the following user exits for mainframes:

NDV-UX01 This exit is invoked before a Natural source object or a DDM is edited. It can be used to reject editing of certain sources. The source code of this exit is delivered in the library SYSLIB and named NDV-SX01 *).
NDV-UX02 This exit is invoked before a Natural object, a DDM or a user error message is deleted, copied or moved (including the context menu functions Cut, Copy and Paste). It enables the rejection of further processing of this object, similar to the user exit MAINEX01 of SYSMAIN in Natural for Mainframes. The source code of this exit is delivered in the library SYSLIB and named NDV-SX02 *).
NDV-UX03 This exit provides flags for special settings within the Natural Development Server. See the source code of this exit for available flags. The source code of this exit is delivered in the libary SYSLIB and is named NDV-SX03 *).

*) The sources of these user exit routines are named NDV-SXnn, where nn denotes the number of the user exit routine.

Start of instruction set To make a user exit routine available

  1. Copy the source code from SYSLIB into a user library.

  2. Catalog it under the name NDV-UXnn.

  3. Copy it back into the Natural system library SYSLIB.

The name of each user exit source is different from the name of the corresponding cataloged object. This guarantees that the object is not affected if the user exit source is overwritten by an installation update.

For further details, see the source code of the user exit routines NDV-SXnn in the Natural system library SYSLIB.

Other NDV User Exits

Apart from the NDV user exits that are coded in Natural, the following user exit exists:

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 loadmodule NSECUX01) is found in the NDV load library concatenation, it is called before the user is validated against RACF.

The following parameters are passed to the exit:

Name Format In/Out Description
sUid CL64 I/O User ID to be modified for RACF login.

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.