The CICS trace domain also provides a diagnostic global trap/trace exit program called DFHTRAP. This allows a detailed online investigation, typically without having to stop and restart CICS when wanting to use it. The global trap/ trace exit is used to detect errors that can’t be diagnosed by other methods and is intended to be used only with guidance from IBM service personnel. DFHTRAP is an Assembler language program that can be invoked whenever the trace domain is called to make a trace entry. The trap must be activated before it’s used, either dynamically or at CICS initialization. A skeleton version of DFHTRAP is supplied in both source and load-module forms. For CICS Transaction Server 3.1, the source of DFHTRAP is provided in the CICS640. SDFHMAC library. The source of the skeleton DFHTRAP contains comments explaining its use of registers and DSECTs and the coding necessary to use the exit. Note that the code in DFHTRAP must not use any CICS services, cause the current task to lose control, or change CICS system status.
For more details, see the CICS Transaction Server 3.1 Problem Determination Guide. In addition, the February/March 2005 issue of z/Journal contains the article “DFHTRAP: Assisting the CICS Systems Programmer.”
The CICS transaction dump and CICS system dump can help you with problem determination. The type to use depends on the nature of the problem. In practice, the system dump is often the most useful; it contains more information a problem you suspect is limited to a particular program, a transaction dump may suffice. It will capture transaction-related storage and trace entries. However, a transaction dump might have missed some important information. That would be true if your problem relates to deadlocks between multiple tasks and you need to refer to task storage for several tasks in the system at the time of the deadlock.
Transaction dumps contain transaction- specific information that’s written to a pair of CICS BSAM data sets, with DD names DFHDMPA and DFHDMPB. CICS system dumps contain data from the entire CICS system address space and this is written to z/OS dump data sets. CICS can write only one system dump to any individual dump data set.
CICS provides transaction and system dump tables to let you dynamically control the number and type of dumps produced. For example, revisiting the deadlock scenario between multiple CICS tasks, you may wish that CICS produce a system dump instead of a transaction dump. The following example shows how to use the CICS supplied transaction, CEMT, to make a transaction abend code ASRB produce a CICS system dump:
CEMT SET TRDUMPCODE(ASRB) ADD SYSDUMP
You may wish to produce a CICS system dump when a specific CICS message is issued. You can do this by adding the dump code (constructed by removing the “DFH” prefix from the message number) to the system dump table, and specifying the SYSDUMP option. CICS then causes a system dump to be taken when the message is issued. Here’s an example that will produce a CICS system dump when the DFHXS1111 message is written: CEMT SET SYDUMPCODE(XS1111) ADD You also can limit the number of these dumps taken by setting a maximum limit:
CEMT SET SYDUMPCODE(XS1111) MAX(1)
To determine which messages you can do this for, look in the CICS Messages and Codes manual. If the message you’re interested in has a two-character alphabetic component ID after the “DFH” prefix, and it has either XMEOUT global user exit parameters or a destination of “Terminal User,” you can use it to construct a system dump code to add to the dump table.