Common Entire System Server Features

#### Search Results

Search

# Common Entire System Server Features

This section describes common Entire System Server features.

Note
Support for z/VSE is deprecated. Support for BS2000 is also deprecated, except in conjunction with the ESM adapter. Features that are z/VSE and BS2000 specific will be removed from future releases.

This document covers the following topics:

- Running System Automation Tools in Entire System Server

- Common Diagnostic Features

- Write-to-Spool for Natural

- Dynamic Server Management for Entire System Server

- Run E-Mail Client

- Zap Reports in Entire System Server

- Ending Entire System Server

## Running System Automation Tools in Entire System Server

### General

Entire System Server (ESY) enables the operation of System Automation Tools,for example, Entire Output Management (EOM), Entire Operations ( EOR), as subtasks in the address space of Entire System Server (z/OS, z/VSE) or as pseudo subtasks, that is, standalone tasks (BS2000). These System Automation Tools (SAT) are applications on the basis of Natural, which require a Batch-Natural as engine.

SAT products are started by means of ESY startup parameters.

Until now, interaction between ESY and SAT or EOM, EOR, etc. has only been possible on a rudimentary basis, as the operator command `SHUTDOWN` has been the only command to terminate part or all of the SAT environment.

The configuration of the required batch Natural task was not very flexible at least under BS2000.

This section offers an overview of the interfaces between ESY and SAT and deals with the configuration in the overall context.

### Activating SAT during Start of Entire System Server

#### Start of SAT under BS2000

As Natural subtasks are implemented as separate tasks under BS2000, the definition of job control instructions is required. The ESY startup parameter `JOBNATSUB` specifies the location of the `SAT-ENTER` job. Apart from that, the following can be defined:

- the attributes for the `SAT-ENTER` job (`PRMNATSUB` parameter)

- the maximum number of pseudo Natural subtasks (`NATNUMSUB` parameter)

- the input control of dynamic Natural parameters (`NATDYNPAR` parameter)

The `SAT-ENTER` job, which is started during the initialization of Entire System Server, reads initialization data and starts the configured SAT products according to the set up definitions.

In general, a distinction must be made between the start of the SAT products via the macros `SATSTART TYPE=BATCH` and `SATSTART TYPE=SUBTASK`. To obtain a complete interaction of the SAT products with ESY, the `SATP` member (see SAT Installation and Customization for details) for the `SATSTART` macros should always use the `TYPE=SUBTASK` type. This ensures that both control functions and the Entire System Server shutdown interact with the SAT subproducts. `TYPE=BATCH` jobs are not known to Entire System Server.

The products started by SAT (for example, EOM, EOR) run via separate `ENTER` jobs. In case of `SATSTART TYPE=SUBTASK` a job-skeleton is used for these `ENTER` tasks, which in the past had to be part of the ESY module library in object module format. As of Entire System Server 3.1.1, this job skeleton is definable as part of the ESY startup file.

#### Recently Introduced Startup Parameters under BS2000

- ESY 2.2.2: `NATDYNPAR` startup parameter for the operation of SAT products

  Customers using SAT know the problems with the interaction between the Batch-Natural and the job skeleton used to generate the `ENTER` file for the products started by SAT. To keep the configuration as variable as possible, the ESY startup parameter `NATDYNPAR` was introduced to enable the user to read the dynamic Natural parameters via `FILE`, `SYSDTA` or `SYSIPT` according to the generation of the Batch-Natural driver. This assures that the dynamic parameters are correctly processed by the Batch-Natural.

- ESY 3.1.1: `NATURAL-SUB-TASK` job skeleton as part of the ESY startup parameter file

  As of ESY 3.1.1: The above complicated method is not used any longer, which consisted of delivering the `ENTER` file job skeleton of the products started by SAT as a `DO` procedure with integrated assembler source. This `DO` procedure was executed during installation and generated an object module, which was loaded in the ESY view processor `NATURAL-SUB-TASK` and which was modified before execution by means of the corresponding parameters. This resulted in an `ENTER` job, which started an EOM or EOR task.

  Now, the job skeleton is a component of the ESY startup parameter file.

  The jobs `P.NSBTSKIS` and `P.NSBTSKSD` are still delivered as ESY source library elements, but they are only included for compatibility reasons.

  The job skeleton can be defined at any location in the ESY startup parameter file, but it must be started using the keyword `SATSKEL-BEGIN` and terminated with the keyword `SATSKEL-END`.

  The following abridged example of an ESY startup parameter file shows its use:

        NODE=113
        TIME=30
        ... more parameters ...
        JOBNATSUB=$NPR.E.SAT.113
        PRMNATSUB=RESOURCES=*PAR(CPU-LIMIT=*NO)
        NATDYNPAR=FILE
        NATNUMSUB=20
        *
        SATSKEL-BEGIN
        /.&UID LOGON
        ... more JCL ...
        / LOGOFF SYS-OUT=DEL
        SATSKEL-END

A complete example is part of the delivery files. A comprehensive description is provided in the section Startup Parameters.

### Control of SAT during Entire System Server Operation

As of Entire System Server Version 3.1.1, the `NATPROC-USERS` view contains an extension of the `LIST` function. If the field `FULL-SCAN=YES`, the view processor also lists all internal tasks in addition to the ESY users. This simplifies the control of the tasks controlled by ESY.

