Error handling in IDMS programs

Products

• IDMS

Issue/Introduction

This article describes proper error-handling coding practices in IDMS application programs.

Environment

Release: All supported releases.

Resolution

After every IDMS database command, IDMS populates a four-byte numeric field called ERROR-STATUS with a value to indicate the result of the command, so that the application program can take action accordingly. This value can be used to determine whether the command was successful, or if it failed and why. It is critical that programs query this field and take appropriate action.

ERROR-STATUS has some 88-level condition names for the most commonly used values. Some examples are included here because they are referenced in this article.

0000            DB-STATUS-OK
0307            DB-END-OF-SET
0326            DB-REC-NOT-FOUND 
0001 thru 9999  ANY-ERROR-STATUS

The most common error that programmers make is to assume that, when attempting to read a particular record, any status other than 0000 means the record was not found. While this is true, different values of error-status have different meaning of varying importance. Example:-

MOVE 1234 TO EMP-ID-0415.
OBTAIN CALC EMPLOYEE.
IF DB-STATUS-OK THEN
    < do whatever processing is necessary for the EMPLOYEE record >
ELSE
    DISPLAY 'EMPLOYEE RECORD NOT FOUND'
END-IF.

This is not good programming. It assumes that anything other than 0000 means that there is no EMPLOYEE record with EMP-ID-0415 equal to 1234. This might not necessarily be the case. The OBTAIN statement may have returned other non-zero values which mean something different. The most obvious example is something like 0361 which would be an indication that there is database corruption or a potential dirty read scenario, but it tells the program nothing about whether or not EMPLOYEE 1234 exists.

The proper way to code the above is as follows:

MOVE 1234 TO EMP-ID-0415.
OBTAIN CALC EMPLOYEE.
IF DB-REC-NOT-FOUND THEN
    DISPLAY 'EMPLOYEE RECORD NOT FOUND'
ELSE
    PERFORM IDMS-STATUS
    < do whatever processing is necessary for the EMPLOYEE record >
END-IF.

IDMS-STATUS is a standard IDMS provided paragraph that will do nothing if ERROR-STATUS is 0000, but otherwise abend the program.

The critical consideration is that in general, there are three situations that a program must consider.

1. The command was completely successful - ERROR-STATUS 0000.
2. The command failed for a reason that is reasonably expected in the context of the program - e.g. ERROR-STATUS 0326 DB-REC-NOT-FOUND.
3. The command failed for an unexpected reason.

A different course of action should be taken for each situation.

Additional Information

DML Reference for COBOL
Navigational DML Programming Techniques