USE Statement

The USE statement specifies procedures for handling Input/Output errors and other errors. USE is a comprehensive error handling construct. The USE statement locates all error routines centrally within the DECLARATIVES section of the PROCEDURE DIVISION when used to specify I/O error handling routines. 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.

Format 1

USE AFTER STANDARD {EXCEPTION} PROCEDURE ON { {file}...   }
                   {ERROR    }              { INPUT       }
                                            { OUTPUT      }
                                            { I-O         }
                                            { EXTEND      }
                                            { TRANSACTION }

Format 2

USE AFTER STANDARD {EXCEPTION} PROCEDURE ON OBJECT
                   {ERROR    }

Format 3

USE FOR REPORTING ON {index-file} ...

Format 4

USE AFTER STANDARD ERROR PROCEDURE ON file-name GIVING
       data-name-1  [ data-name-2 ]

Format 5

USE { active-x-control-item }
    { com-object-item  }
    { property-1 [ ( param-1 ... ) ]
      [ :: property-2 [ ( param2 ... ) ] ] ... }
    { statement }
[END-USE]

Format 6

USE AT PROGRAM {START}
               {END  }

Syntax Rules

  1. file is a file described in the Data Division. It may be a sort file.
  2. index-file is a file described in the Data Division. It must be an indexed file.
  3. data-name-1 is an eight-byte data item of the type PICTURE 9(8) USAGE DISPLAY. A compile-time error message is generated if data-name-1 is not of that type.
  4. data-name-2 may be of any type but must be at least as long as the file buffer. A compile-time error message is generated if this is not the case.
  5. 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.
  6. ERROR and EXCEPTION are interchangeable.
  7. The INPUT, OUTPUT, I-O, and EXTEND and TRANSACTION phrases may each be specified in only one USE statement in a Procedure Division.
  8. A particular file may not appear in more than one Format 1 USE statement in a program.
  9. A particular index-file may not appear in more than one Format 3 USE statement in a program.
  10. Active-x-control-item and com-object-item must be USAGE HANDLE OF class-name, where class-name is defined as an ActiveX control or an COM object in SPECIAL-NAMES.
  11. statement is an imperative statement.
  12. property-1 is the name of a property of the ActiveX control or COM object. property-1 must not be a write-only property.
  13. property-2 is the name of a property of the ActiveX control or COM object which is the value of property-1. property-2 must not be a write-only property.
  14. param-1 and param-2 are literals, data items, or numeric expressions.

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 Format 1 USE statement is executed after the unsuccessful execution of an I/O operation unless an AT END or INVALID KEY phrase takes precedence. It also executes during an I/O operation when a duplicate key error is detected for a file open for BULK-ADDITION. The following rules apply:
    1. If file is specified, the associated procedure is executed when an unsuccessful I/O operation occurs for that file.
    2. If the INPUT phrase is specified, the procedure executes when the OPEN operation is unsuccessful for a file being opened in INPUT mode, unless that file is specified by file in another USE statement. This also applies to a file being opened for INPUT.
    3. The OUTPUT, I-O, and EXTEND phrases operate as described in rule b), except that they apply to files opened in the corresponding mode.
    4. 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.
  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. If the USE procedure executed during a file operation, the control returns to that file operation instead.
  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.
  5. The procedure associated with a Format 2 USE statement is executed after an object exception occurs.
  6. After the Format 2 USE statement executes, control is returned to the next executable statement after the statement that caused the USE procedure to execute.
  7. A Format 2 USE statement executes when an object exception is "raised" during a CREATE, DISPLAY, MODIFY, INQUIRE or calls to C$GETEVENTDATA, C$SETEVENTDATA, C$GETEVENTPARAM or C$SETEVENTPARAM.

    An object exception can either be raised by the object itself or by the runtime to indicate that an error has occurred. ActiveX controls and COM objects are currently the only objects that can raise exceptions. These are called COM exceptions in Microsoft terminology.

    Information about an object exception can be retrieved with the C$EXCEPINFO routine.

  8. Within a Format 2 USE statement, no statement can be executed that would result in the execution of a USE procedure that has been invoked but has not yet returned.
  9. A Format 3 USE statement executes at periodic times for files opened with the BULK-ADDITION phrase. The purpose of this procedure is to report to the user the progress of writing keys for a large number of records written to indexfile.
  10. When a Format 1 USE procedure executes due to a duplicate key error for a file open with BULK-ADDITION, no file I/O statements may be executed. This also applies to Format 3 USE procedures. In addition, no run units may be started or stopped, and the program containing the declarative may not perform an EXIT PROGRAM.
  11. A Format 4 USE procedure is valid only when the -Cv option is in effect. When an error handler introduced by this statement is invoked, the runtime puts special error codes into the eight-byte data item data-item-1. See IBM DOS/VS COBOL Conversions, in Transitioning to ACUCOBOL-GT for complete information on DOS/VS COBOL compatibility mode.
  12. If data-name-2 is present, when the error handler is invoked, it will also load data-name-2 with the contents of the file buffer. ACUCOBOL-GT always loads data-name-2, and if the data-item is larger than the file buffer, the excess bytes at the right end are left unchanged.
  13. The Format 5 USE verb sets up a context for more efficient coding and processing of MODIFY and INQUIRE statements that operate on ActiveX controls or objects. It allows you to execute a series of MODIFY and INQUIRE statements on a specified object without respecifying the object. For example, to change a number of different properties on a single object, place the MODIFY statement within the USE statement, referring to the object once instead of referring to it in each MODIFY clause. 
    USE MyChart Legend::Font
