Many types of exception conditions can occur when a program processes a file; not all of them are errors. The three categories of exception conditions are as follows:

• AT END condition---This is a normal condition when you access a file sequentially. However, if your program tries to read the file any time after having read the last logical record in the file, and there is no applicable Declarative USE procedure or AT END phrase, the program abnormally terminates when the next READ statement executes.
• Invalid key condition---When you process relative and indexed files, the invalid key condition is a normal condition if you plan for it with a Declarative USE procedure or INVALID KEY phrase. It is an abnormal condition that causes your program to terminate if there is no applicable Declarative USE procedure or INVALID KEY phrase.
• All other conditions---These can also be either normal conditions (if you plan for them with Declarative USE procedures) or abnormal conditions that cause your program to terminate.

Planning for exception conditions effectively increases program and programmer efficiency. A program with exception handling routines is more flexible than a program without them. Exception handling routines minimize operator intervention and often reduce or eliminate the time you need to spend debugging and rerunning your program.

This chapter introduces you to the tools you need to execute exception handling routines for sequential, relative, and indexed files as a normal part of your program. These tools are the AT END phrase, the INVALID KEY phrase, file status values, RMS completion codes (on OpenVMS Alpha systems), and Declarative USE procedures. The sections that follow explain how to use these tools in your programs:

• Planning for the AT END condition ( Section 7.1)
• Planning for the Invalid Key condition ( Section 7.2)
• Using file status values
• On OpenVMS, using RMS completion codes ( Section 7.3) <>
• Using Declarative USE procedures ( Section 7.4)

Compaq COBOL provides you the option of testing for this condition with the AT END phrase of the READ statement (for sequential, relative, and indexed files) and the AT END phrase of the ACCEPT statement.

Programs often read sequential files from beginning to end. They can produce reports from the information in the file or even update it. However, the program must be able to detect the end of the file, so that it can continue normal processing at that point. If the program does not test for this condition when it occurs, and if no applicable Declarative USE procedure exists (see Section 7.4), the program terminates abnormally. The program must detect when no more data is available from the file so that it can perform its normal end-of-job processing and then close the file.

Example 7-1 shows the use of the AT END phrase with the READ statement for sequential, relative, and indexed files.

Example 7-1 Handling the AT END Condition

READ SEQUENTIAL-FILE AT END PERFORM A600-TOTAL-ROUTINES PERFORM A610-VERIFY-TOTALS-ROUTINES MOVE "Y" TO END-OF-FILE. READ RELATIVE-FILE NEXT RECORD AT END PERFORM A700-CLEAN-UP-ROUTINES CLOSE RELATIVE-FILE STOP RUN. READ INDEXED-FILE NEXT RECORD AT END DISPLAY "End of file" DISPLAY "Do you want to continue?" ACCEPT REPLY PERFORM A700-CLEAN-UP-ROUTINES.

7.2 Planning for the Invalid Key Condition

The INVALID KEY clause is available for the Compaq COBOL DELETE, READ, REWRITE, START, and WRITE statements. (It does not apply to the READ NEXT statement.) An invalid key condition occurs whenever the I/O system cannot complete a DELETE, READ, REWRITE, START, or WRITE statement. When the condition occurs, execution of the statement that recognized it is unsuccessful, and the file is not affected.

For example, relative and indexed files use keys to access (retrieve or update) records. The program specifying random access must initialize a key before executing a DELETE, READ, REWRITE, START, or WRITE statement. If the key does not result in the successful execution of any one of these statements, the invalid key condition exists. This condition is fatal to the program, if the program does not check for the condition when it occurs and if no applicable Declarative USE procedure exists (see Section 7.4).

The invalid key condition, although fatal if not planned for, can be to your advantage when used properly. You can, as shown in Example 7-2, read through an indexed file for all records with a specific duplicate key and produce a report from the information in those records. You can also plan for an invalid key condition on the first attempt to find a record with a specified key value that is not present in the file. In this case, planning for the invalid key condition allows the program to continue its normal processing. You can also plan for the AT END condition when you have read and tested for the last of the duplicate records in the file, or when you receive the AT END condition for a subsequent read operation, indicating that no more records exist in the file.

