Installation for z/VSE

We recommend reading this section from beginning to end before starting the installation process.

This document covers the following topics:


Installation Tape

The installation tape contains the datasets listed in the table below. The sequence of the datasets is shown in the Report of Tape Creation 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.LIBJ

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

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.LIBJ Entire System Server installation jobs.
NPRvrs.LIBR Entire System Server load 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 the data sets .LIBJ, .LIBR and .LICS from tape to disk. All other data sets can be installed directly from the tape.

Step 1: Copy Data Set COPYTAPE.JOB to Disk

  • Modify the following sample job according to your requirements:

    * $$ JOB JNM=LIBRCAT,CLASS=0,                                          +
    * $$ DISP=D,LDEST=(*,UID),SYSID=1                                      
    * $$ LST CLASS=A,DISP=D                                                
    // JOB LIBRCAT                                                         
    * *****************************************                            
    *     STORE COPYTAPE.JOB IN LIBRARY                                    
    * *****************************************
    // ASSGN SYS004,nnn 
    // MTC REW,SYS004                                                        
    // MTC FSF,SYS004,4                                                      
    ASSGN SYSIPT,SYS004                                                      
    // TLBL IJSYSIN,'COPYTAPE.JOB'                                           
    // EXEC LIBR,PARM='MSHP; ACC S=lib.sublib'
    /*
    // MTC REW,SYS004
    ASSGN SYSIPT,FEC                                                         
    /*                                                                       
    /&                                                                     
    * $$ EOJ

    where:

    nnn is the tape address, and
    lib.sublib is the library and sublibrary in which the data set COPYTAPE.JOB is to be stored.

  • Execute the job to copy the data set COPYTAPE.JOB to disk.

    COPYTAPE.JOB contains the JCL required to copy the data sets .LIBJ, .LIBR and .LICS from tape to disk.

Step 2: Modify COPYTAPE.JOB on Your Disk

  • Modify COPYTAPE.JOB according to your requirements and set the disk space parameters as appropriate.

Step 3: Submit COPYTAPE.JOB

  • Execute COPYTAPE.JOB to copy the data sets .LIBJ, .LIBR and .LICS 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 Command Reference 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 the subsection 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 session parameter LE is set to OFF, otherwise you may experience problems with the Online Tutorial.

Step 4: Change Defaults

Note:
If you are using Natural under CMS and wish to access an Entire System Server node under z/VSE, you must install the Entire System Server Interface as described in the section Installing the Entire System Server Interface in the Natural Installation documentation for mainframes.

  1. Modules NATPNIP and ESYNODTB:

    • If you want to change defaults in parameter module NATPNIP, edit source member NATPNIP.A.

      Assemble it 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:

      Parameter Explanation
      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, which user ID should be fetched to be shipped to Entire System Server (*INIT-USER or *USER in Natural).
    • If you want to use field NODE-NAME instead of NODE to address an Entire System Server via logical names, edit the source member ESYNODTB.A.

      Assemble it as described in the section Installing the Entire System Server Interface in the Natural Installation documentation for mainframes.

      Module ESYNODTB 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 of 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=198,NAME=PRODUCTION-1
      NAMXNOD ID=199,NAME=PRODUCTION-2,LAST=Y
  2. The module must also be linked to view processor XCOMV026 (in NPRvrs.LIBR) with job LNKV026 (SMA Job I055, Step 1108).

  3. If you have changed any defaults, 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.

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

If, however, you have already loaded these descriptions from an earlier version of 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 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 those user IDs to them that require authorization. Define libraries without XREF=YES to load all objects.

  • SYSNPE contains the online tutorial;

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

Step 7: Edit Entire System Server JCL Procedure

 * $$ JOB JNM=ESY,CLASS=6,DISP=D
 * $$ LST CLASS=A,DISP=H,RBS=500
 // JOB ESYvrs
 // OPTION LOG,DUMP
 * *****************************
 * Entire System Server v.r.s *
 * *****************************
 // LIBDEF PHASE,SEARCH=(SAGLIB.ADA,SAGLIB.NPR,SAGLIB.MLCvrs)
 // DLBL LICENSE,'/SAGLIB/USERLIB/NPRvrs.LICS'
 // EXEC NPRINIT,SIZE=3072K
 ADAVERS=5
 ADA5SVC=45                      <- INSTALLATION DEPENDENT
 AUTOLOG=YES
 FORCE=NO                        <- CAN ALSO BE 'YES'
 SPOOL=POWR
 LOCAL=NO                        <- CAN ALSO BE 'YES' IF ENTIRE NET-WORK
 NABS=10
 NODE=148                        <- INSTALLATION DEPENDENT
 NONACT=30
 NUMLIBS=300                     <- # LIBRARIES TO BE ACCESSED
 NUMTASK=5                       <- # WORKER TASKS TO BE STARTED
 VTAMACB=ESYACB1                 <- 'NONE' IF NET-OPER VIEW NOT USED
 VSAMLABELS=YES                  <- PROCESS VSAMLABELS (DEFAULT)
 CONSTAB=1000                    <- SIZE OF CONSOLE TABLE (z/VSE)
 /*
 // EXEC  LISTLOG
 /*
 /&
 * $$ EOJ

As Entire System Server uses z/VSE Librarian services, do not use SIZE=parameters in the EXEC statement that calculates size (such as AUTO), as this may lead to errors when accessing library members. Please see the discussion of the LIBR program in the IBM z/VSE System Control Statements manual for more details. 3072K is an arbitrary number; it may need to be higher or may be reduced depending on your system.

If CA-Dynam/D is installed, the LIBDEF SEARCH,PHASE= statement should include a library where the DYNACC API module is located. DYNACC.PHASE is usually found in the library CALIB1.DYN2PROD, however, it may be in a different location on your system.

See the section Startup Parameters in the Entire System Server Administration documentation for a list of all available startup parameters.

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

Step 8: Create the JCS for the Entire System Server Trace Program

Example:

 * $$ JOB JNM=jobname,CLASS=8,DISP=D,LDEST=(,id),PDEST=(,id)
 * $$ LST CLASS=A,DISP=D
 * $$ PUN CLASS=A,DISP=D
 // JOB jobname comment
 // LIBDEF PHASE,SEARCH=(NPRSYS.NPRvrs)
 // OPTION LOG,LOGSRC,DUMP,NOSYSDUMP
 // EXEC ESYTRACE,PARM='199 --DISPL --NTROUT --POLL'
 // EXEC LISTLOG
 /*
 /&
 * $$ EOJ

Create the JCS 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, and the module NPRSTUB2 must be loaded into the SVA; see Step 9 (Optional): Load NPRSTUB2 for ESYTRACE MONITOR-MODE). The assignment of DLBL TRACIN/SYS001 is not needed here, because all data is read from the memory pool only. The analyzed and edited TRACE data will be written to SYSLST due to the --DISPL parameter. It may also optionally be written to a file identified by DLBL TRACOUT/SYS002, however, in the above example this is suppressed by the --NTROUT parameter.

This task must be stopped explicitly with the operator command

MSG xx,DATA=QUIT

due to the argument --POLL.

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

Step 9 (Optional): Load NPRSTUB2 for ESYTRACE MONITOR-MODE

If you wish to use the MONITOR-MODE of the ESYTRACE program, you must first install the NPRSTUB2 module in the SVA. This may be done at IPL time, or before you bring up the Entire System Server session that will be monitored.

Important:
You cannot monitor a running ESY session if the NPRSTUB2 module has not been previously loaded.

The following is a sample job to load the NPRSTUB2 module in the SVA; it must be run in the BG partition:

 * $$ JOB JNM=NPRSTUB2,CLASS=0,DISP=D,LDEST=(,USER)
 * $$ LST DISP=D,CLASS=A
 // JOB NPRSTUB2
 // LIBDEF *,SEARCH=(SAGLIB.NPRvrs)
 SET SDL
 NPRSTUB2,SVA
 /*
 /&
 * $$ EOJ

Alternatively, you may add the NPRSTUB2,SVA statement to the ADASIP job that runs at IPL.

The module is slightly over 2 KB in length and is loaded above the 16 MB line.

Step 10: Activating the VTAM Interface

To enable the Entire System Server view NET-OPER to function correctly, the application name specified in the VTAMACB system parameter must be defined to VTAM and activated:

VTMAPPL VBUILD TYPE=APPL
VESYACB1 APPL  AUTH=(SPO,CNM),EAS=1,ACBNAME=ESYACB1

This definition can also be found in the member VTAMNATP.B of the Entire System Server sublibrary.

Step 11: 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 and ADACALLS parameters, and also specify the NODE in the ADASVC5 parameters (see the Com-plete System Programmer's documentation).

  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 documentation applies here.

    Note the following:

    • The COMPBTCH module must be linked to the module XCOMV019 to create a new phase XCOMV019. See the sample job LNKMV019.OBJ to create a new phase XCOMV019.

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

      // DLBL COMBTCH, 'NODEvrs.SVCsss'

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

      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 12: E-Mail Client Requirements

SEND-EMAIL view requires Domain Naming Services to resolve the local host name and the E-Mail target host. In addition, the EZASMI interface used requires that a DEFINE NAME parameter be specified in the startup parameters for CSI's (and IBM's) TCP/IP stack.

If the TCP/IP job uses an ID which is not equal 00 like:

// EXEC IPNET,SIZE=IPNET,PARM='ID=nn,...

the JCL of the Entire System Server requires the statement:

// OPTION SYSPARM='nn'

where nn is the ID specified in the TCP/IP job.

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

Step 13: Dataspace Requirements

The following information is required only if CA-Dynam/D is active.

To minimize VTOC resource conflict, Entire System Server will now use a dataspace for every VTOC view request. This may require updating to the VSIZE and SYSDEF statements.

For each active VTOC user, a minium of 256 KB per data space is required, which allows for approximately 1820 VTOC entries per disk volume. If this number is exceeded, then another 256 KB is obtained. Use these figures to modify the VSIZE and SYSDEF statements as needed.

Step 14: 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 (see also Step 6: Natural Security Considerations).

  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. During initialization, after message ESYI0020 INITIALIZATION STARTED FOR FILEID TABLE has been issued, message 4228I may be issued against VSAM files defined in labels, with various reason texts. This behavior is normal, and is caused by a VSE Librarian test. These messages may be safely ignored.