z/OS Considerations

#### Search Results

Search

# z/OS Considerations

This document covers the following topics:

- z/OS Access Method Modules

- z/OS Accounting

- Common JES Interface for z/OS

- APPC/MVS Definitions for the SYSTEM-COMMAND View

- z/OS Security Considerations

- Setting Up RACF Security for Operator Commands on z/OS

- Using Adabas Review with Entire System Server

- Configuring AT-TLS to Build a Secure Connection

## z/OS Access Method Modules

There are two access method modules available under z/OS:

### z/OS Access Method Module for CA-Librarian

If CA-Librarian is available at your site, you can install the CA-Librarian access method module as follows:

1. Set `&LIBRMOD` in source `NATPAML` to the name of the CA-Librarian batch module and set `&LIBROPT` to the default parameters of the batch module. These options can be modified dynamically in the Natural programs using the `OPTION` field in the views `LIB-UPDATE` and `WRITE-FILE`.

   Set `&SECALOC` in source `NATPAML` to the number of blocks for secondary allocation. The default of 10 blocks is normally sufficient, but this can be increased if you receive a NAT5995 error while writing CA-Librarian members.

2. Assemble the module `NATPAML` and link-edit it using the CA-Librarian load library. The link attributes `NON-REUSABLE` and `NON-REENTRANT` must be set. The module name must be `NATPAML`, no alias is necessary. The CA-Librarian `MACLIB` must precede the Entire System Server source library so that the correct `FAIRnn` CA-Librarian macro is used.

3. Add startup parameter `PRODUCT=L` to the Entire System Server startup parameters.

When accessing CA-Librarian using Entire System Server views, users must specify the product code `L` in the `PRODUCT` field.

### z/OS Access Method Module for CA-Panvalet

Set `&SECALOC` in source `NATPAMP` to the number of blocks for secondary allocation. The default of 10 blocks is normally sufficient, but this can be increased if you receive a NAT5995 error while writing CA-Panvalet members.

## z/OS Accounting

The Entire System Server can optionally collect accounting information. This information is available through the view `NATPROC-USERS` (see also the `LOOP` startup parameter in the section Startup Parameters).

### For z/OS only:

The layout of this user SMF record is as follows:

Location | Length | Format | Contents
--- | --- | --- | ---
Dec | Hex
0 | 0 | 2 | Binary | Length or record.
2 | 2 | 2 | - | Reserved.
4 | 4 | 1 | Binary | System indicator: | 8 - z/OS
5 | 5 | 1 | Binary | Record type; value is stated in `SMFRECORD` parameter.
6 | 6 | 4 | Binary | Time in 100th of a seconds, record was moved to SMF buffer.
10 | A | 4 | Packed | Date record was moved to SMF buffer (`00YYDDDF`).
14 | E | 4 | Character | `SYSID`.
18 | 12 | 8 | Character | User ID.
26 | 1A | 4 | Binary | CPU used in hundredths of a second
30 | 1E | 4 | Binary | Number of I/Os.

An SMF record is written:

- if a user logs off him/herself;

- if a user is logged off due to inactivity;

- if `SMFTIME` parameter was set and this time window popped;

- if Entire System Server terminates.

In all cases, the SMF parameter must be set.

## Common JES Interface for z/OS

The former JES2 and JES3 interfaces (before Release 3.1.1) have been rewritten and integrated into a Common JES Interface, exploiting the MVS subsystem interface functions 79 (`SYSOUT` API) and 80 (Extended Status).

The Common JES Interface need not be assembled during installation and therefore is distributed only as load module. It supports all JES2 and JES3 releases in service at the time of general availability of the current Entire System Server release. Support for new releases of JES2 and JES3 will be added via problem solutions.

All required security checks are done within the Common JES Interface and the `SYSOUT` API implementations using the SAF router interface. Therefore the former security exit `JESVRACF` is no longer required. However, for compatibility reasons, a dummy exit is provided that may be used to perform additional authorization functions.

