Installation for z/OS

It is recommended that you read this section from beginning to end before starting the installation process.

This document covers the following topics:


Installation Medium

The installation medium contains the datasets listed in the table below. The sequence of the datasets is shown in the Software AG Product Delivery Report which accompanies the installation tape.

If used in the following document, the notation vrs or vr stands for the relevant version, release, system maintenance level number of the product.

Dataset Name Contents
MLCvrs.JOBS

Sample job library for Software AG's mainframe license check software

Notes:

  1. The acronym "vrs" in the library name represents the version of the license check software, not the version of the Entire System Server.
  2. For more information on the license check software, see Software AG Mainframe Product Licensing.
MLCvrs.LOAD

Load library for Software AG's mainframe license check software including the LICUTIL license utility

Notes:

  1. The acronym "vrs" in the library name represents the version of the license check software, not the version of the Entire System Server.
  2. For more information on the license check software, see Software AG Mainframe Product Licensing.
NPRvrs.JOBS Entire System Server installation jobs
NPRvrs.LOAD Entire System Server load library
NPRvrs.SRCE Entire System Server source library
NPRvrs.INPL Entire System Server DDMs, a tutorial and error messages
NPRvrs.DATA Predict data for the Entire System Server
NPRvrs.LICS

Product license file

For more information on the license check software, see Software AG Mainframe Product Licensing.

How to Copy Data Sets from Tape to Disk

Copy the data sets from the supplied installation medium to your disk before you perform the individual installation procedure for each component to be installed.

The way you copy the data sets depends on the installation method and the medium used:

  • If you use System Maintenance Aid (SMA), refer to the copy job instructions provided in the System Maintenance Aid documentation.

  • If you are not using SMA and want to copy the data sets from CD-ROM, refer to the README.TXT file on the CD-ROM.

  • If you are not using SMA and want to copy the data sets from tape, follow the instructions in this section.

This section explains how to copy all data sets from tape to disk.

Step 1: Copy Data Set COPY.JOB from Tape to Disk

  • Modify the following sample job according to your requirements:

    //SAGTAPE JOB SAG,CLASS=1,MSGCLASS=X
    //* ---------------------------------
    //COPY EXEC PGM=IEBGENER
    //SYSUT1 DD DSN=COPY.JOB,
    // DISP=(OLD,PASS),
    // UNIT=(CASS,,DEFER),
    // VOL=(,RETAIN,SER=tape-volser),
    // LABEL=(2,SL)
    //SYSUT2 DD DSN=hilev.COPY.JOB,
    // DISP=(NEW,CATLG,DELETE),
    // UNIT=3390,VOL=SER=disk-volser,
    // SPACE=(TRK,(1,1),RLSE),
    // DCB=*.SYSUT1
    //SYSPRINT DD SYSOUT=*
    //SYSIN DD DUMMY
    //

    where:

    tape-volser is the VOLSER of the tape, for example: T12345,
    hilev is a valid high-level qualifier, and
    disk-volser is the VOLSER of the disk.

  • Execute the job to copy the data set COPY.JOB to your disk.

Step 2: Modify hilev.COPY.JOB on Your Disk

  • Modify hilev.COPY.JOB according to your requirements:

    Set EXPDT to a valid expiration date, for example, 99365.

    Set HILEV to a valid high-level qualifier, for example, USERLIB.

    Set LOCATION to a storage location, for example, STORCLAS=ABC or UNIT=3390,VOL=SER=USR123.

Step 3: Submit COPY.JOB

  • Execute hilev.COPY.JOB to copy single, multiple, or all data sets to your disk.

Installation Procedure

Step 1: Scratch Libraries SYSNPE and SYSNPR

(Job I051, Step 1100)

If you are upgrading from a previous version of the Entire System Server, scratch libraries SYSNPE and SYSNPR from your existing installation. Otherwise, skip this step.

Step 2: Load the INPL File

(Job I061, Step 1100)

Use the Natural system command INPL (which is described in the Natural System Commands documentation) in order to load the Entire System Server system objects (dataset NPRvrs.INPL).

This loads the following libraries:

Library File Contents
SYSNPR FNAT Installation aid (define DBIDs and define views to Natural Security)
SYSNPE FNAT Online tutorial
SYSNPEH1 FNAT Help texts (English)
SYSNPEH2 FNAT Help texts (German)

