Free trial

Deploy OneAgent on CICS

The CICS code module of OneAgent can either start new PurePaths for specific transaction codes or link CICS transaction PurePaths to distributed PurePaths for transactions initiated using WebSphere MQ(Bridge or Trigger), CICS Transaction Gateway, HTTP(S) SOAP (over HTTP) or 3270 TX Transactions. It supports DB2, DL/I and MQ API calls tracing, as well as any programs invoked using CICS LINK or LE dynamic call. Linked PurePaths are also provided with child transaction details started for DPL LINK or START TRANSACTION requests within a PurePath.

You need to install OneAgent into every CICS region that you want to monitor. It includes a PLT program that initiates at CICS startup, and the code module program that captures various events and forwards them to the z/OS Data Collection subsystem.

Adding the OneAgent to the CICS DFHRPL

Add the following PDS (or its contents) to the DFHRPL concatenation, substituting <hlq> with the high-level qualifier you set while SMP/E install of the OneAgent for z/OS.

// DD DISP=SHR,DSN=<hlq>.SZDTLOAD

Installing the DESK CICS programs and transaction

The sample CICS definitions below install programs and a transaction that are required by the CICS code module of OneAgent. A copy of these definitions can be found in SZDTSAMP member CICRDO, which is provided for use with the batch RDO utility DFHCSDUP.

We recommend to use these transaction and group names, but you can change them in accordance with your installation policies. Coordinate the group name and group list name with your CICS administrator. Replace XYZLIST with the name of your group list (GRPLIST).

CEDA DEFINE TRANSACTION(DTAX) DESCRIPTION(DESK CODE MODULE UTILITY TRAN)
     GROUP(DTA1) PROGRAM(ZDTPLT) TASKDATAKEY(CICS) TASKDATALOC(ANY)

CEDA DEFINE PROGRAM(ZDTPLT) DESCRIPTION(DESK CODE MODULE UTILITY PROG)
     GROUP(DTA1) DATALOCATION(ANY) EXECKEY(CICS)

CEDA DEFINE PROGRAM(ZDTPLTSD) DESCRIPTION(DESK CODE MODULE SHUTDOWN PROG)
     GROUP(DTA1) DATALOCATION(ANY) EXECKEY(CICS)

CEDA DEFINE PROGRAM(ZDTAGT66) DESCRIPTION(DESK CTS 4.1 AGENT)
     GROUP(DTA1) CEDF(NO) CONCURRENCY(THREADSAFE) DATALOCATION(ANY)
     LANGUAGE(ASSEMBLER)
 
CEDA DEFINE PROGRAM(ZDTAGT67) DESCRIPTION(DESK CTS 4.2 AGENT)
     GROUP(DTA1) CEDF(NO) CONCURRENCY(THREADSAFE) DATALOCATION(ANY)
     LANGUAGE(ASSEMBLER)
 
CEDA DEFINE PROGRAM(ZDTAGT68) DESCRIPTION(DESK CTS 5.1 AGENT)
     GROUP(DTA1) CEDF(NO) CONCURRENCY(THREADSAFE) DATALOCATION(ANY)
     LANGUAGE(ASSEMBLER)
 
CEDA DEFINE PROGRAM(ZDTAGT69) DESCRIPTION(DESK CTS 5.2 AGENT)
     GROUP(DTA1) CEDF(NO) CONCURRENCY(THREADSAFE) DATALOCATION(ANY)
     LANGUAGE(ASSEMBLER)
 
CEDA DEFINE PROGRAM(ZDTAGT70) DESCRIPTION(DESK CTS 5.3 AGENT)
     GROUP(DTA1) CEDF(NO) CONCURRENCY(THREADSAFE) DATALOCATION(ANY)
     LANGUAGE(ASSEMBLER)

CEDA DEFINE PROGRAM(ZDTAGT71) DESCRIPTION(DESK CTS 5.4 ETP AGENT)
     GROUP(DTA1) CEDF(NO) CONCURRENCY(THREADSAFE) DATALOCATION(ANY)
     LANGUAGE(ASSEMBLER)

CEDA DEFINE PROGRAM(ZDTAGT72) DESCRIPTION(DESK CTS 5.5 ETP AGENT)
     GROUP(DTA1) CEDF(NO) CONCURRENCY(THREADSAFE) DATALOCATION(ANY)
     LANGUAGE(ASSEMBLER)     

CEDA DEFINE PROGRAM(ZDTSOAPH) DESCRIPTION(DESK SOAP HEADER PROG)
     GROUP(DTA1) EXECKEY(USER) CONCURRENCY(THREADSAFE)
     DATALOCATION(ANY) LANGUAGE(ASSEMBLER)

CEDA DEFINE PROGRAM(ZDTDC2) DESCRIPTION(COBOL2 PRIMER PROGRAM)
     GROUP(DTA1) EXECKEY(CICS) CONCURRENCY(THREADSAFE)
     DATALOCATION(ANY) LANGUAGE(COBOL)

CEDA DEFINE PROGRAM(ZDTDC2A) DESCRIPTION(COBOL2 PRIMER PROGRAM)
     GROUP(DTA1) EXECKEY(CICS) CONCURRENCY(THREADSAFE)
     DATALOCATION(ANY) LANGUAGE(COBOL)

 CEDA INSTALL GROUP(DTA1)

CEDA ADD GROUP(DTA1) LIST(XYZLIST)

Adding OneAgent to the CICS startup program list table