Example 7-2 Handling the Invalid Key Condition

. . . MOVE "SMITH" TO LAST-NAME TEST-LAST-NAME. MOVE "Y" TO ANY-MORE-DUPLICATES. PERFORM A500-READ-DUPLICATES UNTIL ANY-MORE-DUPLICATES = "N". . . . STOP RUN. A500-READ-DUPLICATES. READ INDEXED-FILE RECORD INTO HOLD-RECORD KEY IS LAST-NAME INVALID KEY MOVE "N" TO ANY-MORE-DUPLICATES DISPLAY "Name not in file!" NOT INVALID KEY PERFORM A510-READ-NEXT-DUPLICATES UNTIL ANY-MORE-DUPLICATES = "N" END-READ. A510-READ-NEXT-DUPLICATES. READ INDEXED-FILE NEXT RECORD AT END MOVE "N" TO ANY-MORE-DUPLICATES NOT AT END PERFORM A520-VALIDATE END-READ. IF ANY-MORE-DUPLICATES = "Y" PERFORM A700-PRINT. A520-VALIDATE. IF LAST-NAME NOT EQUAL TEST-LAST-NAME MOVE "N" TO ANY-MORE-DUPLICATES. END READ. A700-PRINT. . . .

7.3 Using File Status Values and OpenVMS RMS Completion Codes

Your program can check for the specific cause of the failure of a file operation by checking for specific file status values in its exception handling routines. To obtain Compaq COBOL file status values, use the FILE STATUS clause in the file description entry.

On OpenVMS, to access RMS completion codes, use the Compaq COBOL special registers RMS-STS and RMS-STV, or RMS-CURRENT-STS and RMS-CURRENT-STV. <>

7.3.1 File Status Values

The run-time execution of any Compaq COBOL file processing statement results in a two-digit file status value that reports the success or failure of the COBOL statement. To access this file status value, you must specify the FILE STATUS clause in the file description entry, as shown in Example 7-3.

Example 7-3 Defining a File Status for a File

DATA DIVISION. FILE SECTION. FD INDEXED-FILE FILE STATUS IS INDEXED-FILE-STATUS. 01 INDEXED-RECORD PIC X(50). WORKING-STORAGE SECTION. 01 INDEXED-FILE-STATUS PIC XX. 01 ANSWER PIC X.

The program can access this file status variable, INDEXED-FILE-STATUS, anywhere in the Procedure Division, and depending on its value, take a specific course of action without terminating the program. Notice that in Example 7-4 (in paragraph A900-EXCEPTION-HANDLING-ROUTINE), the file status that was defined in Example 7-3 is used. However, not all statements allow you to access the file status value as part of the statement. Your program has two options:

• Build an error recovery routine into the statement. The relative and indexed file processing statements that allow you to do this within the INVALID KEY phrase are DELETE, READ, REWRITE, START, and WRITE (that is, all the record I-O verbs except READ NEXT). See Example 7-4.
• Define a Declarative USE procedure to handle the condition. This option is available for all file organizations and their I/O statements. (See Example 7-6, Example 7-7, and Example 7-8.)

Example 7-4 Using the File Status Value in an Exception Handling Routine

PROCEDURE DIVISION. A000-BEGIN. . . . DELETE INDEXED-FILE INVALID KEY MOVE "Bad DELETE" to BAD-VERB-ID PERFORM A900-EXCEPTION-HANDLING-ROUTINE. . . . READ INDEXED-FILE NEXT RECORD AT END MOVE "Bad READ" TO BAD-VERB-ID PERFORM A900-EXCEPTION-HANDLING-ROUTINE. . . . REWRITE INDEXED-RECORD INVALID KEY MOVE "Bad REWRITE" TO BAD-VERB-ID PERFORM A900-EXCEPTION-HANDLING-ROUTINE. . . . START INDEXED-FILE INVALID KEY MOVE "Bad START" TO BAD-VERB-ID PERFORM A900-EXCEPTION-HANDLING-ROUTINE. . . . WRITE INDEXED-RECORD INVALID KEY MOVE "Bad WRITE" TO BAD-VERB-ID PERFORM A900-EXCEPTION-HANDLING-ROUTINE. . . . A900-EXCEPTION-HANDLING-ROUTINE. DISPLAY BAD-VERB-ID " - File Status Value = " INDEXED-FILE-STATUS. PERFORM A905-GET-ANSWER UNTIL ANSWER = "Y" OR "N". IF ANSWER = "N" STOP RUN. A905-GET-ANSWER. DISPLAY "Do you want to continue?" DISPLAY "Please answer Y or N" ACCEPT ANSWER.

