Configuring the Natural Development Server

This document describes how to configure a Natural Development Server that is running in a SMARTS environment on BS2000.

The following topics are covered:

• SMARTS Configuration File

• NDV Configuration File

• NDV Configuration Parameters

• NDV Configuration File Example

• NDV User Exits (Coded in Natural)

SMARTS Configuration File

The Natural Development Server reads its configuration parameters from a file which resides as an S-type member in the NDV-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 Development 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 NDV-JOBLIB. It has to be passed to the system in the startup procedure parameter NDV-SYSPARM.

The following topics are covered below:

• SMARTS SYSPARM Parameters

• SMARTS Server Environment Configuration Parameters

• SMARTS Sample Configuration

SMARTS SYSPARM Parameters

The Natural Development Server requires the following SMARTS SYSPARM parameters:

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 Development 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 NDV-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

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

The default value is

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

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

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=20
THSIZEABOVE=4096      
THREAD-GROUP=(DEFAULT,(DEFAULT,0,4)
TASK-GROUP=(DEFAULT,2)  
WORKLOAD-AVERAGE=8 
WORKLOAD-MAXIMUM=40
RESIDENTPAGE=NATSOCK
RESIDENTPAGE=NATMONI
RESIDENTPAGE=NATRDEVS
RESIDENTPAGE=NCFSERV
RESIDENTPAGE=NvrLPRRB
*********************SERVERS ****************************
SERVER=(POSIX,PAENKERN,CONF=PAANCONF)
SERVER=(NCFNATvr,NCFNATvr,1,2048,2,100,4,2048)
SERVER=(NDVNATv,PAENAPPS,NATRDEVS,'NDVS01')
*********************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:NDV/ROOT/SERVER1/')
MOUNT_FS=('PFS://','/')

where vr is the current version and release number.

NDV Configuration File

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

• HTPMON_ADMIN_PSW

• HTPMON_PORT

• HOST_NAME

• INITIAL_USERID

• MINIMUM_STUDIO_VERSION

• O4I

• PORT_NUMBER

• SESSION_PARAMETER

• SESSION_PARAMETER_MIXED_CASE

• SESSION_TIMEOUT

• 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

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.

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

O4I

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

Example:

O4I=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

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.

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.

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.

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
FRONTEND_NAME=NDVFRONT       # and another comment
PORT_NUMBER=4711
# SESSION_PARAMETER='DU=ON'
# TRACE_LEVEL=15+31

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.