Updating a record in an indexed file in sequential access mode involves the following:

1. Reading the target record
2. Verifying that the record is the one you want to change
3. Changing the record
4. Rewriting or deleting the target record

A program updates an indexed file in random access mode by rewriting or deleting the record.

Three options are available for updating indexed records:

• Sequential access mode updating
• Random access mode updating
• Dynamic access mode updating

Updating an Indexed File Sequentially

Updating indexed records in sequential acess mode involves the following:

1. Specifying ORGANIZATION IS INDEXED in the Environment Division SELECT clause
2. Specifying ACCESS MODE IS SEQUENTIAL in Environment Division SELECT clause
3. Opening the file for I-O
4. Reading records as you would a sequential file (use the READ statement with the AT END phrase)
5. Rewriting or deleting records using the INVALID KEY phrase

The READ statement makes the next logical record of an open file available to the program. It skips deleted records and sequentially reads and retrieves only valid records. When the at end condition occurs, execution of the READ statement is unsuccessful (see Chapter 7).

The REWRITE statement replaces the record just read, while the DELETE statement logically removes the record just read from the file.

Example 6-43 updates an indexed file sequentially.

Example 6-43 Updating an Indexed File Sequentially

IDENTIFICATION DIVISION. PROGRAM-ID. INDEX06. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT FLAVORS ASSIGN TO "DAIRY" ORGANIZATION IS INDEXED ACCESS MODE IS SEQUENTIAL RECORD KEY IS ICE-CREAM-MASTER-KEY ALTERNATE RECORD KEY IS ICE-CREAM-STORE-STATE WITH DUPLICATES ALTERNATE RECORD KEY IS ICE-CREAM-STORE-CODE. DATA DIVISION. FILE SECTION. FD FLAVORS. 01 ICE-CREAM-MASTER. 02 ICE-CREAM-MASTER-KEY PIC XXXX. 02 ICE-CREAM-MASTER-DATA. 03 ICE-CREAM-STORE-CODE PIC XXXXX. 03 ICE-CREAM-STORE-ADDRESS PIC X(20). 03 ICE-CREAM-STORE-CITY PIC X(20). 03 ICE-CREAM-STORE-STATE PIC XX. WORKING-STORAGE SECTION. 01 END-OF-FILE PIC X. 01 REWRITE-KEY PIC XXXXX. 01 DELETE-KEY PIC XX. 01 NEW-ADDRESS PIC X(20). PROCEDURE DIVISION. A000-BEGIN. OPEN I-O FLAVORS. DISPLAY "Which store code do you want to find?". ACCEPT REWRITE-KEY. DISPLAY "What is its new address?". ACCEPT NEW-ADDRESS. DISPLAY "Which state do you want to delete?". ACCEPT DELETE-KEY. PERFORM A100-READ-INPUT UNTIL END-OF-FILE = "Y". A020-EOJ. DISPLAY "END OF JOB". STOP RUN. A100-READ-INPUT. READ FLAVORS AT END MOVE "Y" TO END-OF-FILE. IF END-OF-FILE NOT = "Y" AND REWRITE-KEY = ICE-CREAM-STORE-CODE PERFORM A200-REWRITE-MASTER. IF END-OF-FILE NOT = "Y" AND DELETE-KEY = ICE-CREAM-STORE-STATE PERFORM A300-DELETE-MASTER. A200-REWRITE-MASTER. MOVE NEW-ADDRESS TO ICE-CREAM-STORE-ADDRESS. REWRITE ICE-CREAM-MASTER INVALID KEY DISPLAY "Bad rewrite - ABORTED" STOP RUN. A300-DELETE-MASTER. DELETE FLAVORS.

Updating an Indexed File Randomly

Updating indexed records in random access mode involves the following:

1. Specifying ORGANIZATION IS INDEXED in the Environment Division SELECT clause
2. Specifying ACCESS MODE IS RANDOM in the Environment Division SELECT clause
3. Opening the file for I-O
4. Initializing the RECORD KEY or ALTERNATE RECORD KEY data name
5. Writing, rewriting, or deleting records using the INVALID KEY phrase

You do not need to first read a record to update or delete it. If the primary or alternate key you specify allows duplicates, only the first occurrence of a record with a matching value will be updated.

Example 6-44 updates an indexed file randomly.

Example 6-44 Updating an Indexed File Randomly

