HP 3000 Manuals

HP COBOL II/XL Reference Manual

USE Statement 

The USE statement specifies procedures for input-output error handling,
user label processing, and debugging.  These procedures are an addition
to the standard procedures provided by the input-output control system. 

Syntax 

There are three general formats of the USE statement:


            

For a description of format 3, refer to Chapter 12 , "Debug Module".

Parameters 

file-name-1 and       the names of files to be acted upon by the
file-name-2           appropriate procedures when an input-output error
                      has occurred, or when a user label is to be
                      processed.  These names must not name sort-merge
                      files.

ERROR and EXCEPTION   synonymous and may be used interchangeably.

Description 

The rules below apply to both formats of the USE statement.

A USE statement, when specified, must immediately follow a section header
in the declaratives section and must be followed by a period and a space.
The remainder of the section must consist of zero, one, or more
procedural paragraphs that define the procedures to be used.  These
paragraphs make up the procedures that are executed when required.  The
USE statement itself is never executed.  It merely defines the conditions
calling for the execution of the USE procedures. 

Within a USE procedure, there must not be any reference to any
nondeclarative procedures.  Conversely, in the nondeclarative portion
there must not be any reference to procedure names in the declarative
portion, except that PERFORM statements may refer to a USE statement or
to the procedures associated with such a USE statement.

Within a USE procedure, no statement can be executed that would cause the
execution of a USE procedure that has been previously invoked, but has
not yet returned control to the invoking routine.

In a USE statement, the files affected by the procedures related to the
USE statement may be explicitly or implicitly specified.

They are explicitly specified by using their names in the USE statement
itself.

To implicitly specify a file, the words, INPUT, OUTPUT, I-O, and EXTEND
are used.  For example, if a USE statement uses the word INPUT, any file
opened for input, as opposed to output or input-output, is implicitly
specified in that USE statement.

The same file name may appear in different USE statements.  However, the
appearance of a file name in a USE statement may not cause the
simultaneous request for execution of more than one USE procedure.

USE Statement - Format 1 

The first format of the USE statement is for error handling procedures.

The file implicitly or explicitly referenced in a format-1 USE statement
need not have the same organization or access.

When a format 1 USE statement is specified for a file, and an input or
output error occurs, the input-output system performs any applicable USE
procedures either after completing the standard input-output error
routine, or upon recognition of the INVALID KEY or AT END condition.

If a  GLOBAL phrase is specified in the declarative statement, the USE
procedure can be invoked from any program contained within the program in
which the declarative statement is defined.

When an INVALID KEY or AT END condition occurs, the appropriate USE
procedures are executed provided only that an AT END or INVALID KEY
phrase has not been specified in the input-output statement that
generated the error.

USE Statement - Format 2 

This format of the USE statement is an HP extension to the ANSI COBOL
standard.

The format 2 USE statement is for reading and writing user labels on a
file, starting immediately after the operating system label at the
beginning of a file. 

There may be as many as eight user labels following an operating system
label, and each label may consist of 80 characters.

When user labels are read by your program, only one location is made
available for them in memory.  Thus, only one may be read at a time,
requiring only a single description of a label record data item per file.

Whether a file is explicitly or implicitly referenced in a USE statement,
that statement does not apply and is ignored if the referenced file
includes the LABEL RECORDS ARE OMITTED clause in its description.

The transfer of control to USE procedures occurs when a file is opened,
as follows:

   *   INPUT, I-O, and EXTEND - control is passed to the appropriate USE
       procedure after a beginning input label check procedure is
       executed.

   *   OUTPUT - control is transferred after a beginning output label is
       created, but before it is written.

Using the INPUT keyword allows you to read labels, while using I-O allows
you to both read and write them.  The use of the OUTPUT or EXTEND
keywords only allows you to write user labels.

Using a file name allows you to either read or write, or both, depending
upon how the file is opened.  Thus, for example, a file opened in I-O
mode allows you to read and write user labels.

Within a format 2 USE procedure, no statements are explicitly written in
order to read or write a user label.

For an input or input-output file, a corresponding USE procedure
automatically reads the user label into the label record of the file.
The USE procedure may then be written to check that the label has the
form and content desired.

All format 2 USE procedures have an exit mechanism appended to them by
the compiler.  This exit mechanism follows the last statement of the
procedure and is used to write user labels out to the appropriate file.

Therefore, a format 2 USE procedure for a file opened in OUTPUT, I-O, or
EXTEND mode may use the label record data item to define the contents of
a label.  When the exit mechanism is reached, the label is automatically
written to the file.

With a single exception, all logical paths within a declarative procedure
must lead to this exit point, thus terminating the procedure.  This
implies that with one execution of a format 2 USE procedure, only a
single user label may be read or written.

The purpose of the exception mentioned above is to allow you to read or
write more than one user label (up to eight).  The exception is the use
of the GO TO MORE-LABELS statement within a format 2 USE procedure.

The function of this statement varies according to how the file was
opened:

   *   Input files - Control returns to the software that reads an
       additional user label, and then transfers control back to the
       first statement of the USE procedure.  The last statement in the
       USE procedure must be executed in order to terminate label
       processing.

   *   Output and EXTEND files - Control returns to the software that
       writes out the current user label, and then transfers control back
       to the first statement of the USE procedure so that additional
       user labels can be created.  The last statement in the USE
       procedure must be executed in order to terminate label processing.

   *   Input-Output and EXTEND files - Control returns to the software
       that writes out the current label and then reads the next label.
       The software then transfers control back to the first statement of
       the USE procedure.  The last statement in the USE procedure must
       be executed in order to write out the last user label and to
       terminate label processing.

MPE/iX 5.0 Documentation