Tip

CICS trace: Getting started, formatting and externalizing

CICS expert Robert Crawford describes the handy CICS trace tool and gives code for externalizing its output.

Robert Crawford
By
Published: 29 Jan 2007

In my five year stint as a Windows programmer I learned many things. Among them were new programming languages and development environments. Within the scope of programming I also learned the drudgery of debugging my programs without all the dandy tools we have on the mainframe. Throughout the whole experience the one I missed the most was the CICS trace.

What is CICS trace?

CICS trace is a wonderful tool for understanding how and why a system or application does things. At defined trace points, CICS writes variable length trace entries into the in-core trace table. In addition, application programs can create their own trace entries with the ENTER TRACENUM command. There are hundreds of trace points with differing levels of detail.

More on CICS tools:
Q&A: IBM offers a peek at new SOAP for CICS

New mainframe migration tools: It's really about app modernization

Over all this, CICS gives you control for each trace point's action and detail with transaction CETR. In fact, I would recommend entering CETR as a quick reference to CICS trace points and the detail levels that are available.

Getting started with CICS trace

The most basic form is the CICS internal trace. As mentioned above, the entries are written into a table in memory. And since the table is in memory, you won't see the entries except in dumps. Also, note that the table is of finite size and CICS will wrap around back to the top of the trace entries when it is full. In a very active system the trace table may wrap in less than a second which means some of the information you need may be overwritten before CICS takes the dump.

Internal trace is controlled through the several System Initialization Table (SIT) parameters:

  • INTTR specifies if internal trace should be started at all
  • SPCTR and SPCTRxx (where "xx" is a domain name) options allow you to control individual trace points and their level of detail.
  • SYSTR is the master system trace flag controlling system trace entries
  • TRTABSZ specifies the size of the internal trace table in K

    Of course, internal tracing comes with overhead. In my own experience, turning trace off saved about 10 to 15% CPU at the transaction level. This is probably why IBM sometimes recommends turning the trace off in production systems. At our own shop, we leave trace off except in regions that support critical applications where we can't afford to have the same problem twice.

    Externalizing CICS trace

    Since internal trace is ephemeral, there are two ways to externalize trace entries without a dump: auxiliary and GTF trace.

    When auxiliary trace is active, CICS writes the entries to the auxiliary trace datasets DFHAUXT and DFHBUXT. Once captured the trace entries must be formatted with the CICS trace utility, DFHTUxxx where "xxx" is CICS' release level. You can select the detail level and trace types of the printed entries. Perhaps even more useful, you can control the utility's output by resource names such as transaction or terminal ID.

    You may control auxiliary trace with the CEMT S AUX command or these SIT parameters:

  • AUXTR tells CICS if you want to start auxiliary trace when it initializes. This can be very handy if you have a problem in a PLTPI program
  • AUXTRSW specifies the auxiliary trace dataset switch behavior. On an active system the auxiliary trace datasets fill up quickly. CICS' default action is to stop auxiliary trace and close the dataset to which it is writing. This parameter, and its corresponding CEMT command, allows you to tell CICS that you would rather switch to the inactive trace dataset.

    Auxiliary trace has a lot of overhead. As I know from experience, you don't want to start it on a busy system in the middle of the day because it will have a direct impact on performance. Therefore, in production it should be used in circumstances that are limited and easily controlled. If that's too difficult, try to duplicate the problem in test and take your trace there.

    My favorite way to externalize trace entries is through MVS' General Trace Facility (GTF) where CICS writes trace records to the GTF trace table. This is very useful if you need to collect debugging information involving several CICS regions or other system components. In my experience, it also causes less overhead than auxiliary trace. The only catch is you have to run MVS' GTF trace capture utility program (AHLGTF) during the activity you want to capture.

    Formatting CICS trace

    Once you capture the trace information you may format it with the IPCS GTF subcommand. Here is the format:

    GF USR(F6C) CICS((xxxx))

    Note that you must specify "USR(F6C)" to tell IPCS to invoke CICS' dump utility program. This also means the dump utility program (DFHDUxxx where "xxx" is the release) must be in STEPLIB, ISPLLIB, LPA or the link list. The "CICS" parameter allows you to specify trace record using the same syntax as the auxiliary trace utility. However, you should consult the IPCS User's Guide because not all choices are available.

    GTF trace is controlled through the GTFTR SIT parameter. Again, it can be handy to turn on GTF trace when CICS initializes if you have a PLTPI problem. You can also use transaction CETR.

    CICS' trace facility can be a profound tool for understanding application and system behavior, given the amount of information it provides. I would recommend turning it on at any odd, idle moment when you want to know more about what makes CICS click, but maybe not in production. They may have taken the source away from us, but we still have the trace.

    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.

    • Dig Deeper on Data center hardware and strategy