### z/OS JES3 Considerations

The Common JES Interface now returns spool information from JES3 in the same way as from JES2, which is slightly different from the way spool information was returned from the JES3 interface of Entire System Server Version 2.2. To ease migration in a JES3 environment, the spool-related view processors will support either a "compatibility mode" or a "consistency mode". The mode is determined from the value specified for the `SPOOL` startup parameter. `SPOOL=JES3` will set the "compatibility mode", the "consistency mode" can be requested with "SPOOL=JESC".

The differences between the results from the Entire System Server Version 2.2.2 JES3 interface, the "compatibility mode" and the "consistency mode" for the views `SPOOL-QUEUE` and `SPOOL-FILES` can be obtained from the tables below. The "compatibility mode" will return the results like the Entire System Server Version 2.2.2 JES3 Interface whenever possible.

Applications that wish to exploit the JES3 "consistency mode" should consider the following issues:

- The current mode can be obtained from the `STARTUP-PARM` field of the `SYSTEM-INFO` view for the `SPOOL` keyword.

- `SPOOL-QUEUE` may return multiple entries for the same job, representing different sets of `SYSOUT` data sets with the same attributes.

- For a set of `SYSOUT` data sets with the same attributes there is no identifier. To identify the set of `SYSOUT` data sets, its common attributes must be specified.

- To select jobs by job class, its value must be specified in field `JOB-CLASS` of view `SPOOL-QUEUE`.

SPOOL-QUEUE | JES3 Interface Version 2.2.2 | "compatibility mode" | "consistency mode"
--- | --- | --- | ---
CARD-COUNT | - | - | X
CLASS 2 | (X) | (X) | X
DATE-ON-READER | - | - | X
DATE-XEQ-START | - | - | X
DATE-XEQ-STOP | - | - | X
DATX-ON-READER | X | X | X
DATX-XEQ-START | - | - | X
DATX-XEQ-STOP | - | - | X
DESTINATION | - | - | X
HOLD 1 | (X) | (X) | X
JOB-CLASS | - | - | X
JOB-ID | X | X | X
JOB-NAME | X | X | X
JOB-NUMBER | X | X | X
MESSAGE-CLASS | - | - | X
ORIGIN | X | X | X
PRIORITY | X | X | X
PROGRAMMER-NAME | - | - | X
QUEUE | X | X | X
RECORD-COUNT | - | - | X
SPOOL-UTILIZATION | X | X | X
STATUS | X | X | X
SYSTEM-ID | - | - | X
TIME-ON-READER | X | X | X
TIME-XEQ-START | - | - | X
TIME-XEQ-STOP | - | - | X
TIMX-ON-READER | X | X | X
TIMX-XEQ-START | - | - | X
TIMX-XEQ-STOP | - | - | X
TYPE 3 | (X) | (X) | X
USER | X | X | X

#### Notes:

1. The JES3 Interface and the "compatibility mode" return the `HOLD` status only for held jobs, not for held output.

2. The JES3 Interface and the "compatibility mode" always return the job class in field `CLASS`, there is no output class returned.

3. The JES3 Interface and the "compatibility mode" always return the value `JOB` in the `TYPE` field, even for STC's and TSU's.

The JES3 Interface and the "compatibility mode" return only one entry for a job on the output queue, even when there is output with different attributes.

SPOOL-FILES | JES3 Interface Version 2.2.2 | "compatibility mode" | "consistency mode"
--- | --- | --- | ---
BURST | - | - | X
CHARS 1 | X | X | X
CLASS | X | X | X
COMPACT |  |  |
COPIES | X | X | X
DATA-SET 4 | X | X | X
DATA-SET-KEY 4 | X | X | X
DDNAME | X | X | X
DESTINATION-NODE |  |  |
DESTINATION-REMOTE |  |  |
DSNAME 2 | X | X | X
FCB 1 | X | X | X
FLASH | X | X | X
FORM 1 | X | X | X
HOLD | X | X | X
IDENTIFIER 2 | X | X | X
JOB-NAME | X | X | X
JOB-NUMBER | X | X | X
LINECT |  |  |
LRECL | X | X | X
PRINT-MODE | - | - | X
PROCNAME | X | X | X
RECFM | X | X | X
RECORD-COUNT | X | X | X
STEPNAME | X | X | X
TRC |  |  |
TYPE | X | X | X
UCS | - | - | X
WRITER 3 | X | X | X

