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:
// 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
).
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.
*
* 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
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:
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.
*
* 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:
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.
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:
<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 DynatraceDFHRPL
dataset defined to your CICS region. - Use the CICS command
CEMT I PROG(ZDT*)
to display the Dynatrace CICS code modules. Use theSET 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.