Configuring enhanced monitoring for CICS tasks

To allow CICS® applications to pass enhanced monitoring information to IBM® z/OS® Connect , enable the CICS Task-Related User Exit (TRUE) in the CICS region. Enhanced monitoring information is then available to any interceptors that run in the IBM z/OS Connect server and use the API requester interceptor interface.

About this task

The IBM z/OS Connect provided CICS TRUE allows the UOWID and NETUOWID of the CICS task to be sent to the IBM z/OS Connect server as enhanced monitoring information. Before your CICS applications can pass enhanced monitoring information, you must configure the TRUE in your CICS region.

To set up the IBM z/OS Connect provided TRUE in CICS, you must have the following resources in your CICS region:

A PROGRAM resource with the name BAQCTENA
This program is used to enable the TRUE in the CICS region.
A PROGRAM resource with the name BAQCTDIS
This program is used to disable the TRUE in the CICS region.
A PROGRAM resource with the name BAQCTRUA
This program is called by the TRUE to gather the enhanced monitoring information.
A PROGRAM resource with the name BAQCTRUE
This program is the implementation of the TRUE.
A TRANSACTION resource with the name BAQE
This transaction runs the program BAQCTENA.
A TRANSACTION resource with the name BAQD
This transaction runs the program BAQCTDIS.

Sample CICS CSD resources are supplied with IBM z/OS Connect in the hlq.SBAQSAMP member BAQTRUE. These sample definitions use a CSD group with the name BAQAPIR. For best results, use the resources as supplied.

Procedure

  1. Import the TRUE resources in the BAQAPIR CSD group into your CICS system by using the DFHCSDUP utility program.
    The supplied TRUE resources are located in the BAQTRUE member in the hlq.SBAQSAMP data set.
    1. Edit the job control statements that you can use to invoke DFHCSDUP. Include a DD statement that references the BAQTRUE member in the hlq.SBAQSAMP data set.
    2. Run the DFHCSDUP utility program.
  2. Install the TRUE resource definitions into your CICS system by installing the group BAQAPIR.
  3. Ensure that SBAQLIB1 data set is available to CICS either in the DFHRPL concatenation or as a dynamic library. This step was completed as part of configuring CICS to access IBM z/OS Connect to call APIs.
  4. Enable the TRUE by running the BAQE transaction. This provides enhanced monitoring for any CICS applications that are calling IBM z/OS Connect by using the BAQCSTUB in this CICS region.
    1. If the TRUE can be enabled, then the BAQT0034I message is returned. If it cannot be enabled, then a warning or error message is returned and also written to the BAQQ TDQ.
  5. CICS can be configured to enable the TRUE automatically at startup by using the sample program list table BAQPLTBQ located in the hlq.SBAQSAMP data set. Choose one of the following PLTPI configuration options:
    • If you do not have a program list table defined:
      1. Add the PLTPI=BQ parameter to the CICS system initialization parameters.
      2. Copy the BAQPLTBQ sample to a new data set and rename it to DFHPLTBQ.
      3. Complete the necessary steps for your CICS version to make DFHPLTBQ available to CICS at startup.
    • If you already have a program list table defined and specified in your CICS system initialization parameters, add the BAQCTENA program to the list by including the following statement after the DFHDELIM entry: 
      DFHPLT TYPE=ENTRY,PROGRAM=BAQCTENA
      This ensures that BAQCTENA is run in the second pass of PLTPI.
  6. The TRUE can be disabled by running the BAQD transaction, which returns the BAQT0039I message if it completes successfully. If the TRUE can't be disabled, then a warning or error message is returned and also written to the BAQQ TDQ.