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).
If CICS translation correlation 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. If ITCAM for CICS Data Collector or ITCAM for CICS Client is not installed on the CICS server, the GPS token might reach the server application, which may (in some cases) not process it correctly. For this reason, transaction correlation is disabled by default.
You can enable GPS tokens for specific transactions based on CTG gateway address or protocol; by CICS system; by CICS program or by the CICS transaction ID. Enable correlation with CICS systems that have the ITCAM for CICS data collector installed, configured, and enabled. To do this, edit the file DC_home/runtime/app_server_version.node_name.server_name/custom/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:
- 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 may 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 will 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 DC_home/runtime/app_server_version.node_name.server_name/custom/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=CICS3101The default configuration is to disable all correlation through the following line:Type=E,Gateway=*
Parent topic:
Customization and advanced configuration for the data collector