Installing the Agent for Windows

Installing the Agents

Installing the ServiceManager

---

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

Supplied Files

The necessary files are available in the directory IMAGE:AGENTS\MVS.

The CallAPI files and their implementation are 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)

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 passwordA secret combination of characters for a Automation Engine user. (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 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 must not use the file attribute NUMBER ON.
• Adjust the HEADER.MVS, TRAILER.MVS and RESTART.MVS where necessary. See: Job - Execution

	6.	Starting the Agent

• Server computer
• The AE system 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 via 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
• 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.
• 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