Step 3: Change the Natural Parameter Module

Add the ASIZE parameter and the following macro to the Natural parameter module; then assemble and link it. For information on how to activate this Natural parameter module for your Natural environment, refer to the Natural Installation documentation for mainframes.

ASIZE=64
NTDB PROCESS,148

ASIZE specifies the size of the auxiliary buffer. The range of possible values for this parameter depends on the version of Natural. For example, for version 4.2 and below the minimum value is 36 KB and the maximum value is 64 KB (but you are recommended to specify a value of at least 48 KB). For version 8.2 the minimum value is 64 KB and the maximum value is 512 KB. For other versions, see section ASIZE - Entire System Server Auxiliary Buffer in the Parameter Reference chapter of the current Natural for Mainframes documentation.

148 is the database ID with which the Entire System Server DDMs are cataloged. This does not affect the use of additional Entire System Server nodes with different node IDs, since these can be addressed via the NODE field in each Entire System Server view. See also Multiple Entire System Server Node Support in the section Using the Entire System Server of the Entire System Server Administration documentation.

Note:
If you are upgrading from a previous version of Entire System Server, use the startup parameter NODE to assign different node IDs to different versions of Entire System Server running on the same system. You may, for instance, have an earlier Entire System Server version running in production using node ID 148, and specify NODE=199 in the startup parameter for the current version during installation and test.

Ensure the Natural profile/session parameter LE is set to OFF, otherwise you may experience problems with the Online Tutorial.

Step 4: Change Defaults

  1. If you want to change default values, edit modules NATPNIP and ESYNODTB.

    Assemble both and link them as described in the section Installing the Entire System Server Interface in the Natural Installation documentation for mainframes.

    • NATPNIP contains the following parameters and defaults:

      BUFLEN=8192 Length of all Adabas buffers.
      NUMREQ=5 Number of parallel requests.
      MAXCBL=3000 Complex FIND buffer length.
      MAXEDL=3000 Editor session buffer length.
      EXTUSER=INIT-USER When running under CICS or IMS, which user ID should be fetched to be shipped to RACF/ACF2/TSS (*INIT-USER or *USER in Natural).
    • ESYNODTB contains the following parameters and defaults:

      This module contains mnemonic names for Entire System Server nodes. In the DDMs, there are fields called NODE and NODE-NAME. The field NODE directs a call directly to this Entire System Server. The field NODE-NAME is translated into a node number depending on the contents of this table. We recommend, that you use your system ID as name.

      The macro NAMXNOD generates table entries. The last macro call must be used with parameter LAST=Y to set end-of-table identifier.

      Example:

      NAMXNOD ID=148,NAME=PRODUCTION-1
      NAMXNOD ID=149,NAME=PRODUCTION-2,LAST=Y
  2. The module ESYNODTB must also be linked to module XCOMV026 into the Entire System Server target library. (SMA Job I055, Step 1108).

  3. If default values are changed, relink Natural as described in the section Installing the Entire System Server Interface in the Natural Installation documentation for mainframes.

Step 5: Load the Predict DATA File

(Job I200, Step 1100)

This step is optional.

All Entire System Server views have been documented in Software AG's repository Predict. The NPRvrs.DATA dataset on the installation tape contains these Predict view descriptions that can be loaded with the MIGRATE/COORDINATOR utility in Predict (Job I200, Step 1100).

The MIGRATE/COORDINATOR utility is described in the Predict Reference documentation.

If, however, you have already loaded these descriptions from any previous of the Entire System Server (or Natural Process), you must also logon to Predict's online system to check the database name of DBID 148, to which the views are linked. Its name must be ENTIRE-SYSTEM-SERVER. If it is not, change the database name before running Job I200, Step 1100 to load the dataset NPRvrs.DATA.

Step 6: Natural Security Considerations

If Natural Security is installed, define libraries SYSNPE, SYSNPR, SYSNPEH1 and SYSNPEH2 to Natural Security. If these applications are to be people-protected, link to them those user IDs that require authorization. Define libraries without XREF = YES to load all objects.

  • SYSNPE contains the online tutorial;

  • SYSNPEH1 and SYSNPEH2 contain online help information;

  • the installation aid in library SYSNPR can be used to apply initial security definitions for the Entire System Server views.

