In last month's column I talked about the CICS' trace facility in its several forms. This month I intend to get into more detail about the trace and where I've found it to be very useful.
There are three types of actual trace entries: event, exception and domain. Event trace entries signify an action within CICS and its result. They are single records without separate entry and exit entries. However, if you look closely at the description for some of them you will find beginning and completion entries for some system actions. For instance, a call to check transaction authorization opens with an "XS 0709 XSRC EVENT CHECK" entry followed by an "XS 070A XSRC EVENT CHECK-COMPLETE" record. I'm not sure what IBM had in mind with these things, but you should check the CICS trace entries manual for interpretation and usefulness of each entry.
CICS writes exception entries for errors such as ABEND's or non-zero VSAM return codes. They are easily identified in formatted traces by the string *EXC*. Interestingly enough, CICS creates these entries even if internal trace is turned off. So it's not unusual to format the trace in a dump and see pages of exception entries. It also explains an IBM statement recommending shops leave auxiliary trace on but internal trace off. With internal trace off, CICS will only write the exception entries to the auxiliary trace datasets. By the end of the day, you can then print the auxiliary trace datasets and have a list of exceptions for the day.
CICS domain trace a useful utility
Domain trace entries are the most numerous, detailed and useful. CICS writes them whenever the flow of control enters or leaves a domain gate. There are varying levels of trace entries for many of the domains which can be controlled through system initialization table (SIT) parameters.
The domain trace entries reveal a lot about how CICS works and what it is thinking. For instance, a normal file I/O beings with an EIP (execution interface program) entry for the CICS command. The next few entries will be in file control, with side trips into table manager to locate the file control table (FCT) entry. You may also see calls into the storage domain for buffers or file control blocks. After all this CICS eventually returns to the program with an EIP exit trace record listing the end result.
There is a wealth of information within the domain trace. The R14 field in the EIP entry record points back to the offset into the application program that issued the command. Each domain call is bracketed by entry and exit points making it possible to calculate how long each one takes; although you should remember that the elapsed time includes tracing overhead.
Some of the trace entries contain detailed information and snatches of application data, either in the interpreted fields just below the entry heading or dumped information underneath. Not all of this information is useful and none of it should be interpreted without consulting trace manual. However, the manual is a little cagey about some of the entries that are meant for IBM support only. For instance, there are some storage manager trace entries whose documentation is only, "domain gate parameter list" with no clue as to what the parameters are.
Reading CICS trace transactions
In the absence of a more sophisticated tool such as Strobe, the entry and exit trace points provide an excellent means for analyzing an application's performance. I begin by tracing a transaction through GTF and creating a dataset of the full trace with IPCS. The formatted trace can be read with an appropriate tool (I prefer SAS for ease of processing timestamps). Once read you can build useful reports:
How much time each individual file control or DB2 I/O took
The total amount of time spent by command type
Total time of file or DBMS I/O
The top ten longest API calls.
Someone might make the case for reading the trace datasets directly instead of the formatted output but I wouldn't recommend it. The days of fixed length 16 byte trace records are gone forever and the format or interpretation could change at the application of a PTF.
After spending two columns on the subject you can probably tell I'm a big fan of trace. Analyzed carefully it will provide mountains of information about an application. To the curious systems programmer it will reveal some of CICS' secrets. I just wish other subsystems were as generous.
ABOUT THE AUTHOR: Robert Crawford has been a CICS systems programmer off and on for 24 years. He is experienced in debugging and tuning applications and has written in COBOL, Assembler and C++ using VSAM, DLI and DB2.