### Activating/Deactivating NATURAL-SUBTASKS (SAT) during Operation

The operator command `SHUTDOWN` allows communication between ESY and the SAT product specified by using the operand and communicates the termination request. Communication is carried out by using the view processor `EVENTING`. By using this view, the SAT products obtain all required information, which ESY has passed by using the normal user interface.

New with Entire System Server Version 3.1.1 is the operator command `START ALL` to restart SAT. It restarts the entire SAT environment without restarting the Entire System Server. First the SAT task is restarted and subsequently all defined SAT products are restarted. `START ALL` can be used only if the entire SAT environment has been stopped on its own or by operator command `SHUTDOWN ALL`. These two commands enable the user to have a "yo-yo" or "bounce" during normal operation.

SAT configurations can be corrected and tested while Entire System Server is up and running.

Note that the operator command `SHUTDOWN` can address individual SAT products via parameters, but that the `START` command only accepts the `ALL` parameter.

### Deactivating SAT during Entire System Server Stop

Special processing is required for the shutdown of the Entire System Server, when the SAT products have been started. The `NATURAL-SUB-TASKS` must be informed of the imminent termination. This is carried out by means of the view processor `EVENTING`. Having communicated the termination information, Entire System Server checks the status of the `NATURAL-SUBTASKS` over short intervals. If they have terminated on their own, shutdown handling in ESY will be continued. In the meantime, user requests are still processed, as if the shutdown command had not been issued.

The Deferred Shutdown mechanism limits the time interval between the command for termination of the Entire System Server and the actual ESY termination. It would be possible, however, that the SAT products may not have accepted the shutdown request for various reasons or that they are busy with termination for an unusual period of time.

To eliminate this problem, the startup parameter `SHUTDOWN-MAX-DELAY` is available starting with Entire System Server Version 3.1.1. This parameter limits the Deferred Shutdown to a specified number of seconds. If the time limit is exceeded, Entire System Server will terminate without properly closing down the SAT tasks.

If this situation occurs, why the SAT products did not stop within the defined time interval must be checked. In this case, Software AG support should be consulted, if necessary. As the monitors implemented in EOM or EOR have wait cycles, `SHUTDOWN-MAX-DELAY=180` should be used initially. If all `NATURAL-SUB-TASKS` are stopped, the Entire System Server termination will be continued immediately.

## Common Diagnostic Features

There are two common diagnostic features:

- Command Logging

- Creating Trace Data in the Entire System Server

### Command Logging

For users of Adabas and Adabas Review, Entire System Server provides the capability to optionally log commands to a sequential data set for later analysis. Command logging can be controlled by the corresponding startup parameters `LOGGING`, `LOGCB`, `LOGFB`, `LOGRB`, `LOGSB` and `LOGVB`. The log data set needs to be pre-allocated and defined in the JCL for Entire System Server as `CLOG`.

For z/OS only, two data sets may be used which then need to be allocated with DDNAMEs `CLOGR1` and `CLOGR2`. If one log data set gets an out-of-space condition, command logging will switch to the alternate log data set.

WTO message `ESY0038I` is reporting this as follows:

    > ESY0038I Command logging file full, ...
    > DSN=command.log.data.set.name
    > logging switched to next logging file

Using an `MPF` exit or some other automation tool, this message can be used to initiate a backup of the full command log data set.

Although the command logging facility in Entire System Server (NPR) is similar to the facility in Adabas, there is no support for a user exit to submit the equivalent of the `ADARES CLCOPY` offload job: The command log datasets are simply overwritten or closed when they are full. However, you can code your own `MPF` exit to automatically offload, or the datasets can be manually copied.

The best example for an `MPF` exit is the sample user exit 2 source provided with Adabas.

An Entire System Server (NPR) CLOG requires the following attributes:

    Organization . . . .:PS
    Record format . . . :VB
    Record length . . . :10000
    Block size . . . . .:10004

To print the CLOG, use PRILOG utility of Adabas or batch reports with Adabas Review. Note that the ADAPRI utility does not recognize this format.

The command logs can then be analyzed using the PRILOG utility of Adabas or batch reports with Adabas Review. For details, see the corresponding Adabas and Adabas Review documentation.

### Creating Trace Data in the Entire System Server

#### Introduction

Proper error analysis requires the logging of internal product information. Beginning with Version 3.1.1, Entire System Server is able to generate data that can supply additional diagnosis information to Software AG support and development.

The secondary goal of implementation was that the overall behavior of the Entire System Server not be affected by trace and that only a minimal performance impact would occur. Therefore, trace data is recorded in raw format in order to save time. The data formatting itself is carried out in the diagnosis program `ESYTRACE`, designated explicitly for this purpose.

Trace data include information such as program start and end, return codes of individual functions and events during request processing. This basic level of information will be supplemented in future versions by new trace data points.

The primary function of the trace is to provide information about the operation logic in case of errors. It is not intended as a log of requests during normal operation; the Adabas Command Log provides more detailed information regarding requests and responses.

#### Trace Preparation

The trace environment of Entire System Server is activated by using startup parameters. This environment consists of a data buffer, in which the trace information is stored in a wrap-around method.

The data buffer size may be configured by using a startup parameter. This buffer is available externally to the `ESYTRACE` program running in `MONITOR-MODE` (please see the description of `ESYTRACE` for more information). Under z/VSE, an additional step is required to use the `MONITOR` mode of `ESYTRACE`.

