Install OneAgent on CICS

The OneAgent CICS code module can either start new distributed traces for specific transaction codes or link CICS transaction distributed traces to distributed traces for transactions initiated using WebSphere MQ (Bridge or Trigger), CICS Transaction Gateway, HTTP/S, SOAP (over HTTP/S) or 3270 Transactions. It supports DB2, DL/I and MQ API calls tracing, as well as any programs invoked using CICS LINK. Linked distributed traces 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. OneAgent includes a PLT program that initiates at CICS startup, and the code module program that captures various events and forwards them to the zDC.

Add OneAgent to the CICS DFHRPL

You can dynamically add the load library as a CICS Library definition in the CSD. The CEDA definition is in SZDTSAMP member CICRDO. You can find it in the example in the next section.

If you don't want to use CICS Library definition, you must add the following PDS (or its contents) to the DFHRPL concatenation:

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

Where <hlq> is the high-level qualifier you set during installation of the OneAgent for z/OS.

Install Dynatrace 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).

dns
CEDA DEFINE LIBRARY(DYNATRA) DESCRIPTION(DYNATRACE LOAD Library)
     GROUP(DTA1) DSNAME01(<hlq>.SZDTLOAD)

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

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

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

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(ZDTAGT72) DESCRIPTION(DYNATRACE CTS 5.5 ETP AGENT)
     GROUP(DTA1) CEDF(NO) CONCURRENCY(THREADSAFE) DATALOCATION(ANY)
     LANGUAGE(ASSEMBLER)

CEDA DEFINE PROGRAM(ZDTAGT73) DESCRIPTION(DYNATRACE CTS 5.6 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 DEFINE TDQueue(ZDTQ) DESCRIPTION(DYNATRACE FOR DTAX Messages)
   GROUP(DTA1) TYPE(Extra) DAtabuffers(001) DDname(ZDTQ)
   Opentime(Deferred) Erroroption(Ignore) TYPEFile(Output)
   RecordSize(00136) BlockSize(00140) RECORDFormat(Variable)
   BLOCKFormat(Unblocked) DIsposition(Shr)

CEDA INSTALL GROUP(DTA1)

CEDA ADD GROUP(DTA1) LIST(XYZLIST)

Add 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.

dns
*
* PLT USED TO SUPPORT DYNATRACE 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 Dynatrace 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:

dns
DBPA 17.02 TRAN=*,PROGRAM=ZDTPLT*,CSECT=*

Add 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.

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

Add 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:

dns
INITPARM=(ZDTPLT='MEPC,<Option>'),

<Option> sets the logging level for CICS code module. Accepted values are,

FINE | F for fine logging. This is for internal debugging purposes only. Set this logging level at the request of Support.
INFO | I for info logging. This is the default.
WARNING | W for warning messages logging.
SEVERE | S for severe messages logging.

dns
Example:
INITPARM=(ZDTPLT='MEPC,SEVERE'),

For linking CICS code modules to non-default zDCs, see the section on Running multiple zDC systems on a single z/OS image.

Plexname grouping

You can group CICS regions belonging to the same CICSPlex into a single process group. To do so

In the Dynatrace menu, go to Settings and select Mainframe > Transaction monitoring.
Turn on Group CICS regions that belong to the same CICSPlex.
Add MASPLTWAIT(YES) to your LMAS parameter.

If you enabled grouping after the CICS region is up, you need to do DTAX DIS and DTAX EN for the plexname grouping.

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:

xml
<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 traced by a CICS Code Module sensor, add the previous <headerprogram> stanza to the service requester pipeline definitions of those SOAP services that should be traced. Outbound SOAP requests that occur within CICS transactions that aren't traced are ignored, however tracing isn't limited to requests from SOAP programs that act as CICS SOAP service providers.

Route DTAX messages using TDQueue

To optionally route DTAX messages to Dynatrace TDQueue (Transient Data Queue), use the ZDTQ resource definition provided above in your CICRDO member.

By default, the queue remains closed through the OPENTIME(DEFERRED) attribute. You must manually open it by using the CEMT INQUIRE|SET TDQUEUE command. To default the queue to open at install time, use the OPENTIME(INITIAL) attribute.

Upgrading OneAgent on CICS without region restart

To upgrade your OneAgent without restarting the region, first download and extract the new PAX file onto your mainframe. For instructions on installing the new PAX file, see Download OneAgent to z/OS.

Disable the DTAX transaction in the CICS region with the DIS command.
Copy the CICS code modules in the SZDTLOAD dataset into the Dynatrace DFHRPL dataset defined to your CICS region.
Use the CICS command CEMT I PROG(ZDT*) to display the Dynatrace CICS code modules. Use the SET PROG(ZDT*) NEWCOPY command to tell CICS a new version of each program will be used.
Enter CICS command CEDA INSTALL GROUP(DTA1) to install the new code modules to the CICS region.
Enable the DTAX transaction with the EN command. Verify the new OneAgent version is displayed on the DTAX panel.