Installing the Agent for z/OS

This page guides you through the installation of a z/OS Agent in an Automation Engine 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. For more information, see Agent Authentication.

This page includes the following:

Overview

The Agent is started in a SYSPLEX and each LPAR must run an Event Monitor. The Agent is responsible for the communication to the Automation Engine, carrying out the File Transfer, and connects to all Event Monitors. If there is an LPAR problem, you can start the Agent on another LPAR (for example, automatically with WLM rules) and all Event Monitors directly reconnect to the Agent again.

The Event Monitor monitors Job, CONS and FILE events and forwards them to the Automation Engine via the Agent.

Requirements

The following requirements must be met:

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 section describes a regular z/OS Agent installation. The SMP/E installation must be carried out by the z/OS software maintenance team.

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 z/OS agent is also delivered in the Sysmod format.

For more information about CallAPI files and their implementation, see CallAPI for z/OS

Load Module

CADSDEL: Utility used to release a Common Dataspace (CADS) allocated by the Event Monitor
UC4END: End messenger for the SMF messenger technique (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)

Installing the Agent for z/OS

Transfer the files to the host. On the host, use a file transfer to move the relevant files from IMAGE:AGENTS\MVS\.

Open the host and use a FTP user with the appropriate rights.
- User name=UC4
- Password: <as defined>
UNIX Example
```
bin
quote site recfm=fb lrecl=80 blksize=6080
quote site pri=1 sec=1 CY
put UCXJM25-???.bin 'UC4.UCXJX.WORK'
ascii
quote site lrecl=500 blksize=27500
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
```
Note: The ucx.msl and INI files are delivered with LF EOL format (UNIX/Linux encoding). However, some FTP Clients on Windows require the CRLF EOL format. To make sure you use the correct EOL format for Windows you could, for example, use a file editor to change LF to CRLF or use the appropriate function of your FTP client.

Create the load library using the TSO RECEIVE utility. The parameters in bold are system-specific.

//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 NOPREFIXRECEIVE USERID(UC4USER)INDSN ('UC4.UCXJX.WORK')
  DSNAME ('UC4.UCXJM25.LOAD') -
  RECEIVE USERID (UC4USER) INDSN('MYDSN.UCXJ.WORK')
  DSNAME ('UC4.UCXJM25.LOAD') -
  UNIT(3390) VOLUME (??????)
