Installing the Agent for z/OS

This document guides you through the new installation of a z/OS agent.

The following guide describes how to install an agent in an AE system in which authentication is not used. Additional installation steps are required before the agent can be started and used if you intend to use one of the available authentication methods. More detailed information is provided in the document Advanced Security.

Requirements

JES2 or JES3
TCP/IP V3R2M0 or later
APF authorization for the load library
C runtime library version V1R5M0 or later
An MSGCLASS in HOLD status that does not call a subsequent program (external writer)
UPDATE access for JESSPOOL RACF Class (in order to process Job outputs)
A file qualifier for temporary files, logs and traces

SMP/E

This guile describes the normal installation of a z/OS agent. Note that an SMP/E installation needs to be applied by the z/OS software maintenance team.

As of v12 you may use the SMP/E by IBM in order to install and maintain the z/OS agent, the CallAPI, the External Job Monitor and the Event Monitor.
The AE's z/OS agent as of v12 is delivered in the Sysmod format, too.

The CallAPI for z/OS implementation is described in a separate document.

Load Module:

CADSDEL - A utility that can be used to release a Common Dataspace (CADS) allocated by the Event Monitor.
UC4END - End messenger for the SMF messenger technique (it writes the StepList and return codes to the JESMSGLG)
UC4RESTR - Restart messenger for the SMF messenger technique (dummy program such as IEFBR14)
UC4START - Start messenger for the SMF messenger technique (dummy program such as IEFBR14)

Procedure

	1.	Transferring files to the host

Host
Transfer the appropriate files from IMAGE:AGENTS\MVS\ using a file transfer.

open Host
Use an FTP user with the appropriate rights
User name = UC4
Password = <as set>
bin
quote site recfm=fb lrecl=80 blksize=6080
quote site pri=1 sec=1 CY
put UCXJM25-???.bin 'UC4.UCXJX.WORK'
asci
put UCXJM25.ini 'UC4.UCXJM25.INI'
put UCXEM25.ini 'UC4.UCXEM25.INI'
quote site recfm=vb lrecl=500 blksize=27998
put ucx.msl 'UC4.UC.MSL'
quit

	2.	Creating the Load Library

Host
Create the load library using the utility TSO RECEIVE. Bold printed parameters are system-specific specifications.
//UC4LOAD JOB (ACCT#),'UC4USER',
// CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1),NOTIFY=UC4USER
//*************************************************
//STEP01 EXEC PGM=IKJEFT01,DYNAMNBR=30
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
  PROFILE NOPREFIX
  RECEIVE USERID(UC4USER) INDSN('MYDSN.UCXJ.WORK')
  DSNAME('UC4.UCXJM25.LOAD') -
  UNIT(3390) VOLUME(??????)