IDENTIFICATION DIVISION. PROGRAM-ID. INDEX07. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT FLAVORS ASSIGN TO "DAIRY" ORGANIZATION IS INDEXED ACCESS MODE IS RANDOM RECORD KEY IS ICE-CREAM-MASTER-KEY ALTERNATE RECORD KEY IS ICE-CREAM-STORE-STATE WITH DUPLICATES ALTERNATE RECORD KEY IS ICE-CREAM-STORE-CODE. DATA DIVISION. FILE SECTION. FD FLAVORS. 01 ICE-CREAM-MASTER. 02 ICE-CREAM-MASTER-KEY PIC XXXX. 02 ICE-CREAM-MASTER-DATA. 03 ICE-CREAM-STORE-CODE PIC XXXXX. 03 ICE-CREAM-STORE-ADDRESS PIC X(20). 03 ICE-CREAM-STORE-CITY PIC X(20). 03 ICE-CREAM-STORE-STATE PIC XX. WORKING-STORAGE SECTION. 01 HOLD-ICE-CREAM-MASTER PIC X(51). 01 PROGRAM-STAT PIC X. 88 OPERATOR-STOPS-IT VALUE "1". 88 LETS-SEE-NEXT-STORE VALUE "2". 88 NO-MORE-DUPLICATES VALUE "3". PROCEDURE DIVISION. A000-BEGIN. OPEN I-O FLAVORS. PERFORM A030-RANDOM-READ UNTIL OPERATOR-STOPS-IT. A020-EOJ. DISPLAY "END OF JOB". STOP RUN. A030-RANDOM-READ. DISPLAY "Enter key". ACCEPT ICE-CREAM-MASTER-KEY. PERFORM A100-READ-INPUT-BY-PRIMARY-KEY THROUGH A100-READ-INPUT-EXIT. DISPLAY " Do you want to terminate the session?". PERFORM A040-GET-ANSWER UNTIL PROGRAM-STAT = "Y" OR "N". IF PROGRAM-STAT = "Y" MOVE "1" TO PROGRAM-STAT. A040-GET-ANSWER. DISPLAY "Please answer Y or N" ACCEPT PROGRAM-STAT. A100-READ-INPUT-BY-PRIMARY-KEY. READ FLAVORS KEY IS ICE-CREAM-MASTER-KEY INVALID KEY DISPLAY "Master does not exist - Try again" GO TO A100-READ-INPUT-EXIT. DISPLAY ICE-CREAM-MASTER. PERFORM A200-READ-BY-ALTERNATE-KEY UNTIL NO-MORE-DUPLICATES. A100-READ-INPUT-EXIT. EXIT. A200-READ-BY-ALTERNATE-KEY. DISPLAY "Do you want to see the next store in this state?". PERFORM A040-GET-ANSWER UNTIL PROGRAM-STAT = "Y" OR "N". IF PROGRAM-STAT = "Y" MOVE "2" TO PROGRAM-STAT READ FLAVORS KEY IS ICE-CREAM-STORE-STATE INVALID KEY DISPLAY "No more stores in this state" MOVE "3" TO PROGRAM-STAT. IF LETS-SEE-NEXT-STORE AND ICE-CREAM-STORE-STATE = "NY" PERFORM A500-DELETE-RANDOM-RECORD. IF LETS-SEE-NEXT-STORE AND ICE-CREAM-STORE-STATE = "NJ" MOVE "Monmouth" TO ICE-CREAM-STORE-CITY PERFORM A400-REWRITE-RANDOM-RECORD. IF LETS-SEE-NEXT-STORE AND ICE-CREAM-STORE-STATE = "CA" MOVE ICE-CREAM-MASTER TO HOLD-ICE-CREAM-MASTER PERFORM A500-DELETE-RANDOM-RECORD MOVE HOLD-ICE-CREAM-MASTER TO ICE-CREAM-MASTER MOVE "AZ" TO ICE-CREAM-STORE-STATE PERFORM A300-WRITE-RANDOM-RECORD. IF PROGRAM-STAT = "N" MOVE "3" TO PROGRAM-STAT. A300-WRITE-RANDOM-RECORD. WRITE ICE-CREAM-MASTER INVALID KEY DISPLAY "Bad write - ABORTED" STOP RUN. A400-REWRITE-RANDOM-RECORD. REWRITE ICE-CREAM-MASTER INVALID KEY DISPLAY "Bad rewrite - ABORTED" STOP RUN. A500-DELETE-RANDOM-RECORD. DELETE FLAVORS INVALID KEY DISPLAY "Bad delete - ABORTED" STOP RUN.

Updating an Indexed File Dynamically

Updating indexed records in dynamic access mode involves the following:

1. Specifying ORGANIZATION IS INDEXED in the Environment Division SELECT clause
2. Specifying ACCESS MODE IS DYNAMIC in the Environment Division SELECT clause
3. Opening the file for I-O
4. Reading the records sequentially (using the START statement to position the record pointer and then using the READ...NEXT statement) or randomly (initializing the RECORD KEY or ALTERNATE RECORD KEY data name and then reading records in any order you want using the INVALID KEY phrase) (See Example 6-44.)
5. Rewriting or deleting records using the INVALID KEY phrase

For indexed files with duplicate primary keys values, rewriting and deleting work as if the file was opened in sequential access mode. You first read the record, then update or delete the record just read.

For indexed files without duplicates allowed on the primary key, rewriting and deleting work as if the file was opened in random access mode. Specify the value of the primary key data item to indicate the target record, then update or delete that record.

In dynamic access mode, the program can switch from using random access I/O statements to sequential access I/O statements in any order without closing and reopening files.

6.6 Backing Up Your Files

Files can become unusable if either of the following situations occur:

• Your disk file becomes corrupted by a hardware error.
• Your disk file becomes corrupted with bad data.

Proper backup procedures are the key to successful recovery. You should back up your disk file at some reasonable point (daily, weekly, or monthly, depending on file activity and value of data), and save all transactions until you create a new backup. In this way, you can easily recreate your disk file from your last backup file and transaction files whenever the need arises.

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 systems), and Declarative USE procedures. The topics 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 and OpenVMS 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 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 (refer to 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. <>