The formats for the USE statement are:
For general information about declaratives, see Declaratives.
The EXCEPTION/ERROR declarative specifies procedures for input/output exception or error handling that are to be executed in addition to the standard system procedures.
The words EXCEPTION and ERROR are synonymous and can be used interchangeably.
Format 1: USE statement for EXCEPTION/ERROR declarative >>-USE--+--------+--AFTER--+----------+--+-EXCEPTION-+----------> '-GLOBAL-' '-STANDARD-' '-ERROR-----' .-------------. V | >--PROCEDURE--+----+--+---file-name-1-+-+---------------------->< '-ON-' +-INPUT-----------+ +-OUTPUT----------+ +-I-O-------------+ '-EXTEND----------'
A USE AFTER EXCEPTION/ERROR declarative statement specifying the name of a file takes precedence over a declarative statement specifying the open mode of the file.
The EXCEPTION/ERROR procedure is executed:
After execution of the EXCEPTION/ERROR procedure, control is returned to the invoking routine in the input/output control system. If the input/output status value does not indicate a critical input/output error, the input/output control system returns control to the next executable statement following the input/output statement whose execution caused the exception.
An applicable EXCEPTION/ERROR procedure is activated when an input/output error occurs during execution of a READ, WRITE, REWRITE, START, OPEN, CLOSE, or DELETE statement. To determine what conditions are errors, see Common processing facilities.
The following rules apply to declarative procedures:
You can include a statement that executes a previously called USE procedure that is still in control. However, to avoid an infinite loop, you must be sure that there is an eventual exit at the bottom.
You cannot use a GOBACK statement or a STOP RUN statement when an EXCEPTION/ERROR declarative is active due to a QSAM abend for a READ, WRITE, or REWRITE statement. You cannot use an EXIT PROGRAM statement in a non-nested subprogram when an EXCEPTION/ERROR declarative is active due to a QSAM abend for a READ, WRITE, or REWRITE statement. When a QSAM abend occurs during a READ, WRITE, or REWRITE statement, the file status code can be "34" or "90".
You cannot use a GOBACK statement or an EXIT PROGRAM statement while a declarative is active in a nested program. You cannot use a GOBACK statement or an EXIT METHOD statement while a declarative is active in a method.
EXCEPTION/ERROR procedures can be used to check the file status key values whenever an input/output error occurs.
Special precedence rules are followed when programs are contained within other programs. In applying these rules, only the first qualifying declarative is selected for execution. The order of precedence for selecting a declarative is:
Steps 3 and 4 are repeated until the last examined program is the outermost program, or until a qualifying declarative has been found.
The LABEL declarative provides user label-handling procedures.
Format 2: USE statement for LABEL declarative >>-USE--+--------+--AFTER--+----------+--+-----------+----------> '-GLOBAL-' '-STANDARD-' +-BEGINNING-+ '-ENDING----' .-------------. V | >--+------+--LABEL PROCEDURE--+----+--+---file-name-1-+-+------>< +-FILE-+ '-ON-' +-INPUT-----------+ +-REEL-+ +-OUTPUT----------+ '-UNIT-' +-I-O-------------+ '-EXTEND----------'
The labels must be listed as data names in the LABEL RECORDS clause in the file description entry for the file, and must be described as level-01 data items subordinate to the file entry.
If neither BEGINNING nor ENDING is specified, the designated procedures are executed for both beginning and ending labels.
If FILE, REEL, or UNIT is not included, the designated procedures are executed both for REEL or UNIT, whichever is appropriate, and for FILE labels.
The REEL option is not applicable to direct-access files.
The UNIT phrase is not applicable to files in the random access mode, because only FILE labels are processed in this mode.
file-name-1 must not represent a sort file.
If the file-name-1 option is used, the file description entry for file-name must not specify a LABEL RECORDS ARE OMITTED clause.
When the INPUT, OUTPUT, or I-O options are specified, user label procedures are executed as follows:
If the INPUT, OUTPUT, or I-O phrase is specified, and an input, output, or I-O file, respectively, is described with a LABEL RECORDS ARE OMITTED clause, the USE procedures do not apply. The standard system procedures are performed:
Within the procedures of a USE declarative in which the USE sentence specifies an option other than file-name, references to common label items need not be qualified by a file-name. A common label item is an elementary data item that appears in every label record of the program, but does not appear in any data records of this program. Such items must have identical descriptions and positions within each label record.
Within a declarative section there must be no reference to any nondeclarative procedure. Conversely, in the nondeclarative portion there must be no reference to procedure-names that appear in the declarative section, except that the PERFORM statement can refer to a USE procedure, or to procedures associated with it.
The exit from a declarative section is inserted by the compiler following the last statement in the section. All logical processing paths within the section must lead to the exit point.
There is one exception: A special exit can be specified by the statement GO TO MORE-LABELS. When an exit is made from a declarative section by means of this statement, the system will do one of the following:
If a GO TO MORE-LABELS statement is not executed for a user label, the declarative section is not reentered to check or create any immediately succeeding user labels.
Debugging sections are permitted only in the outermost program; they are not valid in nested programs. Debugging sections are never triggered by procedures contained in nested programs.
Debugging sections are not permitted in:
The WITH DEBUGGING MODE clause of the SOURCE-COMPUTER paragraph activates all debugging sections and lines that have been compiled into the object code. See Source language debugging for additional details.
When the debugging mode is suppressed by not specifying the WITH DEBUGGING MODE clause, all USE FOR DEBUGGING declarative procedures and all debugging lines are inhibited.
Automatic execution of a debugging section is not caused by a statement that appears in a debugging section.
Format 3: USE statement for DEBUGGING declarative .------------------. V | >>-USE--+-----+--DEBUGGING--+----+--+---procedure-name-1-+-+--->< '-FOR-' '-ON-' '-ALL PROCEDURES-------'
Except for the USE FOR DEBUGGING sentence itself, within the debugging procedure there must be no reference to any nondeclarative procedures.
Table 1 shows, for each valid option, the points during execution when the USE FOR DEBUGGING procedures are executed.
Any given procedure-name can appear in only one USE FOR DEBUGGING sentence, and only once in that sentence. All procedures must appear in the outermost program.
| USE FOR DEBUGGING operand | Upon execution of the following, the USE FOR DEBUGGING procedures are executed immediately |
|---|---|
| procedure-name-1 | Before each execution of the named procedure
After the execution of an ALTER statement referring to the named procedure |
| ALL PROCEDURES | Before each execution of each nondebugging
procedure in the outermost program
After the execution of each ALTER statement in the outermost program (except ALTER statements in declarative procedures) |