IBM Tivoli Composite Application Agent for J2EE, Version 7.1.1

Customizing CICS transaction correlation

CICS® is a transaction framework, primarily used to run mature applications. To communicate with CICS, Java™ applications can use the CICS Transaction Gateway (CTG).

ITCAM for J2EE can use BCI (Byte Code Instrumentation) to collect data on CTG calls. The BCI engine injects callback code into CTG classes. To enable this feature, set the following property in the custom_directory/toolkit_custom.properties file:

com.ibm.tivoli.itcam.dc.ctg.enablectg=true

By default, when CTG BCI is enabled, the Data Collector callback code adds composite tracking data, called Global Publish Server (GPS) tokens. This data is added into the communications area (COMMAREA) used to carry transaction request data to CICS. This data can be used by ITCAM for Transactions, which instruments the CICS transaction framework. ITCAM for Transactions correlates every CICS transaction with the corresponding CTG call using the GPS token. The user can then view a detailed breakdown of transaction response time in the ITCAM Visualization Engine.

However, the presence of the GPS token in COMMAREA might not always be desirable. Disable GPS tokens if ITCAM for Transactions is not used for the CICS server. Otherwise, the GPS token reaches the server application, which might (in some cases) not process it correctly.

You can selectively disable GPS tokens for specific transactions. Selections can be based on CTG gateway address or protocol; by CICS system; by CICS program, or by the CICS transaction ID. To selectively disable GPS tokens, edit the file custom_directory/ctg.filters . This file can contain any number of lines with the following syntax:

Type=E|I[,Gateway=<CTG URL>][,Server=<CICS Server>][,Program=<CICS Program>]
  [,Transid=<Mirror tran ID>]

Each line defines a filter, which disables or enables GPS tokens for some transactions.

The Type parameter is mandatory for each line. A value of "E" sets up an Exclude filter; transactions matching it do not have a GPS token inserted into the COMMAREA. "I" denotes an Include filter; any transactions matching an include filter have a GPS token, overriding any Exclude filter applying to them.

All other parameters are optional, but at least one of them must be present on every line. To match a filter, a transaction must match all of the parameters set on the line:

Gateway is any part of the CTG URL, including the protocol, host name and/or port
Server is the host name of the CICS server (this name might be different from the CTG host name)
Program is the CICS program name (a field in a CICS transaction request)
Transid is the CICS Mirror Transaction ID. Except Multi Regional Operation (MRO) CICS/CTG environments, this parameter is of little use as all CTG transactions have the same Mirror Transaction ID

For example, to disable addition of GPS tokens to the COMMAREA of all transactions routed through the local protocol, add the following line to custom_directory/ctg.filters:

Type=E,Gateway=local://*

To disable addition of GPS tokens to some transactions while enabling them for other transactions, use lines similar to the following example:

Type=E,Program=CYN$*,Server=CICS3101
/*Disables addition of GPS tokens to transactions for programs starting 'CYN$' to be 
  run on the CICS3101 server.*/
Type=I,Program=CYN$ECI2,Server=CICS3101
/*Enables addition of GPS tokens for transactions for the CYN$ECI2 program to be 
  run on the CICS3101 server.*/

To disable addition of GPS tokens to all transactions, use the following line:

Type=E,Gateway=*

Feedback