z/OS Considerations

This document covers the following topics:


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.

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.