/*

Alternately, you can create it as follows:

On the z/OS host:
TSO RECEIVE indsn('MYDSN.UCXJ.WORK')
Press Enter and type the following line:
dsname('UC4.UCXJM25.LOAD')

	3.	APF authorization for the Load Library

Host
APF authorization is required for the load library. It must be assigned or can dynamically be added to the system console using the following command:

SETPROG APF,ADD,DSN=UC4.UCXJM25.LOAD, [SMS] [VOLUME=xxx]

	4.	Creating the Started Task for the Agent

Host

The agent runs on the host as a started task. The supplied files include a JCL example. Copy this JCL to a procedure library and specify the name for the INI file and the load library. The STC user also requires the following authorizations:

User, groups and data set profiles
The user under which the agent runs requires the appropriate rights for data sets via the user or group definition. Use the data set profiles to assign the relevant rights.
Alter right for the AE dataset qualifier is required.
Note that the agent requires rights for all data sets that it will use.

OMVS Segment (TCP/IP authorization)
Ensure that the rights for OMVS are specified in the user and default group.

General resource
Usually, there is a general resource for started tasks (STC). General rights can be assigned here in order to enable the agent program to run as a STC. You can also define the user that should be used to run the agent (STDATA).
Required RACF settings for file transfers if the USS file system is used:
FACILITY class BPX.DAEMON profile with UACC(READ)
PROGRAM class * profile, MEMBER(loadlib//NOPADCHK)
Recommended RACF settings for using the INI-file parameter ft_thread_level_security=

The agent user needs:

OMVS segment
Class Facility resource FACILITY BPX.DAEMON with Read access
Class Facility resource FACILITY BPX.SERVER with Read access
Class Facility resource FACILITY BPX.WLMSERVER with Read access
Class UNIXPRIV resource SUPERUSER.FILESYS.CHOWN with Read access
Class SURROGAT resource BPX.SRV.loginUid with Read access for all logins

The login user needs:

OMVS segment
Class APPL resource OMVSAPPL with Read access
Class SURROGAT BPX.SRV.loginUid where agent user has Read access on (mentioned above)

Use the STC user or any other user to start the AE jobs and/or file transfers.

Using the STC user for the complete execution:

The STC user requires access to all z/OS resources that are used in jobs and file transfers. This user must also be specified in the appropriate Login object. Users without a password (batch users) must be specified in the Login object with no password being indicated. The parameter askRACF in the agent's INI file must be set to "0" or "4" in order to deactivate the password verification.

Using different users:

An appropriate OMVS segment must be defined for all users in addition to the required resources in order to establish a TCP/IP connection to the Automation Engine. Specify the relevant Login object in the job attributes. If a batch user (user without a password) is used for the execution, the STC user requires a surrogate authorization for this particular user. In this case, specify the required user in the Login object without defining a password and deactivate the password verification (set the parameter ask RACF in the agent's INI file to "0" or "4" ).

Example for a started task:
//UC4RUN PROC
//UCEX EXEC PGM=UCXJM25,PARM='TRAP(OFF),HEAP(4M,4M,ANY,FREE)/UC4.UCXJM25.INI',
// REGION=4M,TIME=1440
//STEPLIB DD DISP=SHR,DSN=UC4.UCXJM25.LOAD
//SSTORE DD DISP=SHR,DSN=UC4.UCXJM25.SSTORE
//SYSPRINT DD SYSOUT=*
//STDOUT DD SYSOUT=*
//SYSCPRT DD SYSOUT=*
//JOBOUT DD SYSOUT=(A,INTRDR)
//SYSUDUMP DD SYSOUT=*
//*
The started task must be authorized to read JES lists.
The following files must also be in included in the link chain:

CEE.V1R5M0.SCEERUN - (Language Environment dynamic runtime library)
CEE.V1R5M0.SCEELKED - (Language Environment linkage editor library)
TCPIP.V3R1.SEZACMTX - (TCP/IP runtime library)

There is an alternative solution if you do not want to interfere with your system as described above. You can specify the LOAD library in the STEPLIB, but also in the C-environment's DD card EDCMTF. Further information is available in the IBM documentation - STEPLIB DD statement.
Apply the following step if the MVS or Language Environment Resolver do not work correctly:

The DD statements must be included in the sarted task. Otherwise, the agent cannot establish a TCP/IP connection.

Example:
//SYSTCPD DD DSN=TCPIP.SYSTSMS.TCPPARMS(DT20OEDA),DISP=SHR
//PROFILE DD DSN=TCPIP.SYSTSMS.TCPPARMS(DT20VIPA),DISP=SHR

Complete statements are found in the TCP/IP's started task.

The DD statements for TCP/IP must also be included in the Include object Include MVS.JOBMD_DEFINITIONS. Otherwise, the Job Messenger cannot open a TCP/IP connection and the jobs will receive the status ENDED_VANISHED.
Copy the procedure UC4RUN to a procedure library such as SYS1.PROCLIB.
Required authorizations for the STC user in RACF:

OMVS segment
ALTER authorization for own datasets (e.g.: UC4.*)
The started task requires the appropriate authorization in order to read JES lists

Generate the datasets for the StatusStore

Example:

//CREATESS EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
  DEFINE -
  CLUSTER ( -
  NAME(UC4.UCXJM25.SSTORE) -
  INDEXED -
  VOLUMES(volume) -
  CYLINDERS(10 5) -
  ) -
  DATA ( -
  NAME(UC4.UCXJM25.SSTORE.DATA) -
   KEYS(16 0) -
   RECORDSIZE(256 4096) -
  FREESPACE(10 10) -
   ) -
  INDEX ( -
  NAME(UC4.UCXJM25.SSTORE.INDEX) -
)
//* Load a dummy record
//DUMMYREC EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//OUT1 DD DISP=SHR,DSN=UC4.UCXJM25.SSTORE
//SYSIN DD *
REPRO INFILE(IN1) OFILE(OUT1)
/*
//IN1 DD *
DUMMY
/*

Transfer information for every dataset/file is stored as a record in the VSAM dataset. The size of the information record varies depending on the size of the dataset and file size. 260 bytes is an average size. The suggested space values are 10,5 cylinders = (10 + 15 * 5) * 849,960 bytes ~ 75.553 kilobyte, which should be enough for approximately 282k transfer entries.

	5.	Setting up the system environment

Host
Adjust the INI file. The INI file of the z/OS Agent must not use the file attribute NUMBER ON.
Adjust the HEADER.MVS, TRAILER.MVS and RESTART.MVS where necessary. See: Executing Jobs

	6.	Starting the Agent

Server computer
The AE system (see Multi-Server Operation for details) must be running.
Host
Start using start UC4RUN via the system console.
An Agent object is automatically created in the system client 0000 and stored in the folder HOST.
Admin computer or Server computer
Verify that the agent is logged on.
- Start the UserInterface for client 0000. Refer to the System Overview in order to obtain information about agents. Newly logged-on agents have not yet been assigned to a client; they can only be viewed in client 0000. The new agent can now be assigned to clients with the required rights you set in the Authorization Page of the Agent object.

	7.	Quitting the Agent

Host
Quit the agent's started task via the system console using a MODIFY command (such as modify UC4RUN,end). Alternately, you can also use the STOP command stop UC4RUN.

	8.	The Event Monitor as independent Started Task

Adjust the INI file, see: z/OS - Event Monitor
Create the AE started task for the Event Monitor.

Example:

//UC4EMRUN PROC
//EVENTM EXEC PGM=UCXEM25,REGION=0M,
//    PARM='TRAP(OFF),HEAP(4M,4M,ANY,FREE)/UC4.UCXJM25.EM.INI'
//STEPLIB   DD DISP=SHR,DSN=UC4.UCXJM25.LOADLIB
//SYSPRINT DD SYSOUT=*
//UCEVENT   DD DISP=SHR,DSN=UC4.UCEVENT.VSAM
//UCFILTER DD DISP=SHR,DSN=UC4.UCFILTER

Create the datasets (UCFILTER and UCEVENT).

Example:

//CRTEMDS JOB ####,'XXX',NOTIFY=&SYSUID,MSGLEVEL=(1,1)
//* Create Datasets for UC4 EventMonitor
//UCFILTER EXEC PGM=IEFBR14
//UCFILTER DD DISP=(NEW,CATLG,CATLG),DSN=UC4.UCFILTER,
//        RECFM=VB,LRECL=1024,BLKSIZE=8192,SPACE=(CYL,(1,1))
//UCEVENT EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DEFINE -
  CLUSTER ( -
  NAME(UC4.UCEVENT.VSAM) -
  INDEXED -
  VOLUMES(DSK30D) -
  TRACKS(1 1) -
  ) -
  DATA ( -
  NAME(UC4.UCEVENT.VSAM.DATA) -
  KEYS(20 0) -
  RECORDSIZE(1024 1024) -
  FREESPACE(10 5) -
  ) -
  INDEX ( -
  NAME(UC4.UCEVENT.VSAM.INDEX) -
  )
/*

Create dataset initialization

Example:

//INITEMDS JOB ####,'XXX',NOTIFY=&SYSUID,MSGLEVEL=(1,1)
//INITVSAM EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//OUT1      DD DISP=SHR,DSN=UC4.UCEVENT.VSAM
//SYSIN     DD *
  REPRO INFILE(IN1) OFILE(OUT1)
//IN1       DD *
DUMMY
/*

Start the event monitor with start UC4EMRUN.
End the event monitor with modify UC4EMRUN,end.

Note that the RACF authorization READ is required in order to run the event monitor if the MVS Extended Console is protected.

	9.	The External Job Monitor as independent Started Task

Adjust the INI file, see: z/OS - External Job Monitor.
Create the AE started task for the external Job Monitor.

Example:

//UC4EJM PROC
//UCZEJM EXEC PGM=UC4EJM,PARM='TRAP(OFF)/ ZUC800A1.EJM.INI',REGION=0M
//STEPLIB DD DISP=SHR,DSN=UC800A.LOADLIB
//SYSPRINT DD SYSOUT=*
//STDOUT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
Start the external Job Monitor using start UC4EJM.
End the external Job Monitor using modify UC4EJM,end.