BS2000 Considerations

#### Search Results

Search

# BS2000 Considerations

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

This document covers the following topics:

- How to Start/End Entire System Server on BS2000

- Details for Running Entire System Server on BS2000

- Aspects of Running System Automation Tools in Entire System Server on BS2000

- BS2000 Security Considerations

- BS2000 SECOS Considerations

- BS2000 UCON Interface

- BS2000 System Command Interface

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

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

### 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

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

## Details for Running Entire System Server on BS2000

- Tasks

- Communication

- Library Concept on BS2000 for Entire System Server

- Program Characteristics

### Tasks

Entire System Server under BS2000 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 for Entire System Server

The library concept of Entire System Server under BS2000 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

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

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)

- 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

- 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 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 user ID TSOS. Users' access rights are checked by the Entire System Server in order to provide access to BS2000 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 logon user ID for batch, or TIAM, `*USER` for openUTM) is not defined in BS2000, 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, only functions which do not require a BS2000 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 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 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 generation and this name must be defined as BS2000 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.

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 System Command Interface

The `SYSTEM-COMMAND` view allows to issue a BS2000 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.

### On this page

- How to Start/End Entire System Server on BS2000
- Details for Running Entire System Server on BS2000
- Aspects of Running System Automation Tools in Entire System Server on BS2000
- BS2000 Security Considerations
- BS2000 SECOS Considerations
- BS2000 UCON Interface
- BS2000 System Command Interface