The following startup parameters are part of the Entire System Server trace facility:

- `TRACE` to determine

  - whether the `TRACE` is to be activated (`YES`);

  - whether the `TRACE` environment shall only be initialized without starting the `TRACE` procedure (`PREP`);

  - or whether `TRACE` is not to be activated (`NO`)

- `TRACE-LEN` to set up the `TRACE` data buffer size

- `TRACE-SAV` to determine whether the available `TRACE` data is to be saved in a file, at normal termination of ESY or in case of ABEND.

The general recommendation for the operation of Entire System Server is to define the parameter `TRACE=PREP` to reserve a trace buffer (default 8 KB) and to set `TRACE-SAV=YES`. Then `TRACE` can be switched on or off at will by way of an operator command.

For `TRACE-SAV`, definition of a disk file is required. Under z/OS, a `TRACE` DD statement is required. Under z/VSE, a `TRACSAV DLBL` (preferred) or `TLBL` is required, and it is assigned to `SYS021`. The data is fixed length, 288 bytes. Under BS2000, assignment is via the logical file name `TRACE` (for example., under BS2000: `/SET-FILE-LINK LINK-NAME=TRACE,FILE-NAME=name`); the data is written sequentially in variable record format with a length of 4K as a maximum.

The following list supplies information about the file attributes:

Option | Explanation
--- | ---
BS2000 | Size: `SPACE=(4,4)` Features: `BLKSIZE=(STD,2),FCBTYPE=SAM,RECFORM=V`
z/OS | DCB attributes of `RECFM=FB`, `LRECL=288`
z/VSE | SAM (may be VSAM-managed), fixed length 288 bytes

During startup of Entire System Server, the file is opened and checked for validity. If errors occur during this check or during creation of the file buffer, tracing will be deactivated and a corresponding operator message will be issued on the console.

#### Trace Activation/Deactivation during Operation

If Entire System Server was started by means of `TRACE=PREP` or `TRACE=YES` and the initialization was successful, tracing may be switched on or off by operator command during operation. To do this, the commands `TRACE=Y` or `TRACE=N` are available. This enables the tracing to be limited to specific circumstances. A trace stopped with `TRACE=N` can be switched on again at any time by means of `TRACE=Y`.

#### Trace Data Evaluation Using the Diagnosis Program ESYTRACE

As mentioned above, trace data is stored unformatted. A separate program, `ESYTRACE`, is supplied which formats the raw data. It reads these data in the trace buffer during operation or reads the file created by `TRACE-SAV=YES`, which is written at termination or ABEND of the Entire System Server and which represents a mirror image of the trace data available at the time of termination.

The prepared result data can both be written to a file and/or to `SYSPRINT` (z/OS), `SYSLST` (z/VSE) or `SYSOUT` (BS2000). Output is written to an optional file - `TRACEOUT DD` (z/OS), `TRACOUT (SYS002) DLBL` or `TLBL` (z/VSE) or `TROUT` (BS2000).

`ESYTRACE` is controlled by parmameters, which are passed to it via the `PARM` parameter of the JCL/JCS `EXEC` statement (z/OS, z/VSE) or `RDATA` (BS2000).

The following parameters are supported:

- Position parameter 1: `NODE-ID` of the Entire System Server or `-f` or `--file`

  With Online-Trace, the numerical `NODE-ID` is specified to indicate `MONITOR-MODE`, whereas `-f` or `--file` causes the dataset assigned using the DDNAME `TRACEIN` (z/OS), `TRACIN (SYS001) DLBL` or `TLBL` (z/VSE) or logical file name `TRIN` (BS2000) to be processed as input (`FILE-MODE` ).

- Keyword parameters:

  - `-d | --displ`

    The prepared result data is transferred to `SYSPRINT` (z/OS), `SYSLST` (z/VSE) or `SYSOUT` (BS2000).

  - `-n | --ntrout`

    If this parameter is specified, no output file will be generated with the prepared result data using the logical file name `TROUT`. This key is accepted only if the parameter `-d | --displ` has also been specified.

  - `-p | --poll`

    This option causes `ESYTRACE` in the `MONITOR-MODE` not to terminate the program at the end of the buffer, but to wait for further data in the trace buffer. This enables a running ESY node to be monitored in real time. Under z/VSE, additional steps are required before this can be used.

For the format of the optional output file, the following file attributes are required:

Option | Explanation
--- | ---
BS2000 | Size: `SPACE=(4,4)` Features: `BLKSIZE=(STD,2),FCBTYPE=SAM,RECFORM=V`
z/OS | `LRECL=315`, `RECFM=FBA`
z/VSE | `LRECL=315`

The following parameters are recommended for the two modes:

- parameter list for `MONITOR-MODE`: `NODE-ID --displ --poll`

- parameter list for `FILE-MODE`: `--file`

The output file generated is useable only for error analysis by Software AG support. It contains no user data whatsoever other than the user ID.

For real-time monitoring of error situations, these steps should be used:

1. Start Entire System Server

2. Start diagnosis program `ESYTRACE` in `MONITOR-MODE` with the `--poll` option.

`ESYTRACE` will format trace data as soon as it is placed in the buffer.

