Configuring the Natural Development Server

#### Search Results

Search

# Configuring the Natural Development Server

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

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

- Encrypted Communication

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

Parameter | Definition
--- | ---
`RESIDENTPAGE` | The following members must be defined in the SMARTS resident area: `NATRDEVS`, `NATMONI`, `NATDSSEC`, Natural front-end (`NCFNUC`) and Natural nucleus (if you run using a split nucleus).
`SECSYS` | The installed external security system (`RACF` | `ACF2` | `TOPSECRET`).
`SERVER` | The following `SERVER` definitions are required for the Natural Development Server:
`SERVER=(OPERATOR,TLINOPER,TLSPOPER)` | The Operator Communications Server.
`SERVER=(POSIX,PAENKERN)` | The POSIX Server.
The Natural local buffer pool definition. | For details, refer to the Natural Com-plete interface documentation.
`CDI_DRIVER` | `CDI_DRIVER=('TCPIP,PAAOSOCK')` | The SMARTS TCPIP Socket Driver for TCP/IP stack on z/OS (Com-plete).
`THSIZEABOVE` | `THSIZEABOVE=1024` | The storage above 16 MB that is available for each Natural Development Server subtask. This size must be large enough to keep the Natural tread, heap and stack of the Natural Development Server subtasks. A certain headroom (20 % or more, depending on your environment) is recommended. If the Natural Development Server initialization fails with an error message `NAT9915 GETMAIN for thread storage failed`, this parameter must be increased.
`ADASVC` | `ADASVC=nnn` | The Adabas SVC number of your Adabas installation.

You can set the SMARTS `SYSPARM` parameters in the file referred by DD-name `SYSPARM` within your Com-plete startup JCL.

### 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/.

    * ------------------ NDV Server to launch at startup ----------*
    * STARTUPPGM='NATRDEVS NDVvr'
    *
    *
    TASK-GROUP=(DEFAULT,6)
    THREAD-GROUP=(DEFAULT,(DEFAULT,252,06,15,28,N))
    *
    THSIZEABOVE=1024
    *
    SERVER=(NCFNATvr,NCFNATvr)
    *
    CDI_DRIVER=('TCPIP,PAAOSOCK,ADDRSPCE=...')
    *
    RESIDENTPAGE=NATRDEVS
    RESIDENTPAGE=NDVNCFvr
    RESIDENTPAGE=NATNUCvr
    RESIDENTPAGE=NATHTMON
    RESIDENTPAGE=NATMONI
    RESIDENTPAGE=NATDSSEC

`ADDRSPCE` should contain the name of the TCP/IP address space.
`NDVNCFvr` is the name of the Natural Complete Frontend.
`NATNUCvr` is the name of the Natural Nucleus.

## NDV Configuration File

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

The configuration file is a text file located on a dataset 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

- DEFAULT_PROFILE

- FORCE_IPV4

- FRONTEND_NAME

- HANDLE_ABEND

- HOST_NAME

- HTPMON_ADMIN_PSW

- HTPMON_PORT

- HOST_NAME

- INITIAL_USERID

- MINIMUM_STUDIO_VERSION

- O4I

- PARMCHECK

- PASSWORD_MIXEDCASE

- PORT_NUMBER

- SECURITY_MODE

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

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.

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.

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

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

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

### PARMCHECK

This parameter allows you to perform a parameter check of Natural session parameters after the server is up. The check is done by mapping to Natural. If a problem occurs, a message is written to the NDV server trace, and the server is terminated immediately. In such cases, session parameters (`SESSION_PARAMETER`) can be corrected. To avoid termination of the server in case of invalid Natural parameters, the parameter check can be switched off.

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

Value | Explanation
--- | ---
`YES` | Perform parameter check after the server is up. This is the default value.
`NO` | Avoid parameter check after the server is up.

Example:

    PARMCHECK=NO

### 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) you want to impersonate the activities of an NDV client.

Value | Explanation
--- | ---
`IMPERSONATE_LOCAL` | Impersonation is done within the Natural Development Server environment. If the session is dispatched in a remote TP environment, 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.
`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.
`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

### 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
    FRONTEND_NAME=NATNCF       # 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. This is necessary if you want to start different Natural Development Servers under a single SMARTS address space.

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

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 using standard linkage conventions (direct branch using BASR instructions) 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.

## Encrypted Communication

Communication between NaturalONE and NDV servers can be encrypted by using an SSL or (preferably) a TLS protocol.

On the server side, encryption is enabled by using the AT-TLS component of the z/OS Communications Server. AT-TLS allows you to encrypt and secure the TCP/IP communication between client and server without any changes on the server side. If you want to use encrypted communication mode, you must define a set of rules concerning the NDV server job for the policy agent (PAGENT) configuration file of AT-TLS. Encrypted communication requires a certificate associated with encryption on the server side. This encryption certificate must either be included in a RACF keyring or stored in a key database located on the z/OS USS POSIX file system.

Use the ZOSMF utility for maintaining the PAGENT.

For detailed information on AT-TLS, refer to the z/OS Communications Server documentation from IBM.

### On this page

- 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
- Encrypted Communication