What to do when your IMS program terminates abnormally

• Record as much information as possible about the circumstances under which the program terminated abnormally.
• Check for certain initialization and execution errors.

Recommended actions after an abnormal termination of an IMS program

Many places have guidelines on what you should do if your program terminates abnormally. The suggestions given here are common guidelines:

• Document the error situation to help in investigating and correcting it. The following information can be helpful:
  • The program's PSB name
  • The transaction code that the program was processing (online programs only)
  • The text of the input message being processed (online programs only)
  • The call function
  • The name of the originating logical terminal (online programs only)
  • The contents of the PCB that was referenced in the call that was executing
  • The contents of the I/O area when the problem occurred
  • If a database call was executing, the SSAs, if any, that the call used
  • The date and time of day
• When your program encounters an error, it can pass all the required error information to a standard error routine. You should not use STAE or ESTAE routines in your program; IMS uses STAE or ESTAE routines to notify the control region of any abnormal termination of the application program. If you call your own STAE or ESTAE routines, IMS may not get control if an abnormal termination occurs.
• Online programs might want to send a message to the originating logical terminal to inform the person at the terminal that an error has occurred. Unless you are using a CCTL, your program can get the logical terminal name from the I/O PCB, place it in an express PCB, and issue one or more ISRT calls to send the message.
• An online program might also want to send a message to the master terminal operator giving information about the program's termination. To do this, the program places the logical terminal name of the master terminal in an express PCB and issues one or more ISRT calls. (This is not applicable if you are using a CCTL.)
• You might also want to send a message to a printer so that you will have a hard-copy record of the error.
• You can send a message to the system log by issuing a LOG request.
• Some places run a BMP at the end of the day to list all the errors that have occurred during the day. If your shop does this, you can send a message using an express PCB that has its destination set for that BMP. (This is not applicable if you are using a CCTL.)

Diagnosing an abnormal termination of an IMS program

If your program does not run correctly when you are testing it or when it is executing, you need to isolate the problem. The problem might be anything from a programming error (for example, an error in the way you coded one of your requests) to a system problem. This topic gives some guidelines about the steps that you, as the application programmer, can take when your program fails to run, terminates abnormally, or gives incorrect results.

IMS program initialization errors

Before your program receives control, IMS must have correctly loaded and initialized the PSB and DBDs used by your application program. Often, when the problem is in this area, you need a system programmer or DBA (or your equivalent specialist) to fix the problem. One thing you can do is to find out if there have been any recent changes to the DBDs, PSB, and the control blocks that they generate.

IMS program execution errors

If you do not have any initialization errors, check:

1. The output from the compiler. Make sure that all error messages have been resolved.
2. The output from the binder:
   • Are all external references resolved?
   • Have all necessary modules been included?
   • Was the language interface module correctly included?
   • Is the correct entry point specified?
3. Your JCL:
   • Is the information that described the files that contain the databases correct? If not, check with your DBA.
   • Have you included the DL/I parameter statement in the correct format?
   • Have you included the region size parameter in the EXEC statement? Does it specify a region or partition large enough for the storage required for IMS and your program?
   • Have you declared the fields in the PCB masks correctly?
   • If your program is an assembler language program, have you saved and restored registers correctly? Did you save the list of PCB addresses at entry? Does register 1 point to a parameter list of fullwords before issuing any DL/I calls?
   • For COBOL for z/OS® and PL/I for MVS and VM, are the literals you are using for arguments in DL/I calls producing the results you expect? For example, in PL/I for MVS and VM, is the parameter count being generated as a half-word instead of a fullword, and is the function code producing the required 4-byte field?
   • Use the PCB as much as possible to determine what in your program is producing incorrect results.