HP OpenVMS Systems Documentation

HP COBOL
User Manual

The INVALID KEY clause is available for the HP 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.

     .
     .
     .
     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.
     .
     .
     .

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 HP COBOL file status values, use the FILE STATUS clause in the file description entry.

On OpenVMS, to access RMS completion codes, use the HP 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 HP 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.

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.)

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 HP 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 HP COBOL Reference Manual.

7.3.2 RMS Completion Codes (OpenVMS)

HP COBOL on OpenVMS checks for RMS completion codes after each file and record operation. If the code indicates anything other than unconditional success, HP 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.

HP 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 HP COBOL program to directly access RMS completion codes. For more information on RMS completion codes, refer to the HP 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.

   .
   .
   .
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.                                      <>