See Soft Record Locks for information about inspecting variables with soft record locks and Declarative USE procedures.

Each file processing statement described in the Procedure Division section of the Compaq COBOL Reference Manual contains a specific list of file status values in its Technical Notes section. In addition, all file status values are listed in an appendix in the Compaq COBOL Reference Manual.

7.3.2 RMS Completion Codes (OpenVMS)

Compaq COBOL on OpenVMS Alpha checks for RMS completion codes after each file and record operation. If the code indicates anything other than unconditional success, Compaq COBOL maps the RMS completion code to a file status value. However, not all RMS completion codes map to distinct file status values. Many RMS completion codes map to File Status 30, a COBOL code for errors that have no specific file status value.

Compaq COBOL provides the following six special exception condition registers, four of which are shown in Example 7-5:

• RMS-STS
• RMS-STV
• RMS-FILENAME
• RMS-CURRENT-STS
• RMS-CURRENT-STV
• RMS-CURRENT-FILENAME

These special registers supplement the file status values already available and allow the Compaq COBOL program to directly access RMS completion codes. For more information on RMS completion codes, refer to the Compaq COBOL Reference Manual and the OpenVMS Record Management Services Reference Manual.

You do not define these special registers in your program. As special registers, they are available whenever and wherever you need to use them in the Procedure Division. RMS-CURRENT-STS contains the RMS completion codes for the most recent file or record operation for any file. RMS-CURRENT-FILENAME contains the name of the current file by which it is known to the system, which can be the full file specification (directory, device, file name, and extension). RMS-CURRENT-STV contains other relevant information (see the OpenVMS System Messages and Recovery Procedures Reference Manual, an archived manual that is available on the OpenVMS Documentation CD-ROM.). When you access these three special registers, you must not qualify your reference to them. However, if you define more than one file in the program and intend to access RMS-STS, RMS-STV, and RMS-FILENAME, you must qualify your references to them by using the internal COBOL program's file name for the file that you intend to reference.

Notice the use of the WITH CONVERSION phrase of the DISPLAY statement in Example 7-5. This converts the PIC S9(9) COMP contents of the RMS Special Registers from binary to decimal digits for terminal display.

Example 7-5 Referencing RMS-STS, RMS-STV, RMS-CURRENT-STS, and RMS-CURRENT-STV Codes (OpenVMS)

