[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

HP COBOL
DBMS Database Programming Manual

4.8 Programming for Database Exceptions and Error Handling

Your program must contain logic to accommodate exceptions and errors. The items of syntax in HP COBOL that are used for this purpose are ON ERROR, AT END, and USE.

4.8.1 Database On Error Condition

The database on error exception condition occurs when the DBCS encounters a database exception condition for any data manipulation language (DML) statement.

The ON ERROR phrase in a DML statement allows the selection of an imperative statement sequence when any database exception condition occurs.

The NOT ON ERROR phrase allows execution of an imperative statement when a database exception condition does not occur.

The format is as follows:

Stment is an imperative statement.

When a database exception condition occurs and the statement contains an ON ERROR phrase:

The imperative statement associated with the ON ERROR phrase executes.
The NOT ON ERROR phrase, if specified, is ignored.
Control is transferred to the end of database statement unless control has been transferred by executing the imperative statement of the ON ERROR phrase.

When a database exception condition occurs and the statement does not contain an ON ERROR phrase:

The applicable USE FOR DB-EXCEPTION, if specified, executes.
If an applicable USE procedure does not exist, the run unit terminates abnormally.
The NOT ON ERROR phrase, if specified, is ignored.

When a database exception condition does not occur:

The imperative statement associated with the NOT ON ERROR phrase, if specified, is executed.
The ON ERROR phrase, if specified, is ignored.
Control is transferred to the end of the database statement unless control has been transferred by executing the imperative statement of the NOT ON ERROR phrase.

Use the ON ERROR phrase to transfer execution control to the associated statements' error handling routine, where your program can supply useful and effective debugging information. (See Section 4.8.3 for examples and Glossary of Oracle DBMS-Related Terms for more information on Oracle CODASYL DBMS Database Special Registers.) The ON ERROR phrase can be part of every DML statement. It allows you to plan the graceful termination of a program that would otherwise terminate abnormally. (In a FETCH or FIND statement, you cannot specify both the ON ERROR and AT END phrases in the same statement.) For example:

PROCEDURE DIVISION.
    .
    .
    .

    RECONNECT PARTS_RECORD WITHIN ALL
              ON ERROR DISPLAY "Exception on RECONNECT"
                       PERFORM PROCESS-EXCEPTION.
    .
    .
    .
PROCESS-EXCEPTION.
    DISPLAY "Database Exception Condition Report".
    DISPLAY " ".
    DISPLAY "DB-CONDITION            = ", DB-CONDITION
                                          WITH CONVERSION.
    DISPLAY "DB-CURRENT-RECORD-NAME  = ", DB-CURRENT-RECORD-NAME.
    DISPLAY "DB-CURRENT-RECORD-ID    = ", DB-CURRENT-RECORD-ID
                                          WITH CONVERSION.
    DISPLAY " ".
    CALL "DBM$SIGNAL".
    STOP RUN.

4.8.2 At End Condition

An at end condition occurs when a program detects the end of a file. The at end condition may occur as a result of a FETCH or FIND statement execution in your database program. You use the AT END phrase to specify the action your program is to take when an at end condition occurs.

The NOT AT END phrase specifes the action your program takes if an AT END does not occur.

Use the AT END phrase of the FETCH and FIND statements to handle the end of a collection of records condition. Your program will terminate if: (1) an at end condition occurs, (2) the program does not include the AT END phrase, and (3) there is no applicable USE statement.

When an at end condition occurs and the statement contains an AT END phrase:

The imperative statement associated with the AT END phrase, if specified, executes.
The NOT AT END phrase, if specified, is ignored.
Control is transferred to the end of the I/O statement unless control has been transferred by executing the imperative statement of the AT END phrase.

When an at end condition occurs and the statement does not contain an AT END phrase:

If the at end condition is associated with a FETCH or FIND statement, an applicable USE FOR DB-EXCEPTION procedure, if specified, executes. If the AT END phrase or USE FOR DB-EXCEPTION procedure is not specified, the run unit terminates abnormally.
If the at end condition is associated with a FETCH or FIND statement, DB-CONDITION is set to DBM$_END.
The NOT AT END phrase, if specified, is ignored.

When an at end condition (or any other error condition) does not occur:

The AT END phrase, if specified, is ignored.
The imperative statement associated with the NOT AT END phrase, if specified, is executed.
Control is transferred to the end of the I/O statement unless control has been transferred by executing the imperative statement of the NOT AT END phrase.

4.8.3 Exception Conditions and the USE Statement

Planning for exception conditions is an effective way to increase program and programmer productivity. A program with USE statements is more flexible than a program without them. They minimize operator intervention and often reduce or eliminate the time you need to debug and rerun the program.

The USE statement traps unsuccessful run-time Oracle CODASYL DBMS exception conditions that cause the execution of a Declaratives procedure. A Declaratives procedure can:

Supply useful and effective database debugging information (see Section 2.2 for more information on Oracle CODASYL DBMS Database Special Registers)
Provide alternate processing paths for specific exception conditions

Two sets of USE statements follow:

The first set, shown in Example 4-1, consists of a single USE statement. This database USE procedure executes for any and all database exception conditions. If you select this set, it must be the only database USE statement in the Declaratives Section. Its format is:

USE [ GLOBAL ] FOR DB-EXCEPTION.

Example 4-1 A Single USE Statement

PROCEDURE DIVISION.
DECLARATIVES.
200-DATABASE-EXCEPTIONS SECTION. USE FOR DB-EXCEPTION.
DB-ERROR-ROUTINE.
    DISPLAY "Database Exception Condition Report".
    DISPLAY "-------------------------------------------".
    DISPLAY "DB-CONDITION            = ", DB-CONDITION
                                          WITH CONVERSION.
    DISPLAY "DB-CUR-REC-NAME  = ", DB-CURRENT-RECORD-NAME.
    DISPLAY "DB-CURRENT-RECORD-ID    = ", DB-CURRENT-RECORD-ID
                                                 WITH CONVERSION.
    DISPLAY "DB-CUR-REC-ID    = ", DB-CRID.
    DISPLAY " ".
    CALL "DBM$SIGNAL".
END DECLARATIVES.

The second set, shown in Example 4-2, consists of one or more Format 1 USE statements, and one Format 2 USE statement.
Format 1

maximum

USE [GLOBAL] FOR DB-EXCEPTION ON DBM$_exception-condition [, DBM$_exception-condition]...

A Format 1 database declarative executes whenever a database exception condition occurs and the corresponding DBM$_exception-condition is explicitly stated in the USE statement.
Format 2

USE [ GLOBAL ] FOR DB-EXCEPTION ON OTHER.

A Format 2 declarative executes whenever a database exception condition occurs and the corresponding DBM$_exception-condition is not explicitly stated in any Format 1 USE statement.

Example 4-2 Multiple USE Statements

PROCEDURE DIVISION.
DECLARATIVES.
200-DATABASE-EXCEPTIONS SECTION.
    USE FOR DB-EXCEPTION ON DBM$_CRELM_NULL,
                            DBM$_CRTYPE_NULL.
200-DATABASE.
    PERFORM 300-REPORT-DATABASE-EXCEPTIONS.
    IF DB-CONDITION = ..... GO TO ...
    IF DB-CONDITION = ..... GO TO ...
    STOP RUN.
225-DATABASE-EXCEPTIONS SECTION.
    USE FOR DB-EXCEPTION ON DBM$_DUPNOTALL.
225-DATABASE.
    PERFORM 300-REPORT-DATABASE-EXCEPTIONS.
    GO TO ...
250-DATABASE-EXCEPTIONS SECTION.
    USE FOR DB-EXCEPTION ON OTHER.
250-DATABASE.
    PERFORM 300-REPORT-DATABASE-EXCEPTIONS.
    EVALUATE DB-CONDITION
             WHEN .....              GO TO ...
             WHEN .....              GO TO ...
             WHEN .....              GO TO ...
             WHEN .....              GO TO ...
             WHEN .....              GO TO ...
             WHEN .....              GO TO ...
             WHEN .....              GO TO ...
             WHEN .....              GO TO ...
             WHEN .....              GO TO ...
             WHEN OTHER              PERFORM... .
    STOP RUN.
300-REPORT-DATABASE-EXCEPTIONS.
    DISPLAY "Database Exception Condition Report".
    DISPLAY " ".
    DISPLAY "DB-CONDITION     = ",     DB-CONDITION
                                       WITH CONVERSION.
    DISPLAY "DB-CUR-REC-NAME  = ",     DB-CURRENT-RECORD-NAME.
    DISPLAY "DB-CURRENT-RECORD-ID = ", DB-CURRENT-RECORD-ID
    DISPLAY " ".
    CALL "DBM$SIGNAL".

Contents