/*

Optionally, you can also create the load library on the z/OS host as follows:

TSO RECEIVE indsn('UC4.UCXJX.WORK'), press enter and type dsname('UC4.UCXJM25.LOAD').

You must have APF authorization for the load library. It must be assigned or can be added dynamically to the system console. To do so, use the following command on the host:
```
SETPROG APF,ADD,DSN=UC4.UCXJM25.LOAD, [SMS] [VOLUME=xxx]
```
Create the started task for the agent.
1. User, groups and data set profiles
  
  The user under which the agent runs requires the relevant rights for data sets via the user or group definition. You can use the data set profiles to assign the respective rights. The AE data set qualifier requires alter rights.
  
  Note: The agent requires rights for all data sets to be used.
2. OMVS Segment (TCP/IP authorization)
  
  Make sure that the OMVS rights are specified in the user and default group.
3. General resource
  
  Usually, there is a general resource for started tasks (STC). You can assign general rights here to enable the agent program to run as a STC. You can also define the user to be used to run the agent (STDATA).
4. Required and recommended RACF settings
  
  The following RACF settings are required if the USS file system is used:
  - FACILITY class BPX.DAEMON profile with UACC(READ)
  - PROGRAM class * profile, MEMBER(loadlib//NOPADCHK)
  The following RACF settings are recommended to use the ft_thread_level_security= parameter of the INI file of the z/OS agent (see Agent z/OS).
  
  The agent user needs:
  - OMVS segment
  - FACILITY BPX.DAEMON FACILITY class resource with Read access
  - FACILITY BPX.SERVER FACILITY class resource with Read access
  - FACILITY BPX.WLMSERVER FACILITY class resource with Read access
  - SUPERUSER.FILESYS.CHOWN UNXPRIV class resource with Read access
  - BPX.SRV.loginUid SURROGAT class resource with Read access for all logins
  The login user needs:
  - OMVS segment
  - OMVSAPPL APPL class resource with Read access
  - BPX.SRV.loginUid SURROGAT class resource where the agent user has Read access (mentioned above)
  Example of 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=*
//*
```
5. Authorize started tasks to read JES lists.
6. Include the following files 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
  Important! If you do not want to interfere with your system as described, you can specify the LOAD library in the STEPLIB, but also in the DD card EDCMTF of the C-environment. For more information, see the STEPLIB DD statement in the IBM documentation.
7. If the MVS or Language Environment Resolver do not work correctly, make sure that the DD statements are included in the started 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 
```
  You can find complete statements in the TCP/IP of the started task.
  
  Important! The DD statements for TCP/IP must also be included in the Include object. Otherwise, the Job Messenger cannot open a TCP/IP connection and the jobs will receive the status ENDED_VANISHED.
8. Copy the procedure UC4RUN to a procedure library such as SYS1.PROCLIB.
9. The following authorizations are required for the STC user in RACF:
  - OMVS segment
  - ALTER authorization for own data sets (for example, UC4.*)
  - Started tasks require the appropriate authorization to read JES lists
10. Generate the data sets for the Status Store.
  
  Example
```
/CREATES  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(20 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 data set and/or file is stored as a record in the VSAM data set. The size of the information record varies depending on the data set 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.
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.
Set up the system environment in the host:
- Adjust the INI file accordingly. It must not use the file attribute NUMBER ON, see Agent z/OS
- Adjust the HEADER.MVS, TRAILER.MVS and RESTART.MVS as required, see Executing Jobs
Start the agent:
1. Make sure the Automation Engine is running on the server computer, see Multi-Server Operations
2. On the host, use start UC4RUN through the system console. An Agent object is automatically created in the system client 0 and stored in the HOST folder.
3. On the admin or server computer, verify that the Agent is logged on to the Automation Engine.
  
  Newly logged on Agents are not assigned to a client automatically and can only be viewed in Client 0. Once you have logged in to Client 0, access the Administration perspective and select Agents & Groups.
  
  Assign the new Agent to clients with the required rights using the Agent object definition. For more information, see Authorizations Page
On the host, quit the agent's started task through the system console using a MODIFY command, such as modify UC4RUN,end. You can also use the STOP command stop UC4RUN. To stop the agent and all connected Event Monitors you can use the MODIFY command UC4RUN,shutdown.

Create the started task for the Event Monitor.

Adjust the INI file of the Event Monitor, see z/OS Event Monitor
Create a separate INI data set for each LPAR UC4.UCXEM25.INI -> UC4.UCXEM25.INI.SYSID.

Create the Automation Engine started task for the Event Monitor.

Example

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

Create the UCEVENT data set for each LPAR.

Example

//CRTEMDS  JOB ####,'XXX',NOTIFY=&SYSUID,MSGLEVEL=(1,1)
//* Create Data sets for UC4 EventMonitor
//*. -----------------------------------
//UCEVENT  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
 DEFINE -
   CLUSTER ( -
      NAME(UC4.UCEVENT.VSAM.SYSNAME) - 
	  INDEXED -
	  VOLUMES(volume) -
	  TRACKS(1 1) -
	  ) -
   DATA ( -
      NAME(UC4.UCEVENT.VSAM.DATA.SYSNAME) -
	  KEYS(20 0) -
	  RECORDSIZE(1024 1024) -
	  FREESPACE(10 5) -
	  ) -
   INDEX ( -
      NAME(UC4.UCEVENT.VSAM.INDEX.SYSNAME) -
	  )
/*
//* ----------------------------------- 
//INITVSAM  EXEC PGM=IDCAMS
//SYSPRINT  DD SYSOUT=*
//OUT1      DD DISP=SHR,DSN=UC4.UCEVENT.VSAM.SYSNAME
//SYSIN     DD *
    REPRO INFILE(IN1) OFILE(OUT1)
//IN1       DD *
DUMMY
/*

Use the command start UC4EMRUN to start the Event Monitor.
Use the MODIFY command UC4EMRUN,end to end the Event Monitor. In this case, the STC is stopped while the SMF Exit remains active. Upon starting the Event Monitor again, all missed SMF records are processed. You can also use the MODIFY commands UC4EMRUN,shutdown or UC4EMRUN,end. In this case, both STC and SMF are stopped.

Notes
- If the MVS Extended Console is protected, the RACF authorization READ is required to run the Event Monitor.
- In case the agent is upgraded from a previous version, we recommend reinitializing the UCEVENT and the filter datasets.