Troubleshooting PGMIDERR/AEI0 ABEND in CICS Transaction Gateway

The CICS Transaction Gateway (CTG) offers Java clients a simplified means for communicating with CICS. It is, for the most part, a black box that talks to CICS through the External Call Interface, which sometimes makes problem diagnosis a little difficult. This column deals with a particular type of error, the program not found (PGMIDERR) and AEI0 ABEND.

Receiving the initial PGMIDERR/AEI0 ABEND error in CTG
A CTG client gets to CICS by specifying a uniform resource locator (URL) and a target program name. A client has the option to include a transaction and CICS application ID. Any transaction driven through CTG must define the CICS mirror program (DFHMIRS) as its initial program.

When a message arrives, CICS attaches the target transaction and calls DFHMIRS. DFHMIRS plucks the application program name from the header and attempts to link to it, passing the payload in a communications area. If the program is executable, everything proceeds as planned. If there is a problem, DFHMIRS returns the error to the client as "program not found" (or PGMIDERR) and AEI0 ABEND. Eventually, this gets to the client when it sees variable eci_abend_code set to AEI0.

Steps for diagnosing PGMIDERR/AEI0 ABEND
At first, this sounds pretty easy to diagnose, but there are a several problems when attempting to find out what's gone wrong. When DFHMIRS fails to link to the target program, it quietly sends the error back to CTG without writing any messages to the CICS log. CTG is wise enough to recognize the problem, but, at the default level of tracing, it isn't logged anywhere except in its own internal trace table. Lastly, in a CICSPlex environment with multiple CTGs and routing regions, there's no telling where the error occurred.

The first step for troubleshooting this problem involves isolating the offending client message from the one that may be able to get the program name. There are several choices to get the message:

• The least favorite option is some sort of network trace. Not only does it entail wading through mountains of data, but once the error message is found, it must somehow be matched up with the original request. The two advantages of this option are that it doesn't involve crawling through a complicated mainframe environment and is the least invasive.
• In a simple or small configuration, a CICS auxiliary or GTF trace can pinpoint the problem fairly quickly. However, an intermittent error in a big CICSPlex may require tracing many regions for extended periods of time. If a trace manages to capture the error, there will still be oceans of output to go through. Lastly, as everyone knows, tracing has a deleterious effect on performance.
• Tracing in later versions of CTG can be manipulated with a modify command. In addition, CTG will write the trace to SYSOUT, making it much easier to peruse. To catch this error, however, you might have to turn on trace level 4 on several CTG instances. This option has the same disadvantages as a CICS trace, especially in complicated environments.
• Dumping CTG is the easiest, most direct way to get the information. If you run multiple CTG instances, you will need a dump of each one. Also note that the dump command must include both the MVS address space as well as the attached OMVS process.
  The Interactive Problem Control System verb exit DFHPD650, supplied with CICS, formats the trace. The printed trace records (using DFHPD650 operand "TR=2") make it a simple matter of searching for "AEI0" (the ABEND code) to see the error entry complete with the bogus program name.

No matter the method, with the program name in hand, the mystery should be solved quickly. Or will it be? There are a couple of obvious reasons why the program name may be invalid. For instance, the name in the message may contain illegal characters or end with a null character (x'00') instead of a blank. If the program name appears to be valid, finding the error comes down to a two-step process:

1. Sign onto CICS to look to look for the program's definition.
2. Bang your head against your desk when you find out that the program is properly defined and usable.

It turns out that there are many reasons for AEI0 ABENDs, including, but not limited to, the following:

• DPL errors when CICS knows it's supposed to forward the request to another region but there aren't any routes available.
• The target program is disabled on the target AOR.
• In rare cases, when the transaction makes it through the routing region but gets a security error on the target AOR.

To get to the bottom of the above types of errors, the only recourse is a CICS trace, unless other diagnostic information is available.

Even though CICS and CTG silently conspire to hide the error, there are places a user can log the event. For instance, a shop with a custom dynamic routing program can log messages when called after a routing error and the DTR error field is set to c'7'. There are also some global user exits where the event can be observed and logged. The final option is to make sure the error never happens again.

ABOUT THE AUTHOR: For 24 years, Robert Crawford has worked off and on as a CICS systems programmer. He is experienced in debugging and tuning applications and has written in COBOL, Assembler and C++ using VSAM, DLI and DB2.

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