Mainframe shops may already be familiar with DFHTRAP. Sometimes, when IBM runs into a problem it can't debug by other means, they will send a usermod for module DFHTRAP and ask the systems programmer to use the obscure CSFE transaction to enable it. But, as I've recently discovered, in some specific situations a carefully used and deployed DFHTRAP can be a friend to the user as well.
Limitations and capabilities
When enabled, CICS invokes DFHTRAP for every trace entry. The idea is that DFHTRAP can examine the trace entry and decide if this is the time to gather diagnostic information. However, there are some severe restrictions:
- It cannot make CICS calls or invoke CICS services
- It may not cause another trace entry unless done through action flags
- It has limited addressability
- The code should be as efficient, clean and quick as possible
I should also note that CICS trace records, especially the new format ones, are poorly documented. This means you may have a lot of work ahead of you trying to decide which trace entry and data you're looking for. After looking at the manual the next steps to finding the right trace entry are auxiliary traces and dumps.
Despite these restrictions DFHTRAP has several avenues for self-expression. The IBM-approved method is to use CICS provided action flags. These flags, more fully explained below, tell CICS what to do when DFHTRAP returns. Other, non-IBM approved methods might be to issue "write to operator" (WTO) messages or copying data into itself or the CICS provided work area to be found later in a dump.
Lastly, the documentation admonishes the systems programmer to use DFHTRAP only under the supervision of CICS technical support although there is a lot of good documentation specifically for this module. My advice would be to look through the books and DFHTRAP's source in SDFHSAMP to see if it applies to your situation. Go solo if you feel confident enough to do so but remember that you should expect no help from IBM if you break the system. If you don't feel confident, open a problem with IBM and seek their advice. They might even be able to provide some information about what you're looking for.
Invocation
You enable DFHTRAP with the CSFE transaction as follows:
CSFE DEBUG,TRAP=ON
At that point DFHTRAP is in use and cannot be new copied until it is disabled through a "CSFE DEBUG,TRAP=OFF" command. Note that DFHTRAP is active as long as CICS is up. Once it bounces you must re-enter the CSFE.
CICS invokes DFHTRAP with these parameters:
- Action flags to indicate what's supposed to happen when DFHTRAP returns. These flags may be set in any combination:
- Do nothing
- Make another trace entry using data included in areas whose addresses are below
- Take a TR1003 system dump
- Terminate CICS without a dump with message DFHTR1000. To get a dump the flag above must also be set
- Disable DFHTRAP
- The current trace entry
- Up to three areas to be included in a further trace entry
- An 80 byte work area dedicated to DFHTRAP
- The missing and presumed extinct Common Systems Area (CSA)
- The ever elusive task control area (TCA)
- A register save area
Consult the documentation for more information about how to use these fields in for what you want. You should, however, resist the temptation to go chaining through CICS control blocks. First, many of the blocks are no longer documented and you could end up taking a flying leap. Second, you can put a significant drag on the system by chasing a long control block chain on every trace entry.
Example
Assume you have an application transaction that normally receives one input message and sends one out (pseudo-conversational in CICS parlance). But occasionally, the transaction will issue a second receive and hang. You have taken a dump so the programmers know where the second receive executes, but they insist the logic path to get there can only happen through specific circumstances involving interaction with other transactions active at the time. Your problem is the dump you get is long after the conditions driving the rogue transaction through that logic are gone.
DFHTRAP can cause a dump at the time of the second receive. The trick is figuring out when. First you must dive into the trace manual to figure out what a RECEIVE trace entry looks like. Remember that DFHTRAP sees every trace so you don't necessarily have to spring on the EIP entry. Then you have to decide what other data available to DFHTRAP that helps make the decision when to spring. For instance:
- You may find the transaction ID in the TCA
- R14 is available from the trace entry.
- From some of the terminal control trace entries you may be able to look at message content
- If all else fails, you may use the provided 80 byte work area to keep track of receives by task number.
As you can see, deciding when to dump can be complicated and you wouldn't want to move DFHTRAP to production without being very sure the logic is correct.
Given its limitations and potential impact to the system, I would not make DFHTRAP my primary debugging tool. There are too many other facilities available in CICS and the mainframe for that. However, it may be something to reach for when you have an obscure and intermittent bug. Just be sure to remember the penalties for guessing wrong and IBM's stern warning.
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.
