Operating the Natural Development Server

This document describes how to operate a Natural Development Server in a SMARTS on BS2000 environment.

The following topics are covered:


Starting the Natural Development Server

Start the Natural Development Server with the SDF command:

/Enter-Proc *LIB(NDVvrs.JOBS,START-NDV)

The SDF procedure START-NDV has to be supplied with the following parameters:

Parameter Definition Default Value
NDV-JOBS The NDV (SMA) job library. NDVvrs.JOBS
ENV-MOD The NDV environment-specific module library. This library contains the linked Natural nucleus module. NDVvrs.JOBS
NDV-MOD The NDV module library. $SAG.NDVvrs.MOD
NCF-MOD The Natural Com-plete interface module library. $SAG.NCFvrs.MOD
APS-LIB The SMARTS library (modules and procedures). $SAG.APSvrs.LIB
ADA-MOD The Adabas module library. $SAG.ADAvrs.MOD
NDV-SERVERID NDV Server-ID. NDVS01
PROC-NAME The name of the NDV START procedure. The procedure must reside in the NDV-JOBS library. START-NDV
NDV-CONFG The NDV configuration file. It must reside in the NDV-JOBS library (Type S). NDV-CONFG
NDV-SYSPARM The SMARTS configuration file. It must reside in the NDV-JOBS library. NDV-SYSPARM
NDV-ADAPARM The ADALNK parameter file (IDTNAME, etc). It must reside in the NDV-JOBS library. NDV-ADAPARM
LOG-FILE-PREFIX The log-file prefix for the SYSOUT files of all SMARTS tasks. L.NDV.
WORKER-JOB-NAME The job name of the worker-tasks. NDVWORK
WORKER-JOB-CLASS The job class of the worker-tasks. *STD
WORKER-CPU-LIMIT The CPU time limit for the SMARTS worker tasks. *NO
LOGGING Switches logging for diagnostic purposes. *NO
MAIN-TASK For internal use only. Do not modify! -

For the currently applicable versions refer to Empower https://empower.softwareag.com/.

Caution:
Do not modify the variable names and parameter names that are used in the procedure START_NDV. This procedure is called recursively to attach the worker-tasks. For this purpose, the ENTERPARM string is internally executed and several variables are read from the system, using the GETVAR function of SDF-P.

Terminating the Natural Development Server

The Natural Development Server can be terminated with the console command:

/INTR <TSN smarts-main-task>,EOJ

Changing the SYSOUT File Assignment of the FSIO Task

The central logical system file SYSOUT written by the FSIO task can be reassigned at SMARTS server execution time, using the SDF procedure SHOW-SYSOUT.

Thus it is possible to look up trace outputs, error reports, etc., without having to terminate the server.

The procedure SHOW-SYSOUT has to be called with the following parameters:

APS-LIB The SMARTS module library.
TSN The TSN of the SMARTS server main-task.

As a result of the SHOW-SYSOUT execution, the logical system file SYSOUT of the FSIO task will be reassigned to a new file and the previous one will be opened with the SHOW-FILE command. The new logical system file SYSOUT is built by appending a numerical suffix to the file name. The value of the suffix is incremented by 1, each time SHOW-SYSOUT is executed.

Example:

/Call-Proc *LIB(NDVvrs.JOBS,SHOW-SYSOUT), <SMARTS-tsn>

where SMARTS-tsn is the TSN of your SMARTS main task.

Monitoring the Natural Development Server

To enable the administrator to monitor the status of the Natural Development Server, a monitor task is provided which is initialized automatically at server startup. Using the monitor commands described below, the administrator can control the server activities, cancel particular user sessions, terminate the entire server, etc.

The following topics are covered below:

Monitor Communication

To communicate with the monitor, you can use the monitor client NATMOPI; see Monitor Client NATMOPI. Or you can use the HTML Monitor Client that supports standard web browser; see HTML Monitor Client.

Monitor Commands

The Natural Development Server supports the following monitor commands:

Monitor Command Action
ping Verifies whether the server is active. The server responds and sends the string
I'm still up
terminate Terminates the server.
abort Terminates the server immediately without releasing any resources.
set configvariable value With the set command, you can modify server configuration settings. For example, to modify TRACE_LEVEL:
set TRACE_LEVEL 0x00000012
list sessions Returns a list of active Natural sessions within the server. For each session, the server returns information about the user who owns the session, the session initialization time, the last activity time and an internal session identifier (session-id).
cancel session session-id Cancels a specific Natural session within the Natural Development Server. To obtain the session ID, use the monitor command list sessions.
help Returns help information about the monitor commands supported.

Runtime Trace Facility

For debugging purposes, the server code has a built-in trace facility which can be switched on, if desired.

The following topics are covered below:

Trace Medium

A remote development server writes its runtime trace to the logical system file SYSOUT of the FSIO task.

Trace Configuration

The trace is configured by a trace level which defines the details of the trace. Once a trace is switched on, it can be restricted to particular clients or client requests by specifying a trace filter, see also NDV configuration parameter TRACE_FILTER.

Every Natural session is provided with a 32-bit trace status word (TSW) which defines the trace level for this session. The value of the TSW is set in the NDV configuration parameter TRACE_LEVEL. A value of zero means that the trace is switched off.

Trace Level

Each bit of the TSW is responsible for certain trace information. Starting with the rightmost bit:

Bit 31 Trace main events (server initialization/termination, client request/result).
Bit 30 Detailed functions (session allocation, rollin/rollout calls, detailed request processing).
Bit 29 Dump internal storage areas.
Bit 28 Session directory access.
Bit 27 Dump request/reply buffer EBCDIC.
Bit 26 Dump request/reply buffer ASCII.
Bit 25 Dump I/O buffer.
Bit 24 Free.
Bit 23 Request processing main events.
Bit 22 Request processing detailed functions.
Bit 21 Remote debugger main events.
Bit 20 Remote debugger detailed functions.
Bit 19-16 Free.
Bit 15 Trace error situations only.
Bit 14 Apply trace filter definitions.
Bit 13 Trace start and termination of the server only.
Bit 12 Trace start and termination of the client sessions only. Even if bit 13 is set.
Bit 11-08 Free.
Bit 07-01 Free.
Bit 00 Reserved for trace-level extension.

Trace Filter

It is possible to restrict the trace by a logical filter in order to reduce the volume of the server trace output.

  • The filter can be set with the configuration parameter TRACE_FILTER.

  • The filter may consist of multiple keyword=filtervalue assignments separated by spaces.

  • To activate the filter definition, the trace bit 14 in the trace status word (see Trace Level) must be set.

The filter keyword is:

Client Filters the trace output by specific clients.

The following rules apply:

  • If a keyword is defined multiple times, the values are cumulated.

  • The value must be enclosed in braces and can be a list of filter values separated by spaces.

  • The values are not case sensitive.

  • Asterisk notation is possible.

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.

Support of NATRJE Functionality

Calls to the NATRJE utility (Natural Remote Job Entry) are supported. For technical reasons, however, the file name of the job to be submitted is created in a way which is different from batch operation in a TIAM or openUTM environment. The file name has the following structure:

E.DDMMYYYY.XXXXXXXX.program-name.terminal-id

Where:

DDMMYYYY is the day, month and year when the NATRJE call was submitted.
XXXXXXXX is the time since midnight (00.00 h) in hundreds of seconds.
program-name is the name of the Natural program that calls the NATRJE utility for the purpose of submitting JCL cards to be executed by the operating system.
terminal-id is the Natural terminal ID as contained in the system system variable *INIT-ID.