Highlights for First-Time Users

1. The USE statement can be used to handle 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 Appendix J, Book 4, "Appendices."

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

• If the status code begins with the number "1", an AT END error has occurred.
• If the status code begins with a "2", an INVALID KEY error has occurred.
• 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.
• 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.
• 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.
• 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 five different standards specifying the values of file status codes: ANSI85, ANSI74, DG ICOBOL, VAX COBOL, and IBM DOS/VS COBOL. See Appendix J, Book 4, "Appendices" 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