1. The JES3 Interface and the "compatibility mode" do not return `FORM`, `CHARS` and `FCB`, if the values match the installation defaults.

2. The JES3 Interface and the "compatibility mode" return the designated ddname (procstepname.jobstepname.ddname) in fields `DSNAME` and `IDENTIFIER`, not the spool data set name.

3. The JES3 Interface and the "compatibility mode" return the general type of output (`PRT`/`PUN`) in field `WRITER` for `SYSOUT` data sets in the Writer Queue.

4. The JES3 Interface returns values in fields `DATA-SET` and `DATA-SET-KEY` that may be different from those returned by the "compatibility mode" and "consistency mode".

## APPC/MVS Definitions for the SYSTEM-COMMAND View

The `SYSTEM-COMMAND` view processor has been rewritten to invoke an APPC/MVS transaction program to execute the requested TSO/E command(s). The transaction program will then be initiated by the APPC/MVS transaction scheduler, and the output from the TSO/E command will be returned to the `SYSTEM-COMMAND` view.

The following definitions are required for the transaction program and its resources. You may need assistance from your systems programmer and from your network administrator to implement these definitions.

1. Define the logon mode table `LOGMODES` with entry `APPCHOST`, if not already present, or an equivalent logon mode entry to be used as default for the LU defined above. The source for the `LOGMODES` table can be found in the `ATBLMODE` member of `SYS1.SAMPLIB`.

   A new logon mode table needs to be activated with the VTAM command `MODIFY TABLE`.

2. Define the APPC/MVS LU as an application to VTAM. If you run Entire System Server on multiple systems, define different application names for each system. For multiple Entire System Server address spaces on one system, only one local APPC/MVS LU needs to be defined.

       NPRLU01  APPL  ACBNAME=NPRLU01,        ACBNAME FOR APPC                C
                      APPC=YES,                                               C
                      AUTOSES=0,                                              C
                      DDRAINL=NALLOW,                                         C
                      MODETAB=LOGMODES,                                       C
                      DLOGMOD=APPCHOST,                                       C
                      DMINWNL=5,                                              C
                      DMINWNR=5,                                              C
                      DRESPL=NALLOW,                                          C
                      DSESLIM=10,                                             C
                      LMDENT=19,                                              C
                      PARSESS=YES,                                            C
                      SECACPT=ALREADYV,                                       C
                      SRBEXIT=YES,                                            C
                      VPACING=1

   The definition needs to be activated with the VTAM command `VARY ACT`.

3. Define the local LU in parmlib member `APPCPMxx` (APPC/MVS Configuration).

   If you run Entire System Server on multiple systems, define local LUs using different names for each system. The LU name(s) must correspond to the VTAM application definitions for APPC/MVS (see Step 2).

       LUADD ACBNAME(NPRLU01) TPDATA(SYS1.APPCTP) TPLEVEL(USER)

   The definition needs to be activated with the `SET APPC=xx` system command. Note that a base LU for the APPC/MVS transaction scheduler is also required in the configuration.

4. Define a class of transaction initiators in parmlib member `ASCHPMxx` (APPC/MVS Transaction Scheduler). You may also use a class that you have already defined. The minimum number of started transaction initiators should correspond to the expected number of transactions running at a time.

       CLASSADD CLASSNAME(A) MSGLIMIT(1000) MAX(10) MIN(1) RESPGOAL(1)

   The definition needs to be activated with the `SET ASCH=xx` system command.

