Installing the Agent for z/OS

This topic describes how to install an Agent in an AE system where 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 Agent Authentication.

One Agent will be started in a SYSPLEX and each LPAR must run an Event Monitor. The Agent is responsible for the communication to the Automation Engine and is doing the File Transfer and has a connection to all Event Monitors. In case of a problem of a LPAR, the Agent can be started on another LPAR (e.g. automatically with WLM rules) and all Event Monitors will 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.

This page includes the following:

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

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

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)

Installing the Agent for z/OS

Transfer files to the host. On the host, transfer the appropriate files from IMAGE:AGENTS\MVS\ by 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
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
On the 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 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(??????)
/*

Alternately, you can create it as follows:

On the z/OS host:
TSO RECEIVE indsn('UC4.UCXJX.WORK')
Press Enter and type the following line:
dsname('UC4.UCXJM25.LOAD')
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 on the host:
SETPROG APF,ADD,DSN=UC4.UCXJM25.LOAD, [SMS] [VOLUME=xxx]
Create the started task for the agent.
- 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: The agent requires rights for all data sets that it will use.
- OMVS Segment (TCP/IP authorization)
  Warning! 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 parameter ft_thread_level_security= of the INI file of the z/OS agent. For more information, see Agent z/OS.
- 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)
  
  Warning! 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.
  
  Warning! 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. For more information, see Include MVS.JOBMD_DEFINITIONS.
- Copy the procedure UC4RUN to a procedure library such as SYS1.PROCLIB.
- Required authorizations for the STC user in RACF:
- 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(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 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.
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.
- Host
- Adjust the INI file, which must not use the file attribute NUMBER ON. For more information, see Agent z/OS.
- Adjust the HEADER.MVS, TRAILER.MVS and RESTART.MVS where necessary. See: Executing Jobs.
Start the agent.
- On the server computer, the AE system must be running. For more information, see Multi-Server Operation .
- On the 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.
- On the admin computer or server computer, verify that the agent is logged on. Start the AWI for client 0000. Refer to the Administration perspective 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 Authorizations Page of the Agent object. For more information, see Agent z/OS.
On the 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. To stop the agent and all connected event monitor, command modify UC4RUN,shutdown can be used.
The Event Monitor as independent started task.
1. Adjust the INI file, see: z/OS Event Monitor
2. Create a separate INI dataset for each LPAR UC4.UCXEM25.INI -> UC4.UCXEM25.INI.SYSID
  - Create the Automation Engine started task for the Event Monitor. For example:
  - Create the UCEVENTdataset for each LPAR. For example:
  - Start the event monitor with start UC4EMRUN.
  - End the event monitor with modify UC4EMRUN,end (the STC will be stopped but the SMF exit remain active). After the next start of the event monitor all missed SMF records will be processed) or modify UC4EMRUN,shutdown/modify UC4EMRUN,end (the STC and the SMF exit will be stopped).