Rational Developer for System z
COBOL for Windows, Version 7.5, Language Reference


USE statement

The formats for the USE statement are:

For general information about declaratives, see Declaratives.

LABEL declaratives are supported by IBM Enterprise COBOL for z/OS.

 

EXCEPTION/ERROR declarative

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 (EXCEPTION ERROR declarative)
Read syntax diagramSkip visual syntax diagram>>-USE--+--------+--AFTER--+----------+--+-EXCEPTION-+---------->
        '-GLOBAL-'         '-STANDARD-'  '-ERROR-----'  
 
                        .-------------.    
                        V             |    
>--PROCEDURE--+----+--+---file-name-1-+-+----------------------><
              '-ON-'  +-INPUT-----------+  
                      +-OUTPUT----------+  
                      +-I-O-------------+  
                      '-EXTEND----------'  
 
file-name-1
Valid for all files. When this option is specified, the procedure is executed only for the files named. No file-name can refer to a sort or merge file. For any given file, only one EXCEPTION/ERROR procedure can be specified; thus, file-name specification must not cause simultaneous requests for execution of more than one EXCEPTION/ERROR procedure.

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.

INPUT
Valid for all files. When this option is specified, the procedure is executed for all files opened in INPUT mode or in the process of being opened in INPUT mode that get an error.
OUTPUT
Valid for all files. When this option is specified, the procedure is executed for all files opened in OUTPUT mode or in the process of being opened in OUTPUT mode that get an error.
I-O
Valid for all direct-access files. When this option is specified, the procedure is executed for all files opened in I-O mode or in the process of being opened in I-O mode that get an error.
EXTEND
Valid for all files. When this option is specified, the procedure is executed for all files opened in EXTEND mode or in the process of being opened in EXTEND mode that get an error.

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.

A declarative procedure must not reference a nondeclarative procedure.

A PERFORM statement in a nondeclarative procedure can reference a declarative procedure; otherwise, a declarative procedure must not be referenced from a nondeclarative procedure.

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.

EXCEPTION/ERROR procedures can be used to check the file status key values whenever an input/output error occurs.

Precedence rules for nested programs

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:

  1. A file-specific declarative (that is, a declarative of the form USE AFTER ERROR ON file-name-1) within the program that contains the statement that caused the qualifying condition.
  2. A mode-specific declarative (that is, a declarative of the form USE AFTER ERROR ON INPUT) within the program that contains the statement that caused the qualifying condition.
  3. A file-specific declarative that specifies the GLOBAL phrase and is within the program directly containing the program that was last examined for a qualifying declarative.
  4. A mode-specific declarative that specifies the GLOBAL phrase and is within the program directly containing the program that was last examined for a qualifying condition.

Steps 3 and 4 are repeated until the last examined program is the outermost program, or until a qualifying declarative has been found.

LABEL declarative

The LABEL declarative (format 2 of the USE statement) is supported by IBM Enterprise COBOL for z/OS. If a LABEL declarative is encountered by COBOL for Windows, a warning message is issued and the declarative is ignored.

 

DEBUGGING declarative

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 Appendix D. 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 (Debugging declarative)
Read syntax diagramSkip visual syntax diagram                                      .------------------.    
                                      V                  |    
>>-USE--+-----+--DEBUGGING--+----+--+---procedure-name-1-+-+---><
        '-FOR-'             '-ON-'  '-ALL PROCEDURES-------'  
 
USE FOR DEBUGGING
All debugging statements must be written together in a section immediately after the DECLARATIVES header.

Except for the USE FOR DEBUGGING sentence itself, within the debugging procedure there must be no reference to any nondeclarative procedures.

procedure-name-1
Must not be defined in a debugging session.

Execution of debugging declaratives (Table 56) 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.

ALL PROCEDURES
procedure-name-1 must not be specified in any USE FOR DEBUGGING sentences. The ALL PROCEDURES phrase can be specified only once in a program. Only the procedures contained in the outermost program will trigger execution of the debugging section.

Table 56. Execution of debugging declaratives
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 every nondebugging procedure in the outermost program

After the execution of every ALTER statement in the outermost program (except ALTER statements in declarative procedures)


Terms of use | Feedback

Copyright IBM Corporation 1996, 2008.
This information center is powered by Eclipse technology. (http://www.eclipse.org)