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

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

The Natural Development Server requires the following SMARTS SYSPARM parameters:

Parameter Definition
RESIDENTPAGE This parameter specifies one ore more programs which are loaded into the SMARTS load-pool during system startup. The following members must be defined in the SMARTS resident area:

NATRDEVS, NATSOCK, NATMONI, Natural front-end (NCFNUC) and Natural nucleus.

SERVER The following SERVER definitions are required for the Natural Development Server:
SERVER=(POSIX,PAENKERN,CONF=PAANCONF) The POSIX server.
SERVER=(NCFNATnn,NCFNATnn) The Natural bufferpool server. The size of the various Natural bufferpools is configured in the parameter string of the NDV configuration parameter SESSION_PARAMETER.
SERVER=(NDVSERV,PAENAPPS,NATRDEVS,' SERVERID') The NDV server SERVERID.
CDI_DRIVER The CDI (Communication Driver Interface) drivers specify the various I/O routines and/or tasks of SMARTS as well as the physical access paths for sequential files and PFS-container files. If necessary for technical reasons, these routines are implemented as separate tasks (socket communication, physical file I/O, etc.). The others are executed in the oc-task (main task) or in one of the worker-tasks (for example, console I/O).
CDI_DRIVER=('console,PAANCNIO') The console server.
CDI_DRIVER=('file,PA2SFIO,SIOTSK= JOBNAME') The file I/O task JOBNAME (SYSOUT, traces, etc.).
CDI_DRIVER=('tcpip,PAAZSOCK,SOCKTSK= JOBNAME') The socket task JOBNAME.
CDI_DRIVER=('CIO,PAAQBIO,PFSTSK=') The PFS task JOBNAME running the CDI driver CIO.
CDI_DRIVER=('PFS,PAANPFS,LRECL=4096, CONTAINER=CIO:AAA/BBB/CC') Defines the container file $USERID.AAA.BBB.CC for the Portable File System (PFS); see also SMARTS Portable File System on BS2000.
MOUNT_FS MOUNT_FS=('PFS://','/') Mapping of (PFS) file names to the appropriate physical BS2000 container file; see also SMARTS Portable File System on BS2000. This parameter maps (POSIX) filenames to a physical BS2000 container file for the specified PFS.
DATA-MAXIMUM DATA-MAXIMUM=nnnn Maximum possible CMP size for DATA in MB (over all sessions). This parameter limits the maximum size of the data common memory pool. At SMARTS startup, the data CMP is enabled with the specified size, however, real storage allocations within the pool are done on demand only in the actually requested size (For more information, please refer to the BS2000 executive macros manual: ENAMP / REQMP macros).
CODE-MAXIMUM CODE-MAXIMUM=nn Maximum possible CMP size for (shared) Code in MB. This parameter limits the total size of all routines loaded, such as the SMARTS kernel itself, NDV and the Natural nucleus.
THREAD-GROUP THREAD-GROUP=(DEFAULT,(DEFAULT,0,n) Establishes the default thread-group with n threads. Only the num subparameter is of importance. This value defines the number of sessions that can be active and kept in storage in parallel; see also the WORKLOAD and TASK-GROUP parameters.
TASK-GROUP TASK-GROUP=(DEFAULT,n) Specifies the number of active worker-tasks. The value n should correspond to the specified number of threads. Only the num subparameter is of importance. This value defines the number of worker-tasks (BS2000 tasks) that can execute NDV Natural sessions in parallel. Evidently, this parameter value should correspond to the number of available threads as defined by the THREAD-GROUP definition!
THSIZEABOVE THSIZEABOVE=nnnn Specifies the SMARTS thread size (in KB) which has to contain all buffers of one Natural session. This parameter specifies the size of the SMARTS threads which have to contain the Natural thread (NTHSIZE parameter, defined in NCFPARM). A certain headroom (20 % or more, depending on your environment) is recommended. If the Natural Development Server initialization fails with NAT9915 GETMAIN for thread storage failed, this parameter must be increased.
WORKLOAD-AVERAGE WORKLOAD-AVERAGE=n The average number of sessions active in parallel. This parameter defines the expected average number of Natural sessions (not users, since one user can start more than one session!) which are to be executed by the server. This parameter must not be confused with the THREAD-GROUP parameter, because it represents the sum of all active and inactive sessions.
WORKLOAD-MAXIMUM WORKLOAD-MAXIMUM=nn The maximum possible number of sessions active in parallel. This parameter defines the maximum possible number of Natural sessions.
ADASVC ADASVC=249 The Adabas SVC number must not be changed.

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 Development Server under SMARTS on BS2000.

ADASVC

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

RESIDENTPAGE

Sysparm Use Possible Values Default
RESIDENTPAGE The name of a program to be loaded and made resident when SMARTS is initialized. program-name none

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

Sysparm Use Possible Values Default
SERVER Information that identifies a server to SMARTS. server-information none

The server-information has the format

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

- where

serv-id is the ID for this server (1-8 characters).
init-mod is the name of the initialization/termination routine.
p1,p2,pn are parameters to be passed to the initialization routines.

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

Sysparm Use Possible Values Default
TASK-GROUP A group comprising one or more tasks, available when SMARTS is started. (grp, num, priority, maxq) (DEFAULT, num)

- where

grp Required. The name of the task group being defined. The default task group is DEFAULT.
num Required. The number of tasks to be allocated in the task group. The default number of tasks is calculated dynamically based on the size of the installation.
priority Not supported under BS2000.
maxq The maximum number of TIBs (default 16) expected on this task group's work queue at the same time. Under normal circumstances, the default should be adequate. When there are problems and it is not, a secondary Last In First Out (LIFO) queue is used so that no work is lost. The normal queue is First In First Out (FIFO), which ensures that work is done in the order in which it is received. This is why the LIFO queue is only used as a secondary backup.

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

Sysparm Use Possible Values Default
THREAD-GROUP A thread group containing one or more thread subgroups and threads, to be available when SMARTS is started. see below see below

The format for the value is

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

- where

grp Required. The name of the task group being defined.
sub The name of the subgroup being defined. If a subgroup name is specified more than once for the same group, the last valid specification is used when parameter processing has been completed.
size Required. The amount of storage in kilobytes to be allocated for each thread below the line. A valid value is between 8 KB and 1 MB.
num The number of threads to be allocated in the thread subgroup. The value must be greater than 1 and less than 4096. Generally, this subparameter is required. It can be omitted for one (and only one) thread subgroup in the address space; in this case, the number of threads to be allocated for the subgroup is calculated dynamically by SMARTS, based on the size of the installation.
cpu The CPU time in seconds (default 0.00) that a user program can use in the thread subgroup for one SMARTS transaction. This value may be entered as an integer or to a level of hundredths of seconds using the n.nn format. If a 0 is provided as the CPUTIME for a thread subgroup, no CPU limit is placed on programs running in the associated threads.
real The wait time in seconds (default 0.00) for the thread subgroup, after which a message is issued to the console if the user program has not given up control of its thread. This value may be entered as an integer or to a level of hundredths of seconds using the n.nn format. If 0 is specified, elapsed time is not checked for the thread subgroup.
key The key (default M) in which the threads within the subgroups are allocated:

M - The thread keys are a mixture of user keys excluding the key in which SMARTS is running.
N - No storage protection is implemented and all threads run in the same key as SMARTS.

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 the 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

Sysparm Use Possible Values Default
THSIZEABOVE The amount of storage above the 16 MB line, in multiples of 1024 bytes, to be allocated to each thread. n 1024

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.

Sysparm Use Possible Values Default
WORKLOAD-AVERAGE The average number of parallel processes expected to run in SMARTS. 1-32767 WORKLOAD-MAXIMUM divided by 4.
WORKLOAD-MAXIMUM The maximum number of parallel processes expected to run in SMARTS. 1-32767 50 if WORKLOAD-AVERAGE is not specified, otherwise WORKLOAD-AVERAGE times 4.

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

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.

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.

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

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

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.

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

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

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

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

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.

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

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
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:

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.