BS2000/OSD Considerations

This document covers the following topics:


How to Start/End Entire System Server on BS2000/OSD

Single-User Mode

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.

Multi-User Mode

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.

Server-per-User Mode

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.

Changes within the Entire System Server Initialization (for version 3.6.1 or above)

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.

Changes within the Entire System Server processing

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

Shutdown of Entire System Server on BS2000/OSD

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.

Details for Running Entire System Server on BS2000/OSD

Tasks

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

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.

Library Concept on BS2000/OSD for Entire System Server

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.

Program Characteristics

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

Aspects of Running System Automation Tools in Entire System Server on BS2000/OSD

General

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.

Activating SAT during Start of Entire System Server

Start of SAT under BS2000/OSD

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.

Recently Introduced Startup Parameters under BS2000/OSD

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

Control of SAT during Entire System Server Operation

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.

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

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.

Deactivating SAT during Entire System Server Stop

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.

BS2000/OSD Security Considerations

Multi-User Mode

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

Server-per-User Mode

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

BS2000/OSD SECOS Considerations

Multi-User Mode

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.

Server-per-User Mode

There is no need to apply extra security definitions for ESY. The ESYSERV task runs with the user ID of the requesting user.

BS2000/OSD UCON Interface

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.

BS2000/OSD System Command Interface

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.