Defining resources and starting the CICS Transaction Server Agent

To complete the CICS® Transaction Server Agent installation, you must define a number of resources in the CICS region.

Configure CICS Distributed Program Link (DPL) Agent to use HTTPS. For details, see Configuring CICS® Distributed Program Link (DPL) Agent to use HTTPS.
Note:
For additional information, see the README member included in the RIT.CICS.PROC dataset.
The CICS Transaction Server Agent has two parts.
  • Several CICS programs and resources that must be defined in the CICS region to be intercepted.
  • The RITAGENT batch service. The batch service must be run on the same z/OS® system as the intercepted CICS region or in a z/OS system within the SYSPLEX that runs the intercepted CICS region.
Notes:
  • Only one RITAGENT can be run for one CICS region. Do not attempt to run multiple RITAGENT jobs for one CICS region. That is, do not run the second RITAGENT against the same CICS region even in a different z/OS system in a SYSPLEX environment.
  • If CICS is restarted, you must restart the CICS Agent so that it reconnects to the new instance of CICS.

One RITAGENT can work for only one CICS region. You can run multiple RITAGENT jobs if you need to intercept multiple CICS regions. Within one system each RITAGENT job name must be unique.

The IBM DevOps Test Integrations and APIs (Test Integrations and APIs) CICS Agent needs Language Environment® support, TCP/IP, EXCI, and the intrapartition data set to be configured.

For information about installing Language Environment support, see Installing Language Environment Support.

For information about setting up and configuring CICS TCP/IP, see Setting up and configuring CICS TCP/IP.

For information about using the EXCI options table, see Using the EXCI options table, DFHXCOPT.

For information about defining the intrapartition data set, see Defining the intrapartition data set.

The RIT.CICS.PROC dataset contains sample JCL to configure TCP/IP, EXCI, and the intrapartition data set in the CICS region. It is also contains JCL to start the Test Integrations and APIs CICS Agent. In the following steps, member names such as DINTRA#T and EZAPLT#T refer to members of the RIT.CICS.PROC dataset.

Complete the following steps in consultation with your CICS administrator:

  1. Create the intrapartion data set by using the DINTRA#T member and update the DFHINTRA DD name in the CICS region start procedure.

    If you already have a DFHINTRA dataset, and do not want to recreate it, you must ensure that your current dataset was created with RECORDSIZE parameters matching the parameters in job DINTRA#T.

  2. Create the CICS EXCI option load module named DFHXCOPT by using the EXCIOP#T member.
  3. If the TCP/IP interface in the CICS region is not already set up, set it up as follows:
    1. Edit the EZACAC#T member and submit it to create the user cache.
    2. Edit the EZACFG#T member and submit it to create the TCP/IP configuration.
    3. Edit the EZACIC#T member according to the comments in that member.
    4. Edit the EZADEF#T member and submit it to create the resources for sockets.
    5. Edit the EZAPLT#T member and submit it to create the PLTPI program.
  4. Define the Test Integrations and APIs Agent resources:
    1. Edit the RITUSD#T member.
    2. Edit the RITDEF#T member and submit it.
  5. Edit the CICS region start procedure and system initialization parameters and restart the CICS region:
    1. Add the TCPIP.SEZATCP and @CICHLQ@.@REGNAM@.PLTLOAD data sets to the DFHRPL DD statement.
    2. Add the following DD statements to the CICS startup procedure: 
      //TCPDATA  DD SYSOUT=*,DCB=(DSORG=PS,RECFM=V,BLKSIZE=136)
//SYSTCPT  DD SYSOUT=*,DCB=(DSORG=PS,RECFM=V,BLKSIZE=136)
//* The system TCP/IP configuration 
//SYSTCPD  DD DSN=@SYS1@.TCPPARMS(TCPDATA),DISP=SHR
//RITLOG   DD SYSOUT=*
    3. Update the DFHINTRA DD statement, which you defined in step 1.
    4. Add PLTPI=XX and PLTSD=YY to the system initialization parameter, where XX is the suffix (@SUFFIX@) that you set in EZAPLT#T and YY is the suffix (@SUFFI2@) that you set in EZAPLT#T.
    5. Ensure that the system initialization settings contain the strings ISC=YES, TCPIP=YES, and IRCSTRT=YES.
    6. If you are using multiple CICS versions and multiple CICSSVC numbers, ensure that the CICSSVC number is the number of the most recent CICS version that is installed in the z/OS system. Review the CICSSVC number in the CICS system initialization settings and the CICSSVC number in the DFHXCOPT, which is defined in SYSUT1 DD of EXCIOP#T.
    7. Restart the CICS region with the START=COLD option to format the new intrapartition data set, which you created in step 1.
  6. Create a unique RITAGENT JOB, based on @RITHLQ@.CICS.PROC(RITAGENT). Modify the contents, based on instructions within the JCL.
    Note:
    The RITAGENT job stops automatically when it can no longer communicate with either CICS Transaction Server or Test Virtualization Control Panel. Once it detects a problem with either connection, it periodically tries to reestablish the connection. If the attempts to reconnect are not successful, the agent shuts down. You can set environment variables within the RITAGENT job to control how many times the agent attempts to reconnect to CICS or Test Virtualization Control Panel. For more information on setting these environment variables, see the comments within the RITAGENT job.

    Prior to version 10.0.0, the agent could only successfully reconnect to the same instance of CICS. Starting in version 10.0.0, the agent can reconnect to CICS, even if CICS was restarted. If you want the agent to remain up during CICS restarts, you might need to increase the value of the EXCI_MAX_ERRNUM environment variable to ensure that the agent does not shut down automatically before the new instance of CICS was started.

After all the resources are configured, you can start the agent by submitting the following JCL. (In these examples, RITAGT1 is the name of the unique RITAGENT job created in the previous step): @RITHLQ@.CICS.PROC(RITAGT1)

To stop the agent, run the following SDSF command /F RITAGT1,STOP
Note:
Do not use /C RITAGT1 to cancel it.

You can also refresh the contents of the RITLOGxx datasets (either RITLOG01 or RITLOG02, whichever is currently in use) with the following SDSF command /F RITAGT1,REFR