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.
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 }
{ ole-object-item }
{ property-1 [ ( param-1 ... ) ]
[ :: property-2 [ ( param2 ... ) ] ] ... }
{ statement }
[END-USE]
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 ole-object-item must be USAGE HANDLE OF class-name, where class-name is defined as an ActiveX control or an OLE object in SPECIAL-NAMES.
11. Statement is an imperative statement.
12. Property-1 is the name of a property of the ActiveX control or OLE object. Property-1 must not be a write-only property.
13. Property-2 is the name of a property of the ActiveX control or OLE 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:
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 Appendix J, Book 4, "Appendices" 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. 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 procedure executes, control is returned to the next executable statement after the statement that caused the USE procedure to execute.
7. A Format 2 USE procedure executes when an object exception is "raised" during a 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. ACTIVE-X controls and OLE objects are currently the only objects that can raise exceptions. These are called OLE exceptions in Microsoft terminology.
Information about an object exception can be retrieved with the C$EXCEPINFO routine.
8. Within a Format 2 USE procedure, 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 procedure 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 index-file. See section of the User's Guide for more details.
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 Appendix G.1.1 for complete information on IBM DOS/VS COBOL compatibility mode. See Appendix J.5 for the IBM DOS/VS COBOL error codes.
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::Title::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.
More: