Installation for z/OS

#### Search Results

Search

# 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

- Installation Procedure

## 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: The acronym vrs in the library name represents the version of the license check software, not the version of the Entire System Server. 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: The acronym vrs in the library name represents the version of the license check software, not the version of the Entire System Server. 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
- Step 2: Modify hilev.COPY.JOB on Your Disk
- Step 3: Submit COPY.JOB

#### 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 | `ACCESS TYPE` (A1) `A`=Alter `W`=Write `R`=Read `F`=Allocate `A` (`TASK ENTRY`) `DYNAMIC WORK AREA` | If `R15=0`, access allowed. Else, `R15` ==> error text.
`IDCVRACF` | `IDCAMS` verification | `COMMAND` (A80) `DYNAMIC WORK AREA` | If `R15=0`, access allowed. Else, `R15` ==> error text.
`JESVRACF` | Spool interface | requested authority: `- X'02' READ` `- X'04' UPDATE` address of resource name for JESSPOOL resource class address of user id address of dynamic work area | If `R15=0`, access allowed. Else, access denied.
`LOGVRACF` | Logon/logoff procedure | `FUNCTION` (logon/logoff) `USER ID` (A8) `PASSWORD` `DYNAMIC WORK AREA` | If `R15=0`, logon OK. Else, `R15` ==> error text.
`OPRVRACF` | Operator command validation. Address space authorization | `COMMAND` (A80) `JOB NAME` (A8) `JOB NR.` (N5) `DYNAMIC WORK AREA` | If `R15=0`, logon OK. Else, `R15` ==> error text.
`SUBVRACF` | Submit exit | `USER ID` (A8) `A` (job card buffer) `DYNAMIC WORK AREA` | If `R15=0`, logon OK. Else, `R15` ==> error text.
`VTMVRACF` | VTAM command validation | `COMMAND` (A80) `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.

4. Check the `RMODE` of `ADALNK` in Adabas load lib which is used in Started Task JCL (see step 9). The `RMODE` must be `RMODE(24)`.

### On this page

- Installation Medium
- Installation Procedure