. . . DATA DIVISION. FILE SECTION. FD FILE-1. 01 RECORD-1 PIC X(50). FD FILE-2. 01 RECORD-2 PIC X(50). WORKING-STORAGE SECTION. 01 ANSWER PIC X. 01 STS PIC S9(9) COMP. 01 STV PIC S9(9) COMP. PROCEDURE DIVISION. A000-BEGIN. . . WRITE RECORD-1 INVALID KEY PERFORM A901-REPORT-FILE1-STATUS. * * The following PERFORM statement displays the RMS completion * codes resulting from the above WRITE statement for FILE-1. * PERFORM A903-REPORT-RMS-CURRENT-STATUS. . . . WRITE RECORD-2 INVALID KEY PERFORM A902-REPORT-FILE2-STATUS. * * The following PERFORM statement displays the RMS completion * codes resulting from the above WRITE statement for FILE-2. * PERFORM A903-REPORT-RMS-CURRENT-STATUS. . . . * * The following PERFORM statement moves the RMS completion codes * resulting from the above WRITE statement for FILE-2 to data * fields that are explicitly defined within your program. * PERFORM A904-MOVE-RMS-STS-STV. . . . A901-REPORT-FILE1-STATUS. ******************************************* * DISPLAY "RMS-STS = " RMS-STS OF FILE-1 WITH CONVERSION. DISPLAY "RMS-STV = " RMS-STV OF FILE-1 WITH CONVERSION. DISPLAY "RMS-FILENAME = " RMS-FILENAME OF FILE-1. * ******************************************* PERFORM A999-GET-ANSWER UNTIL ANSWER = "Y" OR "N". IF ANSWER = "N" STOP RUN. A902-REPORT-FILE2-STATUS. ******************************************* * DISPLAY "RMS-STS = " RMS-STS OF FILE-2 WITH CONVERSION. DISPLAY "RMS-STV = " RMS-STV OF FILE-2 WITH CONVERSION. DISPLAY "RMS-FILENAME = " RMS-FILENAME OF FILE-2. * ******************************************* PERFORM A999-GET-ANSWER UNTIL ANSWER = "Y" OR "N". IF ANSWER = "N" STOP RUN. A903-REPORT-RMS-CURRENT-STATUS. ******************************************* * DISPLAY "RMS-CURRENT-STS = " RMS-CURRENT-STS WITH CONVERSION. DISPLAY "RMS-CURRENT-STV = " RMS-CURRENT-STV WITH CONVERSION. DISPLAY "RMS-CURRENT-FILENAME = " RMS-CURRENT-FILENAME. * ******************************************* PERFORM A999-GET-ANSWER UNTIL ANSWER = "Y" OR "N". IF ANSWER = "N" STOP RUN. A904-MOVE-RMS-STS-STV. ******************************************* * MOVE RMS-STS OF FILE-1 TO STS. MOVE RMS-STV OF FILE-1 TO STV. * ******************************************* PERFORM A999-GET-ANSWER UNTIL ANSWER = "Y" OR "N". IF ANSWER = "N" STOP RUN. A999-GET-ANSWER. DISPLAY "Do you want to continue?" DISPLAY "Please answer Y or N" ACCEPT ANSWER. <>

7.4 Using Declarative USE Procedures

An applicable Declarative USE procedure executes whenever an I/O statement results in an exception condition (a file status value that does not begin with a zero (0)) and the I/O statement does not contain an AT END or INVALID KEY phrase. The AT END and INVALID KEY phrases take precedence over a Declarative USE procedure, but only for the I/O statement that includes the clause. For example, the AT END phrase takes effect only with File Status 10 and the INVALID KEY phrase takes effect only with File Status 23. Therefore you can have specific I/O statement exception condition handling for a file and also include a Declarative USE procedure for general exception handling.

A Declarative USE procedure is a set of one or more special-purpose sections at the beginning of the Procedure Division. As shown in Example 7-6, the key word DECLARATIVES precedes the first of these sections, and the key words END DECLARATIVES follow the last.

Example 7-6 The Declaratives Skeleton

PROCEDURE DIVISION. DECLARATIVES. . . . END DECLARATIVES. MAIN-BODY SECTION. BEGIN. . . .

As shown in Example 7-7, a Declarative procedure consists of a section header, followed, in order, by a USE statement and one or more paragraphs.

Example 7-7 A Declarative USE Procedure Skeleton

. . . PROCEDURE DIVISION. DECLARATIVES. D0-00-FILE-A-PROBLEM SECTION. USE AFTER STANDARD ERROR PROCEDURE ON FILE-A. D0-01-FILE-A-PROBLEM. . . . D0-02-FILE-A-PROBLEM. . . . D0-03-FILE-A-PROBLEM. . . . END DECLARATIVES. MAIN-BODY SECTION. BEGIN. . . .

Declarative USE procedures can be either ordinary or global. Ordinary Declarative USE procedures have a limited scope; you can use them only in programs where they are originally introduced. Global Declarative USE procedures have a wider scope; you can use them in programs that introduce them as well as in programs that are contained within the introducing program.