Add the OneAgent startup program (ZDTPLT) after the DFHDELIM entry in your PLTPI source code and assemble the table.

This step is optional for test installations because the DTAX transaction may be used instead to enable the OneAgent after CICS initialization. We recommend to place the ZDTPLT entry immediately before the TYPE=FINAL specification.

The JCL procedure DFHAUPLE in CICSHLQ.SDFHINST(DFHAUPLE) can be used to build the PLTPI table.

Below is an example of the PLTPI table that contains the OneAgent startup program.

*
* PLT USED TO SUPPORT DESK CODE MODULE INITIALIZATION
*
         DFHPLT TYPE=INITIAL,SUFFIX=SI
         DFHPLT TYPE=ENTRY,PROGRAM=DFHDELIM
* Other PLT startup programs here...
         DFHPLT TYPE=ENTRY,PROGRAM=ZDTPLT
         DFHPLT TYPE=FINAL
         END
Important note for Compuware Xpediter Global storage protection users

The PLT startup program (ZDTPLT) initializes the CICS Code Module's exit work area, which CICS obtains on its behalf. Products such as Compuware Xpediter/CICS may be configured to enforce strict storage access controls and may abend ZDTPLT and prevent the DESK CICS Code Module from starting unless it is excluded from these controls. If you use the Xpediter/CICS global storage protection feature, add a monitor exceptions entry to the XDDBPINP DD in the CICS region JCL to exclude ZDTPLT*. For example:

DBPA 9.4.1 TRAN=*,PROGRAM=ZDTPLT*,CSECT=*

Adding OneAgent to the shutdown program list table

Add the OneAgent shutdown program (ZDTPLTSD) before the DFHDELIM entry in your PLTSD source code and assemble the table.

We recommend to place the ZDTPLTSD entry immediately after the TYPE=INITIAL specification.

The JCL procedure DFHAUPLE in CICSHLQ.SDFHINST(DFHAUPLE) can be used to build the PLTSD table.

Below is an example of the PLTSD table that contains the OneAgent shutdown program.

*
* PLT USED TO SUPPORT DESK CODE MODULE SHUTDOWN
*
         DFHPLT TYPE=INITIAL,SUFFIX=SD
         DFHPLT TYPE=ENTRY,PROGRAM=ZDTPLTSD
* Other PLT shutdown programs here...
         DFHPLT TYPE=ENTRY,PROGRAM=DFHDELIM
         DFHPLT TYPE=FINAL
         END

Adding SIT override INITPARM for non-default zDC subsystems or FINE logging

The PLT startup program (ZDTPLT) automatically connects to the default zDC at CICS region initialization.

If multiple zDCs are running, it connects to the zDC that specifies DEFAULT(YES), unless an INITPARM parameter in the CICS system initialization parameters specifies that it must connect to a zDC with a particular name:

INITPARM=(ZDTPLT='MEPC[,<Option>]'),

<Option> sets the logging level. See DTAX documentation for details.

For linking CICS Code Modules to non-default zDCs, see Running multiple zDC systems on a single z/OS image.

SOAP support

To trace SOAP service provider programs that are invoked by DFHPITP from CICS SOAP pipelines, update the service provider pipeline definitions for the services that should be traced. Add a <headerprogram> stanza that invokes the supplied ZDTSOAPH header program.

For example, add the definitions below to the cics_soap_1.1_handler section after any existing header program sections:

<headerprogram>
    <program_name>ZDTSOAPH</program_name>
    <namespace>\*</namespace>
    <localname>\*</localname>
    <mandatory>true</mandatory>
</headerprogram>

To trace outbound SOAP requests that originate within CICS transactions that are being traced by any CICS Code Module sensor, add the previous <headerprogram> stanza to the service requester pipeline definitions for those SOAP services that should be traced. Outbound SOAP requests that occur within CICS transactions that are not being traced are ignored, but tracing is not limited to requests from SOAP programs acting as CICS SOAP service providers.

Configure OneAgent

  1. Select Settings from the DESK UI navigation menu.
  2. Go to Server-side service monitoring > Deep monitoring.
  3. Expand the New OneAgent features drop-down. Here you can configure the following settings by toggling on and off:
    • Java CICS Transaction Gateway client: Enables/disables CTG calls from Java. If disabled, no CTG calls from Java will be reported in the traces produced by ony of the enabled sensors.
    • z/OS CICS DB2: Enables/disables DB2 API details. If disabled, no DB2 API call information reports in the traces produced by any of the enabled sensors.
    • z/OS CICS DB2 Fetch: Enables/disables DB2 fetch, causes data to be sent to DESK. In CICS systems that have transactions which issue an excessive number of FETCH calls, performance can be greatly improved by disabling the capture of DB2 fetches.
    • z/OS CICS DLI: Enables/disables CICS DLI API details. If disabled, no DL/I API call information is reported in the traces produced by any of the enabled sensors.
    • z/OS CICS HTTP: Enables/disables CICS HTTP(S) details. If disabled, no HTTP call information is reported in the traces produced by any of the enabled sensors.
  • CICS Transaction ID filter: A list of transaction code patterns to be traced. Each entry in the list may be a transaction code or a transaction code prefix with an asterisk at the end. The TX sensor ignores transactions whose names do not match an entry in the list. An entry with a single asterisk (*) is ignored because monitoring CICS internal transactions is not recommended.
  • Enable Node Limit: Sets a limit on the number of nodes in a single transaction within CICS. The default limit is 500.