Installing the Agent for z/OS
This document guides you through the new 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.
- 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 outputs)
- A file qualifier for temporary files, logs and traces
As of v12 you have to use the SMP/E by IBM in order to install and maintain the z/OS agent, the , the External Job Monitor and the Event Monitor.
The AE's z/OS agent as of v12 is delivered in the Sysmod format.
The CallAPI for z/OS implementation is described in a separate document.
- 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)
|
1.
|
Transferring files to the 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
|
- 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)
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 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 . 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 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: Jobs ausführen
|
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 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 Seite „Berechtigung“ 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.
See also:
Agent - Interaction Between the Automation Engine and z/OS
SMF Exit
Event Monitor
Automatic File-System Events
External Job Monitor