COBOL Manual for TNS/E Programs (H06.08+, J06.03+)

• Handling Exception Conditions
The READ statement enables you to specify explicitly that when an at-end condition occurs, a
particular statement is to be executed.
For general exception handling, a group of statements called declaratives can be placed at
the beginning of the Procedure Division to respond to error conditions arising for a single file
or for all files open in the same input mode (INPUT, OUTPUT, I-O, or EXTEND). See USE AFTER
EXCEPTION (page 484).
The USE AFTER EXCEPTION statement specifies what to do when a file-manipulating statement
encounters an exception condition. Declaratives can be called for at-end, invalid key, and
other exception conditions.
If, for example, the program includes a USE statement referring to the file being read, and a
read operation is attempted when no next logical record exists, then the process executes
either an AT END phrase or the USE statement:
◦ If an AT END phrase is present, it is executed.
◦ If no AT END phrase is present, the USE statement is executed.
If a READ operation encounters a recoverable permanent error (Status Key 1 equals 3, or
Status Key 1 equals 9 but Status Key 2 does not equal 7), no at-end condition occurs; however,
if a declarative is present for the file, that declarative is activated, then any NOT AT END
phrase is executed. Either the declarative or the NOT AT END phrase can then determine the
nature of the error (usually by checking GUARDIAN-ERR) and take appropriate action. See
Recovering from Input-Output Errors (page 255).
After an at-end condition for a sequentially accessed file (other than $RECEIVE), you must
close and reopen or reposition the file before any further operations can be done on it. You
can reposition the file with the START statement, the routine COBOL85^REWIND or
COBOL_REWIND_.
• Variable-Length Records
An Enscribe structured file is always capable of containing variable-length records. The file
has a stated maximum allowable record length, but records can vary from a length of 0 up
to the stated maximum. If the file is written as variable-length records, the COBOL program
can read it under a declaration of
RECORD CONTAINS rec-1 TO rec-2 CHARACTERS
or
RECORD IS VARYING IN SIZE FROM rec-1 TO rec-2 CHARACTERS
DEPENDING ON rec-size
(although in COBOL you cannot explicitly state rec-1 as 0). The only way to determine the
length of the record read is to use the DEPENDING phrase of the VARYING clause. The
contents of the record area beyond the data fetched by any given read is undefined.
Other HP products are capable of writing records of length 0 in such files. A COBOL program
can read a record of length 0; however, in an entry-sequenced file with fixed-length records,
such a record is ignored and the next record is immediately read.
• Setting the Value of the DEPENDING Item (Variable-Length Records)
When the file has variable-length records whose sizes are reflected by the rec-size item
specified in the RECORD VARYING clause of the file description entry, the value associated
with the rec-size at the beginning of a read operation is ignored. The read operation
obtains the record and moves the number of character positions the record contains into
rec-size.
READ 413