This section describes common Entire System Server features.
This document covers the following topics:
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. 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.
This section offers an overview of the interfaces between ESY and SAT and deals with the configuration in the overall context.
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.
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.
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, 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.
There are two common diagnostic features:
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.
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.
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 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.
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).
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. A
TRACE DD statement is required. The data is fixed length, 288 bytes.
The following list supplies information about the file attributes:
DCB attributes of RECFM=FB, LRECL=288
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.
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.
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. Output is written to an optional file - TRACEOUT
DD.
ESYTRACE is controlled by parmameters, which are passed to it via the
PARM parameter of the JCL/JCS EXEC statement.
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 to be processed as
input (FILE-MODE ).
Keyword parameters:
-d | --displ
The prepared result data is transferred to SYSPRINT.
-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.
For the format of the optional output file, the following file attributes are required:
LRECL=315, RECFM=FBA
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 our support. It contains no user data whatsoever other than the user ID.
For real-time monitoring of error situations, these steps should be used:
Start Entire System Server
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.
When in MONITOR-MODE, ESYTRACE can
only be terminated by means of the operator command
QUIT. Issue the QUIT
command as follows:
F stcname,QUIT
Notes:
This section covers the following topics:
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.
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.
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:
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".
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.
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.
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:
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: |
||||
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
|
||||
Form
RMT
|
Describes the form control buffer for JES. This value is transferred to JES which handles the processing. You can find the name of the JES system in the
destination field within the |
||||
| 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:
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)
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 user tasks. 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.
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.
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.
The following sample listing illustrates the report layout. It was created during tests under BS2000.
XC41001 XC41002 XC41003 XC41004 XC41005 XC41006 XC41007 XC41008 XC41009 XC41010 XC41011 XC41012 XC41013 XC41014 XC41015 XC41016 XC41017
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 |
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 our support.
For information on how to terminate Entire System Server, see Operator Commands in the Entire System Server Administration documentation.
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.