Configuring the Natural Development Server

This document describes how to configure a Natural Development Server for SMARTS on z/VSE.

The following topics are covered:

• Configuration Requirements

• NDV Configuration File

• NDV Configuration Parameters

• NDV Configuration File Example

• NDV Server Datasets

• NDV User Exits (Coded in Natural)

• Other NDV User Exits

Configuration Requirements

The following topics are covered below:

• SMARTS SYSPARM Parameters

• SYSPARM Example for the Natural Development Server

SMARTS SYSPARM Parameters

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

In the following example, the notation vrs or vr stands for the relevant version, release, system maintenance level numbers. The currently applicable product version must be installed; refer to Empower at https://empower.softwareag.com/.

* ------------------ 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
*
* ------------------ NDV Server to launch at startup ----------*
* STARTUPPGM='NATRDEVS NDVS1'
*
*
TASK-GROUP=(DEFAULT,6)
THREAD-GROUP=(DEFAULT,(DEFAULT,252,06,15,28,N))
*
THSIZEABOVE=1024
*
SERVER=(NATBPSvr,NCFBPSvr,1,2048,2,512,4,1024)
*
CDI_DRIVER=('TCPIP,PAACSOCK,MINQ=10,MAXQ=20')
*
RESIDENTPAGE=NATRDEVS
RESIDENTPAGE=NDVNCFvr
RESIDENTPAGE=NATNUCvr
RESIDENTPAGE=NATSOCK
RESIDENTPAGE=NATMONI

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 a librarian member under 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 NDV Configuration File Example shown below.

NDV Configuration Parameters

The following NDV configuration parameters are available:

• DBG_CODEPAGE

• DEFAULT_PROFILE

• FRONTEND_NAME

• HANDLE_ABEND

• HOST_NAME

• HTPMON_ADMIN_PSW

• HTPMON_PORT

• HOST_NAME

• IGNORE_PRESENT_SERVER

• INITIAL_USERID

• MINIMUM_STUDIO_VERSION

• PASSWORD_MIXEDCASE

• PORT_NUMBER

• SECURITY_MODE

• SESSION_PARAMETER

• SESSION_PARAMETER_MIXED_CASE

• TERMINAL_EMULATION

• TRACE_FILTER

• TRACE_LEVEL

• UNICODE_SOURCE

• UPPERCASE_SYSTEMMESSAGES

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.

No default value is provided.

Example:

DBG_CODEPAGE=USER

DEFAULT_PROFILE

This optional configuration parameter defines a default profile.

profile-name,dbid,fnr,password,cipher-code

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.

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

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

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.

Example:

HANDLE_ABEND=NO

HOST_NAME

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 defines the password required for some monitor activities (for example, Terminate Server) performed by the HTML Monitor Client.

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.

No default value is provided.

Example:

HTPMON_PORT=3141

HOST_NAME

This configuration parameter defines the host name of the NDV server.

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.

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.

Example:

INITIAL_USERID=NDVINITU

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

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.

Example:

MINIMUM_STUDIO_VERSION=62100

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.

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

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.

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.

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.

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.

Example:

TERMINAL_EMULATION=WEBIO

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

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.

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.

NDV Configuration File Example

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

NDV Server Datasets

The Natural Development Server requires the following datasets:

Alternatively, you can qualify each dataset name by the server ID. This is necessary if you want to start different Natural Development Servers under a single SMARTS address space.

NDV User Exits (Coded in Natural)

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

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

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:

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.