MODIFY    ^Size = 10
          ^Name = "Courier"
          ^Bold = 1
END-USE
  14. param-1 is the first parameter passed when getting the value of property-1.
  15. param-2 is the first parameter passed when getting the value of property-2.
  16. Runtime errors announced as Use of a LINKAGE data item not passed by the caller and Passed USING item smaller than corresponding LINKAGE item belong to the class of intermediate runtime errors that, upon occurrence, call installed error procedures.
  17. When placed in a program's Declarative section, a Format 6 USE statement creates a START or END procedure for the program. Each program may contain no more than one START and one END procedure. Every program in a run unit may contain such procedures.
    1. A START procedure executes immediately before the first normal COBOL statement in the Procedure Division when the program is in its initial state. The START procedure executes only once regardless of the number of times the program is entered, until the program is returned to its initial state (e.g. via CANCEL). A START procedure executes regardless of which entry point is used to start the program when a program contains multiple entry points (see the ENTRY statement).
    2. An END procedure executes immediately before a program is placed into its initial state or it is about to leave memory, providing the program has been entered at least once. An END procedure executes before open files are closed as part of the shutdown process.
    3. You can call the C$EXITINFO library routine from an END procedure to obtain information about the program exit. For example, you can determine if the exit is the result of a STOP RUN or a fatal error. Refer to Appendix I in ACUCOBOL-GT Appendices for detailed information about this library routine.
    4. It is normal for an END procedure to execute when the program that contains it is inactive. For example, if a program is canceled, its END procedure will execute when the program is otherwise inactive. For this reason, an END procedure should not reference data passed to the program through Linkage. This data will not be defined in many cases.
    5. END procedures are executed during abnormal shutdown when possible. However, certain operating system errors (such as a fatal memory error) cannot be caught in some operating environments, and in these cases the END procedures will not be able to execute. If a fatal error occurs during an END procedure, that procedure stops, but other unprocessed END procedures execute where possible.
    6. When multiple END procedures execute (e.g. STOP RUN when several programs are in memory), the order of their execution is arbitrary.

Code Example

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

    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 AT END and INVALID KEY Phrases.

  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. 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.
Parent topic: Procedure Division Statements