In Compaq COBOL Declarative procedures, the conditions in the USE statements indicate when they execute. There are five conditions. One USE statement can have only one condition; therefore, if you need all five conditions in one program, you must use five separate USE procedures. These procedures and their corresponding conditions are as follows:

• File name---You can define a file name Declarative USE procedure for each file name. This procedure takes precedence over the next four procedures. It executes for any unsuccessful exception condition. (One USE statement can specify multiple file names.)
• INPUT---You can define only one INPUT Declarative USE procedure for each program. This procedure executes for any unsuccessful exception condition if: (1) the file is open for INPUT and (2) a file name Declarative USE procedure does not exist for that file.
• OUTPUT---You can define only one OUTPUT Declarative USE procedure for each program. This procedure executes for any unsuccessful exception condition if: (1) the file is open for OUTPUT and (2) a file name Declarative USE procedure does not exist for that file.
• INPUT-OUTPUT---You can define only one INPUT-OUTPUT Declarative USE procedure for each program. This procedure executes for any unsuccessful exception condition if: (1) the file is open for INPUT-OUTPUT (I-O) and (2) a file name Declarative USE procedure does not exist for that file.
• EXTEND---You can define only one EXTEND Declarative USE procedure for each program. This procedure executes for any unsuccessful exception condition if: (1) the file is open for EXTEND and (2) a file name Declarative USE procedure does not exist for that file.

Note that the USE statement itself does not execute; it defines the condition that causes the Declarative procedure to execute. Refer to the Compaq COBOL Reference Manual for more information about specifying Declarative procedures with the USE statement.

Example 7-8 shows you how to include a USE procedure for each of the conditions in your program. The example also contains explanatory comments for each.

Example 7-8 Five Types of Declarative USE Procedures

. . . PROCEDURE DIVISION. DECLARATIVES. ******************************************************** D1-00-FILE-A-PROBLEM SECTION. USE AFTER STANDARD ERROR PROCEDURE ON FILE-A. * * * If any file-access statement for FILE-A results in an * error, D1-00-FILE-A-PROBLEM executes. * * D1-01-FILE-A-PROBLEM. PERFORM D9-00-REPORT-FILE-STATUS. . . . ******************************************************** D2-00-FILE-INPUT-PROBLEM SECTION. USE AFTER STANDARD EXCEPTION PROCEDURE ON INPUT. * * * If an error occurs for any file open * in the INPUT mode except FILE-A, * D2-00-FILE-INPUT-PROBLEM executes. * * D2-01-FILE-INPUT-PROBLEM. PERFORM D9-00-REPORT-FILE-STATUS. . . . ******************************************************** D3-00-FILE-OUTPUT-PROBLEM SECTION. USE AFTER STANDARD EXCEPTION PROCEDURE ON OUTPUT. * * * If an error occurs for any file open * in the OUTPUT mode except FILE-A, * D3-00-FILE-OUTPUT-PROBLEM executes. * * D3-01-FILE-OUTPUT-PROBLEM. PERFORM D9-00-REPORT-FILE-STATUS. . . . ******************************************************** D4-00-FILE-I-O-PROBLEM SECTION. USE AFTER STANDARD EXCEPTION PROCEDURE ON I-O. * * * If an error occurs for any file open * in the INPUT-OUTPUT mode except FILE-A, * D4-00-FILE-I-O-PROBLEM executes. * * * D4-01-FILE-I-O-PROBLEM. PERFORM D9-00-REPORT-FILE-STATUS. . . . ******************************************************** D5-00-FILE-EXTEND-PROBLEM SECTION. USE AFTER STANDARD EXCEPTION PROCEDURE ON EXTEND. * * * If an error occurs for any file open * in the EXTEND mode except FILE-A, * D5-00-FILE-EXTEND-PROBLEM executes. * * D5-01-FILE-EXTEND-PROBLEM. PERFORM D9-00-REPORT-FILE-STATUS. . . . D9-00-REPORT-FILE-STATUS. . . . END DECLARATIVES. ******************************************************** A000-BEGIN SECTION. BEGIN. . . .