#### ESYTRACE Diagnosis Program Termination in MONITOR-MODE

When in `MONITOR-MODE`, `ESYTRACE` can only be terminated by means of the operator command `QUIT`. Issue the `QUIT` command as follows:

Option | Explanation
--- | ---
BS2000 | `/INTR tsn,QUIT`
z/OS | `F stcname,QUIT`
z/VSE | `MSG xx,DATA=QUIT`

## Write-to-Spool for Natural

Notes:

1. This section applies to Natural 4.2 only. If you are using Natural 8.2 or higher, please refer to the corresponding installation documentation for Natural.
2. The Write-to-Spool feature is only available under z/OS and z/VSE.

This section covers the following topics:

- Purpose

- Using the Write-to-Spool Feature

- Installation Considerations

### Purpose

The Write-to-Spool feature enables Natural users to write reports to the system spool directly. It can be used in any Natural environment (Com-plete, TSO, CICS, IMS, Batch, etc.) and uses the Entire System Server view `WRITE-SPOOL`.

Under z/OS, the `SYSOUT` is part of the Entire System Server job stream within the JES spool, and it may be processed by any software which expects output in JES Spool. (for example, Entire Output Management).

The JES spool may be a JES2 or a JES3 spool.

Under z/VSE, the `SYSOUT` is a separate entry in `POWER` queue.

### Using the Write-to-Spool Feature

The Write-to-Spool feature is handled by a so called "access method", which is called ESS for Entire System Server. You may define your printer in the Natural parameter module or dynamically in your session parameter as follows:

1. Define the Natural parameter module:

   In the Natural parameter module, the `NTPRINT` macro has to be set with printer number and access method definition as follows:

       NTPRINT (n),AM=ESS

   Example:

       NTPRINT (1,3),AM=ESS

   Here, printer 1 and 3 are defined for the access method "Entire System Server".

   Or:

   Define the printer during session startup with: `PRINT=((1-6),AM=ESS)`

   Here printers 1 until 6 are defined for access-method "Entire System Server".

2. Link the access-method modules to the Natural nucleus (see Installation Considerations) or load it dynamically using the session parameters: `RCA=(NATAM11),RCALIAS=(NATAM11,NATWSPN4)`

   `NATWSPN4` is the delivered write-to-spool module with the default parameters. If you have linked a module with adapted parameters use the name of this module instead.

