Two forgotten but useful CICS transactions

Since the ‘80s, IBM’s Customer Information Control System (CICS) has progressed to newer and fancier system interfaces. First, there was a string of full-screen command transactions, like CEMT, followed by the system programming interface (SPI) and CICS Explorer. There are, however, buried in IBM’s CICS documentation, a couple of lesser-known CICS transactions that still prove useful from time to time.

ADYN has yet to run its course
ADYN is one of the CICS transactions left over from when CICS didn’t support dynamic dataset allocation. In the old CICS/VS days, for example, a systems programmer could use ADYN to free an application file for batch jobs without bringing down the region. ADYN runs program DFH99 and, for those interested in dynamic allocation, the source is available in SDFHSAMP.

To start this CICS transaction, type ADYN from a clear screen. From there, ADYN presents a display similar to that of a command console. The command syntax roughly follows the same rules as the TSO ALLOC and FREE commands. Like CEMT, you can get help with any ADYN verb or parameter by using a question mark.

ADYN is interesting because the CLEAR key does not end the transaction. To exit, you must go to the upper left corner of the screen and press erase end-of-field, followed by ENTER.  You’re out of ADYN when you see the text “TRANSACTION END” on the screen. Doing anything else to exit is futile.

ADYN is now largely obsolete as CICS automatically allocates and frees application datasets. It is still useful, however, in allocating a big auxiliary trace dataset to debug a nasty problem. You would create the bigger dataset and then execute the following ADYN commands so CICS can use the new file:

        _{FREE DDNAME(DFHAUXT) UNALLOC}

_{ALLOC FILE(DFHAUXT) DSNAME(CICS.BIG.TRACE.DATASET) STATUS(SHR) DISP(KEEP) CONDDISP(KEEP)}

Note that standard dataset access rules apply -- you may not free an open dataset or allocate a file that CICS isn’t authorized to touch.

CSFE wears many hats
CSFE can perform several seemingly unrelated functions.

Entering CSFE without any operands puts it into echo mode. Any characters typed onto the display will be written to the screen. If, for instance, you type “xyz” and hit enter, the updated display shows “xyzxyz.” To exit, type “END” in the screen’s top left corner. This mode is not particularly useful.

CSFE also enables tracing for spool and terminal builder functions. CICS writes the extra trace entries to the internal table, but you must use auxiliary or Generalized Trace Facility (GTF) to capture them for debugging. The terminal builder trace can be turned on selectively for a specific or all auto-installed terminals.

Storage freeze, another CSFE function that can be selectively enabled by transaction, tells CICS to keep all the storage used by a task until the transaction ends. This may be useful in certain situations, including when a CICS transaction abnormally ends, updates files incorrectly or takes an unexpected code path, and information needed to debug the problem is in a piece of freed and reused storage. Apply this trace carefully -- before using it in production, you must ensure CICS can handle higher storage occupancy.

CSFE also controls a couple of powerful debugging traps. One is the global kernel exit, which the kernel calls on every domain call and return. When called, the global kernel exit can inspect the kernel stack for specific error conditions.

The other type of trap involves the global trap program. Occasionally, IBM won’t get all the information it needs to solve a problem or use SLIP. If all else fails, IBM’s level 2 support may code up a trap to capture diagnostic data when the error occurs.

IBM packages the trap as a replacement to module DFHTRAP and instructs the customer to use CSFE to activate it. When activated, CICS calls DFHTRAP before every trace entry with a parameter list that hopefully provides enough information for DFHTRAP to decide if the desired condition is met. DFHTRAP communicates back to CICS through a return action flag byte.

Lastly, the most useful CSFE function is the storage violation trap. Enabling the trap tells CICS to check transaction storage crumple zones before and after every trace entry. When it detects a damaged crumple zone, it writes an exception trace entry, creates a system dump file and turns itself off.

There are a few limitations to this trap. First, it will not detect storage violations that don’t damage crumple zones. As with all storage violation dumps, sometimes the trap will capture the victim (an unrelated task) and not the perpetrator (the transaction causing the overlay). Lastly, running the storage chain for the active task during each trace entry will cause overhead.

While this trap will not catch the violation during the overwrite, it will get you closer to the root cause of the issue. Every trace entry lists the return address of the caller. The return address of the storage violation trace entry and the previous trace record represent the range of instructions where the violation occurred. The granularity of the range depends on the application programs.

CICS transactions are worth it
Each CICS release introduces newer and bigger system management widgets, but tough problems sometimes call for a rarely used, lower-level debugging tool controlled by an obscure transaction. This is why a dive into IBM’s CICS documentation is always worth the trouble.

What did you think of this feature? Write to SearchDataCenter.com's Matt Stansberry about your data center concerns at [email protected].