Common Entire System Server Features

This section describes common Entire System Server features.

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. Please see the Installation for z/VSE documentation for further details.

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:

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:

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:

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) 

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:

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