5. Verify that the APPC and ASCH address spaces for APPC/MVS and the transaction scheduler are active on the system. If not, they need to be started using the commands:

       START APPC,SUB=MSTR,APPC=xx
       START ASCH,SUB=MSTR,ASCH=xx

   To start the `APPC` and `ASCH` address spaces automatically at IPL, you can add these `START` commands to the `COMMNDxx` member of your parmlib concatenation.

6. Define the transaction program in parmlib member `IKJTSOxx` as an authorized program by adding `XCOMTP46` to the `AUTHPGM NAMES` statement:

       AUTHPGM NAMES(..., XCOMTP46 ...)

   The definition needs to be activated with the TSO/E command `PARMLIB UPDATE(xx)`.

7. Define the transaction program to APPC/MVS using the Administration Utility:

       //TPADD   EXEC PGM=ATBSDFMU
       //SYSPRINT DD  SYSOUT=*
       //SYSSDLIB DD  DSN=SYS1.APPCTP,DISP=SHR
       //SYSSDOUT DD  SYSOUT=*
       //SYSIN    DD  DATA,DLM=ZZ
            TPADD
                 TPNAME(SAG.NPRvrs.XCOMTP46)
                 ACTIVE(YES)
                 TPSCHED_DELIMITER(##)
                    CLASS(A)
                    TPSCHED_TYPE(STANDARD)
                    JCL_DELIMITER(END_OF_JCL)
       //NPRTPTSO JOB (&SYSUID),MSGCLASS=X,MSGLEVEL=(1,1),REGION=4096K
       //TSOE    EXEC PGM=IKJEFT01,PARM='CALL ''NPRvrs.MVSLOAD(XCOMTP46)'''
       //SYSTSPRT DD  UNIT=VIO,DISP=(,,DELETE),
       //             DCB=(RECFM=FB,LRECL=133,BLKSIZE=13300,DSORG=PS)
       //SYSTSIN  DD  UNIT=VIO,DISP=(,,DELETE),
       //             DCB=(RECFM=FB,LRECL=80,BLKSIZE=800,DSORG=PS)
       //SYSABEND DD  SYSOUT=X
       //ESYTRACE DD  SYSOUT=X
       END_OF_JCL
       ##
       ZZ
       //

   The definition is active when the utility was executed successfully.

8. Define the APPC/MVS resource names to be used in the Entire System Server startup parameters `APPC-TPNAME`, `APPC-LUNAME` and `APPC-MODENAME`. To activate these definitions, Entire System Server needs to be restarted.

9. To verify the APPC/MVS definitions for the `SYSTEM-COMMAND` view transaction program, logon to Natural using library `SYSNPE`, run the sample program for the view `SYSTEM COMMAND` and enter the TSO/E command `TIME`. If all definitions are active, you will get a response like:

       READY
       TIME
       IKJ56650I TIME-07:17:07 PM. CPU-00:00:01 SERVICE-9829 SESSION-00:00:02 JULY 17, 2007
       READY
       END

## z/OS Security Considerations

### Security Logon

The Entire System Server region accesses datasets and other resources as requested by the Natural user. Therefore, if a security system is installed (identified by the `SECURITY` startup parameter), the Natural user must identify himself or herself 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. `SECURITY` will be called to validate these parameters. If validation is successful, `SECURITY` will build a control block for the user. This control block will be used for future validations.

If the user attempts to access a view before logging on, Response Code 510 (`LOGON REQUIRED`) will be returned. However, if the startup parameter `AUTOLOG` is set to `YES`, an implicit logon is performed as part of the first user request. A password is only required if the Natural user ID does not match the user ID defined in the `SECURITY` system.

If the `APPL` resource class is active in the security system, the Entire System Server address space has to be defined as an application with its `STC` or job name and the users need to be authorized to access that Entire System Server application.

When a view requests access to resources such as datasets, batch jobs, etc., `SECURITY` will be called to check whether access is allowed (see the following section). If access is not allowed, the user will receive an appropriate error message.

The Entire System Server online tutorial contains a sample logon program that uses the view `NATPROC-LOGON`.

The logon operation is not needed if Entire System Server is used in single-user mode.

If no security system interface is requested (`SECURITY=NONE`), no security check is performed: all logon attempts will be successful. In this case, each attempt to access an object which is protected by security is treated in the same way as defined for the Entire System Server started task.

If ACF2 is installed at your site, you must define Entire System Server as the multi-user address space (using the parameter `MUSASS` in ACF2).

If TOP-SECRET is installed, the following parameters must be set:

     FAC (USERS=NAME=PROCESS)
     FAC (PROCESS=ACTIVE,NOASUBM)
     FAC (PROCESS=NOABEND,AUTHINIT)
     FAC (PROCESS=MULTIUSER,WARNPW)
     FAC (PROCESS=MODE(FAIL),PGM=NAT
     FAC (PROCESS=UIDACID=8,ID=P)

## Setting Up RACF Security for Operator Commands on z/OS

Assemble the distributed source for the `OPRVRACF` and `VTMVRACF` exits with conditional assembly variable `&RACF` set to `0`, in order to generate the `RACROUTE` code for validating the `OPERCMDS` resource class. Set the `&JESC` to your JES command character. The default is the dollar sign ($).

If `&RACF` is set to `1`, the `OPERATIONS` flag in the `ACEE` control block will be examined instead of the `RACROUTE` approach.

## Using Adabas Review with Entire System Server

Adabas Review (Version 4.3.2 or above) may be used with Entire System Server (Version 3.4.1 or above) to collect performance data in local mode for requests originating from Natural (Version 4.2.2 or above). To enable Adabas Review in local mode with Entire System Server, the following steps need to be taken:

- Specify your Review load library in the `STEPLIB` concatenation for Entire System Server.

- Verify that you have one of the following Zaps applied:

  - `RD432100` for Review Version 4.3.2 or

  - `RD441017` for Review Version 4.4.1

- Additional DD statements for data sets used by Review will be needed in your JCL. Please see the Adabas Review documentation to determine which `RVU...` data sets you need and add the corresponding DD statements to your JCL for Entire System Server.

- Specify `REVIEW=YES` in your startup parameters for Entire System Server.

  If you have used the startup parameter `UEX4=RAOSEXIT` with an earlier release of the Entire System Server, please remove it as it is no longer supported.

- Specify the Natural profile parameter `ADAPRM=ON` for the Natural environments that you want to collect data from.

- If you want to report calls from a Batch Natural environment running as a subtask within the Entire System Server address space (such as subtasks of ESM products), re-link your `ADALNKR` module with the required Review modules as described in the section Implement Support for Reporting from Batch Natural of the Installation and Operations for z/OS documentation for Adabas Review.

## Configuring AT-TLS to Build a Secure Connection

Define a traffic descriptors:

    Protocol: TCP
    Localport all
    Remoteport 993
    Connection direction: either
    Jobname <jobname of Entire System Server>
    Userid  -
    AT-TLS configuration index 0

Configuration associated with this AT-TLS Application:

    AT-TLS configuration index 0
    Handshake Role Client
    Key ring: your kdb and sth file
    Certificate label –
    Application controlled off
    Secondary Map off
    Handshake timeout 10 seconds

See also z/OS Communications Server > z/OS Communications Server:IP Configuration Guide > Server applications Application Transparent Transport Layer Security data protection > Options for configuring AT-TLS security under https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r2.cs3/cs3.htm.

### On this page

- z/OS Access Method Modules
- z/OS Accounting
- Common JES Interface for z/OS
- APPC/MVS Definitions for the SYSTEM-COMMAND View
- z/OS Security Considerations
- Setting Up RACF Security for Operator Commands on z/OS
- Using Adabas Review with Entire System Server
- Configuring AT-TLS to Build a Secure Connection