CICS Agent installation and configuration

The CICS Agent installs into every CICS region that you want to monitor. It includes a PLT program that initiates at CICS startup, and an Agent program that captures various events and forwards them to the zDC.

The CICS Agent can either start new PurePaths for specific transaction codes or link CICS transaction PurePaths to distributed PurePaths for transactions initiated using WebSphere MQ, CICS Transaction Gateway, or SOAP (over HTTP). The CICS agent 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.

Adding the AppMon CICS programs 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 Download and SMP/E install of the z/OS Agent Components.

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

Installing the AppMon CICS programs and transaction

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

These transaction and group names are recommended by AppMon, 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(DYNATRACE AGENT UTILITY TRAN)
     GROUP(DTA1) PROGRAM(ZDTPLT) TASKDATAKEY(CICS) TASKDATALOC(ANY)

CEDA DEFINE PROGRAM(ZDTPLT) DESCRIPTION(DYNATRACE AGENT UTILITY PROG)
     GROUP(DTA1) DATALOCATION(ANY) EXECKEY(CICS)

CEDA DEFINE PROGRAM(ZDTPLTSD) DESCRIPTION(DYNATRACE AGENT SHUTDOWN PROG)
     GROUP(DTA1) DATALOCATION(ANY) EXECKEY(CICS)

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

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

CEDA DEFINE PROGRAM(ZDTSOAPH) DESCRIPTION(DYNATRACE 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 the AppMon CICS Agent to the CICS startup program list

Add the AppMon CICS PLTPI 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 agent after CICS initialization. It is recommended that the ZDTPLT entry immediately precede the TYPE=FINAL specification.

The JCL procedure DFHAUPLE in CICSHLQ.SDFHINST(DFHAUPLE) can be used to build the PLTPI table. This is an example PLTPI table that contains the AppMon CICS Agent.

*
* PLT USED TO SUPPORT DYNATRACE AGENT 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 Agent's exit workarea, 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 AppMon CICS Agent 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 the AppMon CICS Agent shutdown to the shutdown program list table

Add the CICS Agent shutdown program ZDTPLTSD before the DFHDELIM entry in your PLTSD source code and assemble the table. It is recommended that you 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. This is an example PLTSD table that contains the CICS Agent shutdown program.

*
* PLT USED TO SUPPORT DYNATRACE AGENT 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

Preparing your System Profile for CICS Agents

Add a CICS tier to the system profile that was created in the installation of the zDC. The wizard presents a number of tiers that are available. Select the CICS Agent.

Select the Tier Type
Select the Tier Type

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, the zDC that specifies DEFAULT(YES) is chosen 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[,FINE]'),

Fine logging can be set for diagnostic purposes by supplying the optional second parameter.

For linking CICS Agents to non-default zDCs, see zDC > 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 agent 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.

CICS PurePath

The following figure shows a CICS PurePath that was started by an MQGet call. The message was initially put into the queue by a Java application, so the CICS PurePath has been linked to the Java PurePath by MQ tagging.

CICS PurePath
CICS PurePath

The PurePath contains three CICS subpaths. The first path a) in CICS region C054 was started by a call to the MQ API. The first node FLCTRIG1 represents the initial program of the FLC1 transaction and contains details about the transaction. FLCTRIG1 started another transaction b) (EXEC CICS START) in the same region. This transaction did a DPL call to synchronously run another transaction c) in CICS region C013.

The following summarizes the different nodes in the PurePath:

  • Program: Program nodes are created for all programs that are called by EXEC CICS LINK calls. The initial program of a transaction (first node of CICS subpaths) also contains details about the transaction.

    • Method: CICS program name.
    • Argument: The transaction ID is captured as an argument on the initial program.
    • Class: Load module name.
    • API: CICS.
    • Return: Abend code if Abend occurred.

    The following image shows the details displayed when you hover the cursor over this Program node.

    • Messaging: Messaging nodes are created for all MQ API calls.
    • Method: MQ API call, for example MQPUT
    • Argument: (not applicable)
    • Class: MQ
    • API: MQSeries
    • Return: MQ reason code

    The following image show the details displayed when you hover the cursor over this Messaging node.

  • Database: Database nodes are created for all DB2 API calls.

    • Method: DB2 API call, for example SELECT
    • Argument: DBRM Name, Source Line, Section Number
    • Class: SQL
    • API: DB2
    • Return: SQL code

    The following image show the details displayed when you hover the cursor over this Database node.

    The connection pool attachment is filled with data from the DB2ENTRY definition. The URL is mapped to the name of the CICS DB2CONN entry. The pool size is mapped to the THREADLIMIT field in the DB2ENTRY.

Note

Transaction tracing started in another CICS region as a result of a CICS START TRANSACTION or DPL LINK request depends on the association data that accompanies these transactions when they flow over IPIC connections. This association data is also provided for transactions started over MRO connections for CTS version 4.2 and later. VTAM ISC connections do not support association data and transactions flowing over ISC are not traced.

Example Transaction Flows

The following screenshots show what the transaction flow for the different protocols may look like.