3. Users must define the JES destination under the `OUTPUT` class using the `DEFINE PRINTER` statement in their programs.

   Example:

       DEFINE PRINTER (n) OUTPUT 'LOCAL' /* For printing on local JES/POWER printers

   Or:

       DEFINE PRINTER (n) OUTPUT 'DAEF' /* For printing to JES-spool called DAEF

   where `n` is the number in the `PRINTER` entry in the Natural parameter module as described above.

   Reports can now be written to the system spool using one of the following statements:

       DISPLAY (n)

   or

       WRITE (n)

   or

       PRINT (n)

   where `n` is the number in the `PRINTER` entry in the Natural parameter module as described above.

   Users can set the output format and number of copies using the `FORMS` and `COPIES` clauses of the `DEFINE PRINTER` statement.

   Example:

       DEFINE PRINTER (2) OUTPUT 'DEST'
                          FORMS 'FORM'

   You can find the defaults for items such as Entire System Server node, forms and output class in the module `NATWSPDF`.

### Installation Considerations

To use the Write-To-Spool feature you may either link the access method to your Natural nucleus or you may dynamically load the method (see also Natural parameters `RCA` and `RCALIAS`).

You can define the defaults for your Natural nucleus using `NATPWSDF` and assemble them before linking to nucleus. You can find the source member `NATPWSDF` in the source library of Natural.

There, you have the possibility to customize the defaults as follows:

#### Defaults for Factory Settings:

    WSPDFLT NODE=148,
     Entire System Server (NPR) TARGET NODE
    PROGRAM=,
    JES WRITER (8 CHARS MAX)
    CLASS=A,
    SYSOUT CLASS (1 CHAR)
    HOLD=YES,
    HOLD (YES/NO)
    CNTL=A,
    CARRIAGE CONTROL (A/M)
    FORM=,
    FORM (4 CHARS MAX)
    RMT=,
    JES REMOTE (8 CHARS MAX)
    FORMDEF=,
    FORMDEF (6 CHARS MAX)
    PAGEDEF=
    PAGEDEF (6 CHARS MAX)

Parameter | Description
--- | ---
`Node` | The real Entire System Server node number which can contain up to 5 digits. It addresses the destination started task of Entire System Server and where the output is written.
`Program` | The JES Writer which can contain up to 8 characters. JES provides control to the Writer program. If JES does not find it, it is ignored. Possible Value: `*OUTPUT` means that the input from the Natural statement `DEFINE PRINTER` is used to be interpreted as JES Writer.
`Class` | The `SYSOUT` class within JES where the output has to be written. It can contain only one character or digit. It is a descriptor for further software (e.g. Entire Output Management) to detect the output stream for processing.
`Hold = yes/no` | Specifies if the output stream is to be held within the JES spool or not, in case the task previously started by Entire System Server terminates.
`CNTL` | Represents the control character for the `SYSOUT` dataset. `CNTL` contains one character:
`A`
ASA control character
`M`
machine control character
`Form` RMT | Describes the form control buffer for JES. This value is transferred to JES which handles the processing. `RMT` represents the JES remote user ID if `SYSOUT` has to be routed to a different JES system. You can find the name of the JES system in the destination field within the `DEFINE PRINTER` statement (for example, `DEFINE PRINTER OUTPUT='DAEM'`)
Formdef Pagedef | They can contain up to 6 characters.

After editing the `NATPWSDF` member with customized values, you can assemble and link it. (If you want to use the factory settings, you may omit these steps.)

To use the Write-to-Spool feature with statically linked access method at your site, relink the Natural module as follows:

#### For z/OS:

    INCLUDE NATLIB(NATPWSPL)     The Write-to-Spool access method for Natural
    INCLUDE NATLIB(NATPWSDF)     Write-to-Spool defaults (default or adapted parameter module)

Or load it dynamically using the session parameters: `RCA=(NATAM11),RCALIAS=(NATAM11,NATPWSAM)`

If you have linked a module with adapted parameters, use the name of this module instead.

    INCLUDE NATLIB(NATPWSPL)
    INCLUDE USRLIB(NATPWSxx) your adapted parameter module
    NAME NATWSPxx(R)         your adapted write to spool module. This name must be used in RCALIAS=(NATAM11,NATWSPxx)

#### For z/VSE:

    INCLUDE NATWSP41    The Write-to-Spool access method for Natural 4.1
    INCLUDE NATWSPDF    Write-to-Spool defaults (your adapted parameter module)

To use dynamic load you may either use the delivered module `NATWSPN4` with default parameters or you may link your adapted parameter module.

Examples:

#### 1. Assume using the factory settings and executing the Natural program:

    DEFINE PRINTER (2) OUTPUT 'WK1'
    WRITE (2) 'THIS IS A SMART RECORD'
    CLOSE PRINTER (2)

During the execution of this program, you can see the following fields with their in the Display Active Tasks panel:

    DDNAME     DSID Owner C Dest Rec-Cnt Forms Wtr PageDef FormDef
    SYS00001   104  WKK   A WK1     2     STD

Browsing this dataset, you can see:

    Page 1
    THIS IS A SMART RECORD

#### 2. Assume using the defaults member:

    WSPDFLT NODE=55526,
    Entire System Server (NPR) TARGET NODE
    PROGRAM=HUGO,
    JES WRITER (8 CHARS MAX)
    CLASS=Y,
    SYSOUT CLASS (1 CHAR)
    HOLD=YES,
    HOLD (YES/NO)
    CNTL=A,
    CARRIAGE CONTROL (A/M)
    FORM=WOFO,
    FORM (4 CHARS MAX)
    RMT=JESWOLF,
    JES REMOTE (8 CHARS MAX)
    FORMDEF=FOWOLF,
    FORMDEF (6 CHARS MAX)
    PAGEDEF=PAWOLF
    PAGEDEF (6 CHARS MAX)

Executing the following Natural program:

    DEFINE PRINTER (2) OUTPUT 'WK1'
    WRITE (2) 'THIS IS A SMART RECORD'
    CLOSE PRINTER (2)

During the execution of this program, you can see the following fields with their in the Display Active Tasks panel:

    DDNAME   DSID Owner C Dest Rec-Cnt Forms  Wtr   PageDef  FormDef
    SYS00002 105   WKK  Y  WK1    2     WOFO  HUGO  PAWOLF   FOWOL

Browsing this dataset, you can see:

    Page 1
    THIS IS A SMART RECORD

#### 3. Assume using the default member:

    WSPDFLT NODE=55526,
    Entire System Server (NPR) TARGET NODE
    PROGRAM=*OUTPUT,
    JES WRITER (8 CHARS MAX)

The other parameters in the default member are not changed.

Run the following example program:

    DEFINE PRINTER (2) OUTPUT 'KURT'
    PRINT (2) ' hier kommt KURT'
    CLOSE PRINTER (2)

After that, Entire System Server fetches the value from the field `OUTPUT` in the `DEFINE PRINTER` statement and inherits it as the JES Writer attribute for the specific spool-dataset.

Looking in TSO/SDSF under the job-name of Entire System Server, you can see the following:

    PREFIX=NPR*  DEST=(ALL)  OWNER=*  SYSNAME=
    NP   DDNAME   Time     Forms    FCB  UCS  Wtr      Flash
         SYS00005 10:20:48          **** **** KURT     ****

If in JES an associated JES Writer Program is defined, it gets control and handles this output as defined in the program.

#### For z/VSE

In z/VSE the output is written into the `POWER` spool under a new job number. The name of the printed spool dataset will be the name of the original batch job or the user ID of the TP monitor.

Examples:

1. Assume we are using the factory settings for `NATWSPDF` and have the natural program:

    DEFINE PRINTER (2) OUTPUT 'ELSA'
    WRITE (2) 'THIS IS A SMART RECORD'

    CLOSE PRINTER (2)

User `WKK` is running this program in a batch-mode Natural, with `JOBNAME=GERHARD`.

The power queue contains the following information:

    JOBNAME JOBNO   Q NUM C D PR  STAT FROM TO   CP PAGES RECORDS ID
    GERHARD 0020443 L     A H 003 HOLD WKK  ELSA  1     1       2

Browsing this output displays the following information:

    BROWSE-DJ:GERHARD(20443)-Queue:LS --------------------- Row 0 - Columns 001 076
      COMMAND===>                                                    SCROLL===> CSR
    ****************************** top of list *******************************
    1Page      1                                                date, time
    0THIS IS A SMART RECORD
    **************************** bottom of list ******************************

2. Assume we are using the factory settings for `NATWSPDF` and have the natural program:

    DEFINE PRINTER (2) OUTPUT   'KARL'
                       FORMS    'F001'
                       COPIES   4
    WRITE (2) 'PRINTER TEST'
    WRITE (2) 'OK?'
    CLOSE PRINTER (2)

The power queue contains the following information:

    JOBNAME  JOBNO   Q NUM C D PR  STAT FROM  TO   FORM CP  PAGES RECORDS ID PR
    GERHARD  0020465 L     A H 003 HOLD WKK   KARL F001   4     1       3

## Dynamic Server Management for Entire System Server

#### (This feature is available under BS2000, z/VSE only.)

This section covers the following topics:

- Dynamic Server Management Concepts

- Configuring a Dynamic Server Environment

- Activating/Deactivating Dynamic Server Management during Operation

- Controlling Dynamic Server Management during Operation

- Troubleshooting

- z/VSE Considerations

### Dynamic Server Management Concepts

Unlike z/OS, under BS2000, z/VSE, a fixed number of server tasks/subtasks are started in Entire System Server in order to process user requests. Under z/OS, there is a 1:1 relationship between user and subtask, that is, there is one subtask started for each user.

Use of a fixed number of server tasks/subtasks is due to operating system architecture, as under both BS2000, z/VSE the main Entire System Server task may create only a limited number of tasks/subtasks.

A dispatcher gives user requests to individual servers. The servers use the security profile of the user and process the request accordingly. Under BS2000, the server with the least load will process the new request. Under z/VSE, the first available server will process the request. If none are available, the request will wait until a subtask is free.

However, when using a fixed number of tasks/subtasks, problems may occur. This design cannot adequately react to different workloads. In case of many requests, the servers may not be able to process the requests quickly enough, resulting in delays. Likewise, during idle times Entire System Server cannot release resources.

For this reason, the Dynamic Server Management (DSM) was created. As of Entire System Server Version 3.1.1 ( BS2000, z/VSE), it enables systems programming staff and operations to dynamically control servers, i.e., to start or stop them as necessary. A minimum number of servers are started during initialization of Entire System Server, which will be automatically increased in case of a large number of user requests up to a definable upper limit. Delays during request processing can thus be avoided to a large degree.

In case of idle times, servers are stopped until a definable lower limit is reached.

The dispatcher mentioned above determines if incoming requests can be processed with the current server configuration, and increases the number of servers if necessary.

A monitor function checks at regular intervals whether too many servers are idle and stops tasks/subtasks as necessary.

Under BS2000, the most important aid to recognizing bottlenecks is the queue depth as measured by the dispatcher, i.e., how many requests are pending for processing by a server. If this value reaches a definable limit, another server will be started and selected for processing the new request. Under z/VSE, new tasks are created when a new request is received and all active servers are busy with other requests (this will change in a future release).

Idle times are measured based on when a server is finished with a user request. If the monitor finds that the idle time exceeds that specified at startup, the server will be terminated.

### Configuring a Dynamic Server Environment

For Dynamic Server Management, various new startup parameters are required to explicitly switch on this operating mode and define basic data for its functionality.

Up to now, the startup parameter `NUMTASK` defined the number of server subtasks for the conventional static operating mode which is still available of course. If the new startup parameters are not used, the dynamic operating mode will remain inactive.

The following startup parameters are available for Dynamic Server Management:

Startup Parameters | Explanation
--- | ---
`SERVER-DYN` | Defines whether Dynamic Server Management is to be switched on (`YES`) or off (`NO`) at initialization. This may be changed via an operator command at any time.
`SERVER-MAX` | Defines the upper limit of the number of servers. This may be changed via an operator command at any time.
`SERVER-MIN` | Defines the lower limit of the number of servers. This may be changed via an operator command at any time.
`SERVER-NONACT` | Fixes the maximum idle time of a server. If the value is reached or exceeded, the server will be terminated if `SERVER-MIN` is smaller than the current number of servers.
`SERVER-QUEUE-DEPTH` | Fixes the depth of the task queue; if the server with the least load has reached this value, another server will be started if `SERVER-MAX` is greater than the current number of servers.
`SMFTIME` | z/VSE only - how often the monitor task will check for idle servers.

In dynamic operating mode, the startup parameter `NUMTASK` is used to define the initial number of servers. The following relationship exists between the parameters for the definition of the initial, upper or lower limit of running server tasks/subtasks:

    SERVER-MIN <= NUMTASK <= SERVER-MAX

The general recommendation for the operation of Entire System Server in dynamic operating mode is to define the parameter `SERVER-DYN=YES` and to leave all other parameters at their default values. If the default values are not sufficient under BS2000, we recommend decreasing the value for `SERVER-QUEUE-DEPTH` or to set it to 1, if necessary, so that there will not be any queues. However, the value of `SERVER-MAX` may limit the number of new servers started.

### Activating/Deactivating Dynamic Server Management during Operation

For simplified Dynamic Server Management administration, the operator command interface was enhanced so that most of the startup parameters can be set dynamically as well.

The values for `SERVER-DYN`, `SERVER-MAX`, and `SERVER-MIN` can be modified.

It is also not required to explicitly prepare the dynamic server environment at the time of initialization of Entire System Server. It may be activated by operator command at any time.

### Controlling Dynamic Server Management during Operation

The operator command `SERVERS` lists the information about the server load to reflect the current state of Dynamic Server Management.

The following output was generated during a test operation under BS2000:

      11:21:31 ADAI29 00113   OPER CMD: SERVERS
      11:21:31 XCO0016I 00113 Operator typed in: SERVERS.
      11:21:32 ESY0308I 00113 SERVER  STATUS  VP  CMD   USER   ACT  IDLE   VIEW.
      11:21:32 ESY0308I 00113 ------ -------- --- --- -------- --- ------- ----.
      11:21:32 ESY0308I 00113  2EF8  ACTIVE     2   2 DC1       Y       67    2.
      11:21:32 ESY0308I 00113  2EGK  ACTIVE     2   2 DC1       Y       48    2.
      11:21:32 ESY0308I 00113  2EGL  ACTIVE     0   0 ETB       N       10  190.

It indicates that Entire System Server currently operates three server tasks. The servers with the TSN `2EF8` and `2EGK` are active, while Server `2EGL` has not been used for 10 seconds; for details, see Operator Commands. The display under z/VSE is similar, with the exception of the values under the `SERVER` column.

The view `NATPROC-USERS` also returns information about the state of internal tasks - that is, the server as well - so that server control by means of a program is possible.

### Troubleshooting

You may experience in a heavy loaded System the Error Message `ESY5508 ADABAS response code 111`.

#### The following applies:

The Adabas (resp. Entire System Server) response code 111 is accompanied by the console message: `ESY0084W ALL TASKS ACTIVE - INCREASE "NUMTASK"`

It indicates that a request could not be serviced because all Entire System Server tasks are busy, or dedicated to a caller that needs his context preserved over multiple service calls. The customer action depends on the setting of the `SERVER-DYN` startup parameter:

If `SERVER-DYN=NO`:

- Stop Entire System Server and re-start it with an increased `NUMTASK` parameter

- Or issue operator command `SERVER-DYN=YES`, possibly followed by operator command `SERVER-MAX=nn` (where nn is greater than the number specified with the `NUMTASK` startup parameter.)

If `SERVER-DYN=YES` is in effect:

- Increase the number of tasks using operator command `SERVER-MAX`.

If you receive console message

`ESY0001I INVALID NUMERIC VALUE ENTERED`

Or

`ESY0056W nn TASKS ATTACHED (INSTEAD OF kk)`

the maximum number of subtasks in a VSE partition has been reached and no more server tasks can be created.

### z/VSE Considerations

Under z/VSE, there is a maximum number of 31 subtasks per partition. Since two subtasks are required by Entire System Server, this sets the maximum number of subtasks that can be assigned to both user tasks and Natural subtasks to 29. In addition, each concurrent use of the `IDCAMS` and `CATALOG` (`CATALOG` only when requesting information from a VSAM catalog) views requires a subtask, so `SERVER-MAX` and or `NUMTASK` may need to be set even lower than the maximum of 29.

## Run E-Mail Client

### General

`SEND-EMAIL` view implements a text-based mail client. See view description of `SEND-EMAIL` in the Entire System Server User's Guide for programming aspects and a sample program. The view processor requires additional startup parameters. See the section Startup Parameters in the Entire System Server Administration documentation for a description of the parameters `HOST-CODE-PAGE`, `JOBEMAIL`, `NUMMAIL`, `PRMEMAIL`, `SMTP-HOST`, `SMTP-PORT`, `TCP-STACK`.

Entire System Server creates a TCP/IP connection to the host that is configured as mail gateway. This connection runs in the separate E-Mail Manager Task on BS2000, in the user tasks on z/OS or in the server tasks on z/VSE. Therefore, a running TCP/IP stack is required and also running Domain Naming Services to resolve the own host name and the host name of the configured mail gateway. Contact your network and your mail administrator to determine if it is possible to establish a TCP/IP connection to the mail gateway.

### Requirements on z/OS

`SEND-EMAIL` view uses the `EZASMI` macro interface to request services from IBM's TCP stack.

The Entire System Server Started Task and all users requesting `SEND-EMAIL` view must be defined with a proper user ID for z/OS UNIX. Error message `ESY5897 Mailer response: errno 0156 in EZASMI INITAPI` reporting errno 156 (`EMVSINITIAL`) is returned as `ERROR-TEXT` if the requesting user ID is not properly defined for z/OS UNIX.. This error message is also issued if the `MAXPROCUSER` limit of z/OS Unix has been exceeded. In this case a higher value for `MAXPROCUSER` needs to be specified in the `BPXPRMxx` parmlib member.

### Requirements on z/VSE

`SEND-EMAIL` view uses the `EZASMI` macro interface to request services from the TCP stack. The `EZASMI` interface is supported by both Connectivity Systems, Inc. (including IBM), and Barnard Software, Inc.'s TCP/IP stack services.

When using the CSI or IBM product, be sure that a `DEFINE NAME` parameter is specified in the stack parameters, otherwise an EDCV002I error message may be issued to the console and an error message ESY5897 Mailer response: errno 2 in EZASMI GETHOST will be issued to the caller.

### Requirements on BS2000

E-Mail Manager Task requires the `SOCKETS` subsystem installed and running on the BS2000 host where Entire System Server node will be started.

If it is not possible to completely initialize the E-Mail Manager Task (`ESYMAIL`), the task will stop but does not cause a shutdown of Entire System Server. `ESYMAIL` will report errors on system console and more detailed diagnostics in the `SYSLST` file. `SEND-EMAIL` view will be disabled for the current Entire System Server session.

If Entire System Server is properly configured and the startup of `ESYMAIL` does not detect errors, the E-Mail Manager Task will run and service `SEND-EMAIL` requests until Entire System Server is stopped again.

## Zap Reports in Entire System Server

As of Version 3.1.1, Entire System Server prints a report of all applied Zaps at ESY startup. This information is determined during startup and is written to DDNAME `SYSPRINT` (z/OS), `SYSLST` (z/VSE) or `SYSLST01` (BS2000).

Note for BS2000:
Each ESY task except the console task generates this Zap report on `SYSLST01`. If `SYSLST01` is not assigned, no report will be created.

The following sample listing illustrates the report layout. It was created during tests under BS2000.

### Overview of Applied Zaps

      XC41001 XC41002 XC41003 XC41004 XC41005 XC41006 XC41007 XC41008 XC41009
      XC41010 XC41011 XC41012 XC41013 XC41014 XC41015 XC41016 XC41017

### CSECT Mapping

    CSECT    EP       DATE       TIME     ZAPS
      NPRINIT  01000000 2000-09-18 10:37:33 XC41001 XC41002 XC41003 XC41004 XC41005
                                            XC41006 XC41007 XC41008 XC41009 XC41010
                                            XC41011 XC41012 XC41013 XC41014 XC41015
                                            XC41016 XC41017
      CHKLINK  01000E58 2000-09-18 10:32:30 NONE
      CMDX2    010012A0 2000-09-18 10:32:38 NONE
      GETPARMS 01001878 2000-09-18 10:34:36 NONE
      LOAD2    01003330 2000-09-18 10:34:57 NONE
      NATPCMDL 010038A0 2000-09-18 10:36:15 NONE
      NATPNAT  01004180 2000-09-18 10:36:54 NONE
      NATPREP  01004A08 2000-09-18 10:37:04 NONE
      NATPSRV  010052D0 2000-09-18 10:37:12 NONE
      NATPSUBT 01005FD8 2000-09-18 10:37:21 NONE
      NATPUSR  01006780 2000-09-18 10:37:28 NONE
      NPROPHND 01006A38 2000-09-18 10:37:41 NONE
      SCANECET 010076D8 2000-09-18 10:37:56 NONE
      SYNCADA  01007F00 2000-09-18 10:38:19 NONE
      SYSINFO  01008298 2000-09-18 10:38:26 NONE
      TRACE    010086C0 2000-09-18 10:38:34 NONE
      WTO      01009438 2000-09-18 10:39:02 NONE
      XCOMINIT 01009DF0 2000-09-18 10:39:19 NONE
      XCOMMAIN 0100A3E8 2000-09-18 10:39:28 NONE
      XDBOPER  0100B1F8 2000-09-18 10:47:39 NONE
      XDBPRSTP 0100B4D0 2000-09-18 10:47:54 NONE
      XDBSTOP  0100B758 2000-09-18 10:48:03 NONE
      XDBTIME  0100BCC8 2000-09-18 10:48:14 NONE
      XCOMNUC  0100BFF0 2000-09-18 10:39:38 NONE
      XDBPROC  0100DAB8 2000-09-18 10:47:45 NONE
      ANSWER   0100EA90 2000-09-18 10:32:20 NONE

z/OS, z/VSE reports have a similar format.

The first part of the report lists all installed program corrections (`OVERVIEW OF APPLIED ZAPS`). The second part provides detailed information about the names of the program sections (`CSECT`), the entry points (`EP`), the creation date and time (`DATE` and `TIME`), and the installed corrections (`ZAPS`) per program section.

This information may help to get an overview about applied zaps. It is also useful for Software AG support.

## Ending Entire System Server

For information on how to terminate Entire System Server, see Operator Commands in the Entire System Server Administration documentation.

For BS2000, see How to Start/End Entire System Server on BS2000 in the section BS2000 Considerations in the Entire System Server Administration documentation.

### Return Codes Issued by Entire System Server at Termination

#### On z/OS, z/VSE

When Entire System Server terminates due to reasons other than an ABEND, a return code is issued. A return code `0` indicates no abnormal incidents occurred during the run. A return code `4` indicates that a subtask ABENDed at some time during the run; check the JES job log for details. A return code `8` indicates that Entire System Server never started due to a bad parameter or other reason; check the JES job log for details.

#### On BS2000

At program termination, the Entire System Server components set a return code, which is transferred to a monitoring job variable. The status display for successful execution is `C' $T 0000'`, the status for abnormal termination is `C' $A 0008'`.

### On this page

- Running System Automation Tools in Entire System Server
- Common Diagnostic Features
- Write-to-Spool for Natural
- Dynamic Server Management for Entire System Server
- Run E-Mail Client
- Zap Reports in Entire System Server
- Ending Entire System Server