contents.gifindex.gifprev1.gifnext1.gif

USE Statement

The USE statement specifies procedures for Input/Output error handling.

USE is a comprehensive I/O error handling construct. The USE statement centrally locates all I/O error handling routines within the DECLARATIVES section of the PROCEDURE DIVISION. USE is a valuable supplement to the AT END and INVALID KEY I/O error handling phrases.

NOTE: This manual entry includes code examples and highlights for first-time users following the General Rules section.

General Format 

USE AFTER STANDARD {EXCEPTION} PROCEDURE ON { file...     }

                   {ERROR    }              { INPUT       }

                                            { OUTPUT      }

                                            { I-O         }

                                            { EXTEND      }

                                            { TRANSACTION }

Syntax Rules

1. File is a file described in the Data Division. It may be a sort file.

2. When used, a USE statement must immediately follow a section header in the Declaratives portion of the Procedure Division and must appear in a sentence by itself. The remainder of the section must consist of zero, one, or more paragraphs that define the exception procedure to be used.

3. ERROR and EXCEPTION are interchangeable.

4. The INPUT, OUTPUT, I-O, and EXTEND and TRANSACTION phrases may each be specified in only one USE statement in a Procedure Division.

5. A particular file may not appear in more than one USE statement in a program.

General Rules

1. The USE statement is not executed; it merely defines the conditions calling for the execution of the USE procedure. The USE procedure consists of all the paragraphs contained in the section the USE statement appears in.

2. The procedure associated with a USE statement is executed after the unsuccessful execution of an I/O operation unless an AT END or INVALID KEY phrase takes precedence. The following rules apply:

a. If file is specified, the associated procedure is executed when an unsuccessful I/O operation occurs for that file.

b. If the INPUT phrase is specified, the procedure executes when a file opened in the INPUT mode undergoes an unsuccessful I/O operation, unless that file is specified by file in another USE statement. This also applies to a file being opened for INPUT.

c. The OUTPUT, I-O, and EXTEND phrases operate as described in rule (b), except that they apply to files opened in the corresponding mode.

d. If TRANSACTION is specified, the procedure executes when an error occurs during a START TRANSACTION, COMMIT, ROLLBACK, or call to C$RECOVER. Note that the status-code will be in the TRANSACTION-STATUS variable. See Book 4, Appendix J for a list of transaction status codes.

3. After the USE procedure executes, control is returned to the next executable statement after the I/O statement that caused the USE procedure to execute.

4. Within a USE procedure, no statement may be executed that would result in the execution of a USE procedure that has been invoked but has not yet returned.

Code Examples 

PROCEDURE DIVISION.

DECLARATIVES.

NAMED-FILE-IO-ERROR-HANDLING SECTION.

   USE AFTER STANDARD ERROR PROCEDURE ON

      REPORT-FILE.

NAMED-FILE-IO-ERROR-HANDLER.

{ . . . }

IO-INPUT-ERROR-HANDLING SECTION.

   USE AFTER STANDARD ERROR PROCEDURE ON INPUT.

IO-INPUT-ERROR-HANDLER.

{ . . . }

IO-OUTPUT-ERROR-HANDLING SECTION.

   USE AFTER STANDARD ERROR PROCEDURE ON OUTPUT.

IO-OUTPUT-ERROR-HANDLER.

{ . . . }

END DECLARATIVES.

MAIN-PROGRAM SECTION.

{ . . . }

Highlights for First-Time Users

1. The USE statement is a facility dedicated exclusively to handling program file I/O errors. USE is not executed, but, rather, describes the conditions under which the contained procedures are to be executed.

2. The USE statement is located in a DECLARATIVES section in a program's PROCEDURE DIVISION. The USE statement may contain one or many error handling procedures. Each USE statement may specify a file, set of files or OPEN mode for which the enclosed procedures apply. No file name or OPEN mode (INPUT, OUTPUT, I-O, EXTEND) may be named more than once in the DECLARATIVES section of that PROCEDURE DIVISION. If an I/O error raises an ambiguity between an error handling procedure that names the file and an error handling procedure with a matching OPEN mode description, the procedure naming the file takes precedence.

3. Detecting and handling I/O errors:

Every I/O operation returns a two-digit status code that indicates the result of the operation. A status code that begins with "0" indicates a successful operation. A status code that begins with a number other than "0" indicates that the I/O operation failed. For a complete list of file status codes see Book 4, Appendix J.

When an I/O operation takes place, the file status code is set and sent back to the calling statement.

gt490000.gif If the status code begins with the number "1", an AT END error has occurred.

gt490000.gif If the status code begins with a "2", an INVALID KEY error has occurred.

gt490000.gif If the programmer has included a corresponding AT END or INVALID KEY phrase in the I/O statement (where supported), the respective clause is executed and the program, if not terminated, continues after the I/O statement that raised the error.

gt490000.gif If the status code begins with any other number (except "0"), or there is no AT END or INVALID KEY phrase, the system searches for an applicable USE statement in the DECLARATIVES section.

gt490000.gif If an applicable USE statement is found, the search stops, the applicable error handler is executed, and if the program has not been terminated, program execution continues after the I/O statement that raised the error.

gt490000.gif If no applicable USE statement is found, the runtime determines the action. Usually, a message is presented and the program halts.

For more about file status and the AT END, and INVALID KEY phrases, see sections 6.4.7 and 6.4.8, respectively.

4. The set of I/O verbs that return a status code includes:
CLOSE, DELETE, OPEN, READ, REWRITE, START, UNLOCK, WRITE.

5. There are four different standards specifying the values of file status codes: ANSI85, ANSI74, DG ICOBOL, and VAX COBOL. See Book 4, Appendix J for the complete definitions of the status codes corresponding to each standard. By default, ACUCOBOL-GT uses the ANSI85 status code standard. You can change to any of the alternate standards by changing the setting of the "FILE-STATUS-CODES" runtime configuration variable.

The ANSI85 (default) definitions of the major error classes are: 


   Status Code    Status


   0x             I/O operation succeeded


   1x             AT END ERROR


   2x             INVALID KEY ERROR


   3x             PERMANENT ERROR


   4x             LOGIC ERROR


   9x             ACUCOBOL-GT DEFINED

Note: Some errors such as 30, 98, and 9D also return additional information in the secondary or tertiary file codes. These may be retrieved with the library routine C$RERR.