Step 7: Define APF Authorization

Define APF authorization for the Entire System Server load library by updating the member IEAAPFxx in library SYS1.PARMLIB. You may also use the APF statement in a PROGxx parmlib member to define the Load Library in the APF-authorized list.

Ensure that all libraries in the STEPLIB concatenation of the Entire System Server started task in Step 12 are APF-authorized.

Note:
If the library is not authorized, certain Entire System Server functions return an appropriate response code, and at startup time the following message appears on the console:

ESY0050W ENTIRE SYSTEM SERVER IS N O T APF AUTHORIZED

Step 8: Edit the Parameter Module XCOMPARM

(Job I070, Step 1100)

Edit the parameter module XCOMPARM to set the correct startup parameters. This member is created with Job I070, Step 1100 and contains some default values.

For a description of the parameters and an example, see the section Startup Parameters of the Entire System Server Administration documentation.

Step 9: Edit the Entire System Server Started Task

(Job I070, Step 1101)

Edit the example member XCOMSTC (Entire System Server's started task). This member is created with Job I070, Step 1101.

The following is an example of Entire System Server subtask JCL. Note that the load libraries must be concatenated and APF-authorized:

 //NATPROCS PROC
 //**********************************************************************
 //*  Entire System Server Start-up Procedure
 //*
 //*  Make the following substitutions
 //*
 //*    &NPRSRCE - Entire System Server source library
 //*    &NPRLOAD - Entire System Server load library
 //*    &ADALOAD - Adabas load library
 //*    &MLCLOAD - Mainframe license check load library
 //*    &NPRLICS - License Key File
 //*
 //*  Define the libraries in the steplib as APF authorized.
 //*  Adapt all necessary parameters (see DD-CARD 'PARMS').
 //*
 //*
 //**********************************************************************
 //         EXEC PGM=NPRINIT,REGION=3M,TIME=1440
 //STEPLIB  DD DSN=&NPRLOAD,DISP=SHR
 //         DD DSN=&ADALOAD,DISP=SHR
 //         DD DSN=&MLCLOAD,DISP=SHR
 //LICENSE  DD DSN=&NPRLICS,DISP=SHR
 //LICREP   DD SYSOUT=X
 //SYSPRINT DD SYSOUT=*
 //SYSUDUMP DD SYSOUT=*
 //*
 //PARMS    DD DSN=&NPRSRCE(XCOMPARM),DISP=SHR
 //*

In the above example, member XCOMPARM in the Source Library referenced by the PARMS DD statement contains the Entire System Server startup parameters. For a description, see the section  Startup Parameters of the Entire System Server Administration documentation.

Also, the license necessary to run the Entire System Server is verified.

This started task starts the Entire System Server.

Step 10: Create the JCL for the Entire System Server Trace Program

Example:

//JOB card
//ESYTRACE EXEC PGM=ESYTRACE,PARM='199 --DISPL --NTROUT --POLL'
//STEPLIB DD DSN=your.load.library,DISP=SHR
//SYSPRINT DD SYSOUT=*
//

Create the JCL to execute the program ESYTRACE. It analyzes the TRACE data of Entire System Server, if the startup parameter TRACE=YES is defined.

In order to start ESYTRACE in Monitor mode, the parameter 199 --POLL is specified. The assignment of DDNAME TRACEIN is not needed here, because all data is read from the memory pool only. The analyzed and edited TRACE data will be written to SYSPRINT due the --DISPL parameter. It may also optionally be written to a file identified by the DDNAME TRACEOUT, however, in the above example this is suppressed by the --NTROUT parameter.

This task must be stopped explicitly with the operator command

F jobname,QUIT

due to the argument --POLL.

For more information, see Creating Trace Data in the Entire System Server in the section Common Entire System Server Features of the Entire System Server Administration documentation.

Step 11: Activating the VTAM Interface

Edit member VTAMNATP and save it in VTAM's online Source Library SYS1.VTAMLST.

The name specified in the ACBNAME parameter should be identical to Entire System Server's VTAMACB startup parameter. (This can be skipped if VTAMACB=NONE is specified.)

Notes:

  1. The VTAM interface is used in the view NET-OPER to enable VTAM commands. By means of the view NET-OPER, you may send any VTAM command to VTAM without using the system console.

  2. Another VTAM interface is used inside Entire System Server, which prints data to any VTAM printer; this feature is available with Entire Output Management.

  3. Ensure that the major name is different from the minor name.

Step 12: Assemble and Link Security Exits (Optional)

To simplify installation, the sample security exits from the distributed source library have already been assembled and linked into the distributed load library. If no modifications to these exits are needed to satisfy special security requirements, this step can be skipped.

(Job I055, Steps 1110-1116)

  • Steps 1110-1116 delete the pre-linked load-modules with the suffix RACF and are necessary if you want to execute steps 1120-1126. Note that you must edit steps 1110-1116 specifying the volume where the Entire System Server load lib is allocated, and the volume type (3380, 3390, ...).

(Job I055, Steps 1120-1126)

  • Steps 1120-1126 assemble and link all exits with suffix RACF for RACF, CA-ACF2, or CA-TOP SECRET.

  • When assembling the LOGVRACF exit, be sure to include your current Adabas source library in the Assembler SYSLIB DD statements.

Security exit modules are loaded at Entire System Server startup and are used by various view processors. The names of the security modules loaded are determined by the specification of the Entire System Server SECURITY parameter which consists of a 4-byte suffix (see the section Startup Parameters of the Entire System Server Administration documentation).

Sample security exits for CA-ACF2, CA-TOP SECRET and RACF installations are contained in the distributed Source Library. You may assemble and link these using Job I055 as described above. These exits are intended as examples and may require modification to meet your site requirements. The following table lists the sample security exits provided together with the relevant view names:

Exit Name Views
DSNVRACF ACCOUNTING, CATALOG-UPDATE, CHECK-SECURITY, COPY-FILE, FILE-ALLOCATE, FILE-MAINTENANCE, IEBCOPY, LIB-DIRECTORY, LIB-UPDATE, LIB-ZAP, LIST-VTOC, READ-FILE, SUBMIT, VTOC-UPDATE, WRITE-FILE
IDCVRACF IDCAMS
JESVRACF CONSOLE-LOG, READ-SPOOL, SPOOL-UPDATE, SPOOL-FILES, SPOOL-UPDATE
LOGVRACF NATPROC-LOGON
OPRVRACF ALLOCATIONS, CONSOLE, LOADED-MODULES, MAIN-STORAGE, SPOOL-UPDATE, TCB
SUBVRACF SUBMIT
VTMVRACF NET-OPER

General Linkage Conventions

The following table shows the register settings on entry:

Register Convention
R1 Exit parameter list (see below for examples)
R13 18-full word save area
R14 Return address
R15 Entry point address

Below are parameter lists of the example user exits provided in source form in the distributed Source Library. They can be changed to suit your site requirements:

Exit Name Description Parameters Upon Return:
DSNVRACF Dataset verification
  1. ACCESS TYPE (A1)
    A=Alter
    W=Write
    R=Read
    F=Allocate

  2. A (TASK ENTRY)

  3. DYNAMIC WORK AREA

If R15=0, access allowed.
Else, R15 ==> error text.
IDCVRACF IDCAMS verification
  1. COMMAND (A80)

  2. DYNAMIC WORK AREA

If R15=0, access allowed.
Else, R15 ==> error text.
JESVRACF Spool interface
  1. requested authority:
    - X'02' READ
    - X'04' UPDATE

  2. address of resource
    name for JESSPOOL
    resource class

  3. address of user id

  4. address of dynamic
    work area

If R15=0, access allowed.
Else, access denied.
LOGVRACF Logon/logoff
procedure
  1. FUNCTION
    (logon/logoff)

  2. USER ID (A8)

  3. PASSWORD

  4. DYNAMIC WORK AREA

If R15=0, logon OK.
Else, R15 ==> error text.
OPRVRACF
  1. Operator
    command
    validation.

  2. Address
    space
    authorization

  1. COMMAND (A80)

  2. JOB NAME (A8)

  3. JOB NR. (N5)

  4. DYNAMIC WORK AREA

If R15=0, logon OK.
Else, R15 ==> error text.
SUBVRACF Submit exit
  1. USER ID (A8)

  2. A (job card buffer)

  3. DYNAMIC WORK AREA

If R15=0, logon OK.
Else, R15 ==> error text.
VTMVRACF VTAM command
validation
  1. COMMAND (A80)

  2. DYNAMIC WORK AREA

If R15=0, logon OK.
Else, R15 ==> error text.

Note:
All user exits must be reentrant. The Entire System Server dynamic work area is accessible by all user exits. A copybook containing the layout of this work area is also contained in the distributed Source Library under the name VIEWWK. The task table is in XCOMTSDS.

See also Setting Up RACF Security for Operator Commands on z/OS in the section z/OS Considerations of the Entire System Server Administration documentation.

Step 13: Com-plete Considerations

  1. If you intend to use the Entire System Server under Com-plete, you may have to adjust the setting of the ADAROLL, ADACALLS and ADASVC5 parameters (see the Com-plete System Programmer's Manual).

  2. In order to use the SEND-MESSAGE function to users of Com-plete, the Entire System Server must be treated as a batch job from Com-plete's point of view. The subsection Batch in the section Software Interfaces in the Com-plete System Programmer's Manual applies here. Note the following:

  • Link the COMPBTCH module to the Entire System Server library and link the module XCOMV019 to COMPBTCH using Job I055, Step 1105.

  • The following DD card must be added to the Entire System Server JCL:

    COMBTCH DD DSN=NODEvrs.SVCsss,DISP=SHR

    where vrs is the Com-plete node number given by the (Com-plete) ACCESS-ID sysparm, and sss is the Adabas SVC number given by the ACCESS-SVC sysparm.

  • The TUBATCH module must be included in the STEPLIB concatenation of the Entire System Server JCL.

    The Entire System Server logs on to Com-plete with the name of its started task and sends the message(s).

    Note:
    One Entire System Server can send to only one Com-plete.

Step 14: E-Mail Client Requirements

SEND-EMAIL view requires Domain Naming Services to resolve the local host name and the E-Mail target host. In order to get the required Domain Naming Service running properly, a SYSTCPD DD card may be required in the Entire System Server started task to specify your installation TCPIP.DATA data set. Contact your network administrator to determine if and how the SYSTCPD DD statement should be coded in order to run DNS properly.

The Entire System Server Started Task and all users requesting SEND-EMAIL view must be defined with a proper user ID for z/OS UNIX. Error message ESY5897 Mailer response: errno 0156 in EZASMI INITAPI reporting errno 156 (EMVSINITIAL) is returned as ERROR-TEXT if the requesting user ID is not properly defined for z/OS UNIX. This error message is also issued if the MAXPROCUSER limit of z/OS Unix has been exceeded. In this case a higher value for MAXPROCUSER needs to be specified in the BPXPRMxx parmlib member.

For more information about E-Mail administration, see the Run E-Mail Client in the section Common Entire System Server Features in the Entire System Server Administration documentation.

Step 15: Requirements for View SYSTEM-COMMAND

TSO/E commands issued by the SYSTEM-COMMAND view are now executed in an APPC/MVS transaction outside the Entire System Server address space. This transaction, its associated resources and their properties must be defined to APPC/MVS and VTAM.

For details of the required APPC/MVS definitions, see APPC/MVS Definitions for the SYSTEM-COMMAND View in the section z/OS Considerations in the Entire System Server Administration documentation.

Step 16: Additional Notes

  1. An installation aid is contained in library SYSNPR. This installation aid can be used to change the DBIDs (node numbers) of Entire System Server views, and to define views to Natural Security.

  2. For sites running Software AG's data center products: for all users running as subtask in Entire System Server address space who logon to Adabas, ETID=' ' (blank) must be set in the Natural Security profile. This also applies to standard users NOPMON, NOMMON, NCLMON, NOMARC, NOMREV, NOMPRT.

  3. If you experience a security message during startup like:

        ICH408I USER(SAG2 ) GROUP(SAGTEST ) NAME(TEST ID )
        MVS.MCSOPER.ESY148CO CL(OPERCMDS)
        WARNING: INSUFFICIENT AUTHORITY - TEMPORARY ACCESS ALLOWED
        FROM MVS.MCSOPER.* (G)
        ACCESS INTENT(READ ) ACCESS ALLOWED(NONE )

    then you have to give READ access to the MCS console for the task started by the Entire System Server in your

    Security system. Contact your RACF/ACF2/TOP-SECRET administrator for assistance.