IBM Tivoli Composite Application Manager for Application Diagnostics, Version 7.1.0.1

Customize 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, 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 will add composite tracking data, called Global Publish Server (GPS) tokens, 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 will correlate 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 may not always be desirable. Disable GPS tokens if ITCAM for Transactions is not used for the CICS server. Otherwise, the GPS token will reach the server application, which may (in some cases) not process it correctly.

You can selectively disable GPS tokens for specific transactions based on CTG gateway address or protocol; by CICS system; by CICS program or by the CICS transaction ID. To do this, 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 will not have a GPS token inserted into the COMMAREA. "I" denotes an Include filter; any transactions matching an include filter will 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:

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 transactions for programs starting'CYN$' to be run on the CICS3101 server, but enable them for transactions for the CYN$ECI2 program on the same server, use the following lines:
Type=E,Program=CYN$*,Server=CICS3101
Type=I,Program=CYN$ECI2,Server=CICS3101
To disable addition of GPS tokens to all transactions, use the following line:
Type=E,Gateway=*


Parent topic:

Customization and advanced configuration for the data collector