This document covers the following topics:
All modules required to perform an Entire System Server function are
dynamically loaded into the caller's address space at request. You must
therefore assign the Entire System Server Module Library to link name
DDLIB2 before the Natural session is started.
A startup parameter file should be assigned to link name
PARMS. If not, the default values for all startup parameters are
used as far as they exist. For example, the parameter
PRODUCT has no default and therefore no LMS functions
can be performed if no startup parameter file is assigned.
The Entire System Server session is terminated when the Natural session is terminated.
To use Entire System Server in multi-user mode, an Entire System
Server node must have been started, that is, the Entire System Server
ESYMAIN task must have been started under TSOS. All other tasks
required for an Entire System Server node will then be automatically started by
the ESYMAIN task. All tasks are running with the same user ID i.e.
TSOS. See also Step 8: Edit the Entire
System Server Jobs in the
Installation for
BS2000/OSD documentation.
This mode is a variation of the existing Multi-User Mode. Therefore,
parameter SERVER-PER-USER was introduced with NPR361.
SERVER-PER-USER=YES is used to start ESYSERV tasks as jobs under
the user ID of the requesting user but not as privileged TSOS tasks. This
simplifies the request processing in the Entire System Server. The Operating
System performs all the necessary security checks. There is no need to do such
a check in ESY anymore. Features like Coowner-Support are supported with the
Server-per-User Mode.
The Server-per-User Mode is based on the privileged /ENTER and the dynamic server feature.
The initialization of NPR361 modifies the following parameter settings
internally if SERVER-PER-USER=YES was specified:
AUTOLOG = NO
JOBENT = YES
SDF-P = NO
SECURITY = BS2
SERVER-DYN = NO
The job control E.ESYSERV must not contain a user ID for
the assignment of the SYSLST files because all users are using
this job control. The module libraries NPR361.MOD and
NPR361.USER.MOD must be cataloged as shareable and must reside on
a pubset accessible by all users.
Only one ESYSERV task is started under TSOS during
initialization to handle requests like SYSTEM-INFO and
NATPROC-USERS. These views do not require a user being logged
on.
Parameter NUMTASK is ignored at startup.
NPR361 starts an ESYSERV task whenever a user issues a
NATPROC-LOGON. LOGON-ID, ACCOUNTING and
PASSWORD of the NATPROC-LOGON request are used for
the /ENTER command and an error is returned if there was a problem
with the supplied credentials. This procedure does not require a privileged
/ENTER.
The user specific ESYSERV task is stopped after elapsed SERVER-NONACT. The next user request will not find a running ESYSERV task. In order to avoid an extra NATPROC-LOGON, a privileged /ENTER has to be used since the password is not known at that time
There are several ways to terminate an Entire System Server node. The usual method is to issue the console command
/INTR tsn,ADAEND
where tsn is the TSN assigned to the
ESYMAIN task.
This will automatically end all tasks belonging to that Entire System Server node.
For information on how to terminate Entire System Server via operator command, see Operator Commands in the Entire System Server Administration documentation.
Another way to terminate an Entire System Server node is to issue
FUNCTION= 'XEND' in the view processor NATPROC-USERS.
As of Version 3.1.1 of Entire System Server, you can run the program
ESYSTOP to shutdown ESY. It must be executed with the same user ID
as the Entire System Server, that is, as user TSOS.
The program ESYSTOP is driven by parameters obtained from
SYSDTA. Job name or TSN of the ESYMAIN task can be
specified. The following syntax must be used for the parameters:
-J jobname | --JNAME jobname -T tsn | --TSN tsn
The parameter --JNAME is recommended for a
generic setup of program ESYTRACE.
A sample job is listed in Step 8: Edit the Entire System Server Jobs in the Installation for BS2000/OSD documentation.
Entire System Server under BS2000/OSD consists of several tasks.
The ESYMAIN task is started manually by the operator or
by a startup script. This main task spawns a number of other tasks according to
the definitions in the startup parameter file.
Problems arise, if the JOB-CLASS-LIMIT of the operating
system is exhausted.
Entire System Server cannot work properly, if some ESY tasks are still hold in the wait queue. This state must be avoided by appropriate operator interventions.
A timer-controlled routine in the ESYMAIN task regularly
checks the state of all ESY tasks,for example, the status of the started
ESYSERV tasks and their workload.
Communication between the different ESY tasks is established via Eventing and Common Memory Pools. Forward Eventing is used for performance reasons.
The Natural applications and Entire System Server use the Adabas communication for transport of user data and for mutual communication between the different address spaces. The ESY node is addressable like an Adabas nucleus and thus visible via appropriate utilities.
The library concept of Entire System Server under BS2000/OSD has been completely revised for Version 3.1.1.
The modules are link-edited to reduce the ESY startup duration. Apart from that, there is a strict distinction between the delivery library and the user library. While the delivery library contains the original ESY modules only, Customers user exits are kept in the ESY user library.
All ESY startup jobs contain the assignment of the ESY module library
via LINK-NAME 'DDLIB2' and the assignment of a customer-specific
ESY user library via LINK-NAME 'BLSLIB00'. This user library is
searched for required modules alternatively, if nothing was found in the
library assigned via LINK-NAME 'DDLIB2'.
To run different configurations, some modules must be loaded dynamically.
The Server-per-User Mode requires access of all ESY users to the module libraries assigned in the job control of the ESYSERV task. Therefore, these libraries have to reside on a pubset accessible by all ESY users and they have to be shareable.
As of Version 3.1.1, all Entire System Server components run in
AMODE 31 (AMODE = addressing mode). This is
independent from settings in the job control.
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'.
Entire System Server enables the operation of System Automation Tools (e.g., Entire Output Management (EOM), Entire Operations (EOR)) as subtasks in the address space of ESY (z/OS, z/VSE) or as pseudo subtasks, i.e., standalone tasks (BS2000/OSD. 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.
This section offers an overview of the interfaces between ESY and SAT and deals with the configuration in the overall context.
As Natural subtasks are implemented as separate tasks under
BS2000/OSD, 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)
and as of ESY Version 2.2.2, 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 ESY 3.1.1,
this job skeleton is definable as part of the ESY startup file.
ESY 3.1.1: NATURAL-SUB-TASK job skeleton as part of the ESY startup parameter file
The job skeleton must not be converted into object module format
any more. It can be defined at any location in the ESY startup parameter file
and must be started using the keyword SATSKEL-BEGIN and terminated
with the keyword SATSKEL-END.
The jobs P.NSBTSKIS and P.NSBTSKSD are
still delivered as ESY source library elements, but they are only included for
compatibility reasons.
The following abridged example of an ESY startup parameter file illustrates the keyword usage:
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.
Starting with ESY 3.1.1, the enhanced LIST function of
view NATPROC-USERS displays all internal tasks in addition to the
ESY users, if the new field FULL-SCAN = 'YES' has been specified.
It allows to control ESY tasks with a Natural program.
The operator command SHUTDOWN stops SAT
components. New with ESY 3.1.1 is the operator command START
ALL to restart SAT without restarting ESY. The SAT mother task
will be started again to respawn all configured ESM monitors.
START ALL may be used only if the entire SAT
environment has previously stopped on its own or has been stopped by operator
command SHUTDOWN ALL. Both commands in conjunction
allow to "bounce" SAT during normal operation of ESY.
Please note that the operator command
SHUTDOWN can address individual SAT products via
parameters while the START command only accepts
parameter ALL.
Entire System Server must stop all NATURAL-SUB-TASKS
before shutting down. The stop request is published by ESY to all ESM monitors.
Having communicated the termination information, ESY checks the status of the
NATURAL-SUBTASKS over short time intervals. If they have
terminated on their own, shutdown will be continued. In the meantime, user
requests are still processed, as if the shutdown command had not been issued.
This procedure is called "Deferred Shutdown".
New startup parameter SHUTDOWN-MAX-DELAY limits
the Deferred Shutdown to a specified number of seconds. If the time limit has
been exceeded, Entire System Server will terminate without properly closing
down the SAT tasks.
If this situation occurs, you must check why the SAT products did not stop within the defined time interval. In this case, Software AG support should be consulted, if necessary.
As the SAT monitors have wait cycles,
SHUTDOWN-MAX-DELAY=180 should be used initially. If all
NATURAL-SUB-TASKS are stopped, the ESY termination will be
continued without further delays.
The Entire System Server tasks access datasets and other resources as requested by the Natural user. To be able to do this for various users, the Entire System Server must run under BS2000/OSD user ID TSOS. Users' access rights are checked by the Entire System Server in order to provide access to BS2000/OSD objects in the same range as if working under TIAM. Therefore, the Natural user must identify himself to Entire System Server before any view can be accessed.
A logon operation must be performed, specifying the user's system user
ID and password. If SECURITY=BS2 was specified in startup
parameters, user ID and password are checked against the system's user
definition file (TSOSJOIN). If this validation is successful, the user ID will
from then on be used for future validations until it is changed by another
logon operation.
If the user attempts to access a view before logging on, Response Code
510 (LOGON REQUIRED) is returned. However, if the
startup parameter AUTOLOG is set to YES, an
implicit logon is performed as part of the first user request.
If the Natural user ID (BS2000/OSD logon user ID for batch, or TIAM,
*USER for openUTM) is not defined in
BS2000/OSD, Response Code 510 (LOGON REQUIRED) is
returned. For Natural/UTM, TSOS is not allowed as
*USER and will be rejected.
The Entire System Server online tutorial contains a sample logon program that uses view NATPROC-LOGON.
The logon operation is not needed if Entire System Server is used in single-user mode.
If SECURITY=USER is specified in the startup parameters,
exit USERLSEC is called to check the user ID and password as
required at your site, and not against the system's user definition file
(TSOSJOIN). For a sample exit USERLSEC, see the
supplied Source Library.
If no security system interface is requested (startup parameter
SECURITY=NONE), no security check is performed: all logon attempts
will be successful. If in this case the Natural user ID is not defined in
BS2000/OSD, only functions which do not require a BS2000/OSD user ID are
available (such as EVENTING).
This mode was introduced with ESY 3.6.1 and is more effective than the
Multi-User Mode. The ESYSERV task that has been started for the
requesting user runs with the same user ID. There is no need to perform extra
security checks. Access to Operating System resources is executed in the
related ESYSERV user task but not in a privileged TSOS task. This
simplifies the security requirements since all checks are done by the Operating
System itself. The ESYMAIN task sets following parameters if
SERVER-PER-USER=YES was specified:
AUTOLOG = NO
JOBENT = YES
SDF-P = NO
SECURITY = BS2
SERVER-DYN = NO
If the Siemens software product SECOS is installed at your site, please note that the Entire System Server must be authorized to access any object that any of its users should be able to access.
This means that the Entire System Server user ID (TSOS) has to be
defined in every access control list (ACL) of those objects. For SECOS V2 it is
sufficient to define the program ESYSERV from the Entire System
Server Module Library in any GUARD concerned, if GUARDs are used.
There is no need to apply extra security definitions for ESY. The
ESYSERV task runs with the user ID of the requesting user.
The Entire System Server can run without the UCON
interface. However, it is required if you wish to use views
SEND-MESSAGE or CONSOLE.
The UCON interface of Entire System Server is activated by
a separate task which opens a DCAM application and connects to
UCON ($CONSOLE).
To enable the UCON interface task to connect to
UCON, an authorization name must be defined for Entire System
Server in BS2000/OSD generation and this name must be defined as BS2000/OSD
user ID. This user ID, as well as the password defined for it must be specified
as parameter of program ESYCONS in the JCL to start the Console Task of Entire
System Server. (See also Step 8: Edit the Entire
System Server Jobs in the Installation for
BS2000/OSD documentation.)
The user ID must be authorized to issue certain operator commands. ESY
does not require operator command authorization keys but the ESM monitors do.
Therefore, the user ID must be authorized to issue all operator commands needed
by the ESM monitors to support full functionality. For example, Entire Output
Management needs the authorization key of operator command
/CANCEL-JOB.
The required authorization keys for the UCON user ID are
listed in the documentation of the various ESM products.
If your application issues operator commands, the UCON
user ID must be authorized by the Administrator to execute that command.
With startup parameter CONACCESS, the use of
console functions can be restricted for all users on the respective node.
If WRITE is specified for CONACCESS, an exit
can be used to further restrict the use of the OP-CMD function of
the CONSOLE view. Whenever the CONSOLE view is called
with FUNCTION=OP-CMD, the USERCSEC module in the
Entire System Server User Module Library gets control (if it exists). The
caller's user ID, as well as the command string, is passed to the exit as input
parameters and the exit checks whether the user is authorized to issue the
command. If the user exit USERCSEC does not exist, all operator
commands are accepted.
For a sample exit USERCSEC, see the supplied Source
library. For a description of the CONACCESS
parameter, see the section Startup Parameters.
The SYSTEM-COMMAND view allows to issue a BS2000/OSD
command in a Natural program. The view passes the data to the macro command
language processor and returns the result to the calling Natural application.
An exit must be activated to restrict the use of system commands.
Whenever the SYSTEM-COMMAND view is called, the
USERSSEC module in the Entire System Server User Module Library
gets control (if it exists). The caller's user ID, as well as the command
string, are passed to the exit as input parameters and the exit checks whether
the user is authorized to issue the command. If user exit USERSSEC
does not exist, view SYSTEM-COMMAND is completely disabled.