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

• Use of wait-time
wait-time must be either a numeric data item or a numeric literal, signed or unsigned,
having a maximum of seven digits to the left of the decimal. Any fractional part to the right
of the decimal is rounded to two decimal places; for example:
05 WAIT-FILEX PIC 9(7)V9(2) COMPUTATIONAL.
A nonnegative value of wait-time indicates the time interval within which the operation
must complete. If the record is locked or reading a process and the operation does not complete
within that time interval, it is terminated, and no error message is generated. The file-status
item is set to “30,” the GUARDIAN-ERR register is set to 40, and the value of the file position
indicator becomes undefined.
The file position indicator is undefined because it is not clear at what point of the read operation
wait-time was exceeded. There is no guarantee that you can try the operation again.
If the value of wait-time is -1 or the TIME LIMIT phrase is not present, no time limit is placed
on the operation. The program can wait indefinitely for its request to complete. Any other
negative value has the same effect as -1.
If the TIME LIMIT phrase is specified with a nonnegative value and the file is not opened with
time limits enabled, the program terminates with an I-O status code “90,” and a message (File
is not opened for timed I-O) is delivered to the process’s home terminal.
The effect of declaratives on time-limit termination is:
◦ If there is no declarative procedure applicable to the file when the operation is abandoned,
the process terminates, and an ABEND message is reported to the process’s home terminal.
◦ If the applicable declarative procedure is present (but no AT END phrase is present) and
the time interval expires, the declarative procedure is performed. Then program execution
continues with the imperative statement in the NOT AT END phrase, if one is present, or
otherwise with the statement following the one terminated.
When a file is being read with APPROXIMATE positioning (see START (page 449)), the
value used for wait-time must take into account that a read operation can take
somewhat longer than expected. This can occur when a nonexistent record is sought,
because the file system searches through the file looking for the next defined record before
reporting the absence of the record sought. See the Guardian Programmer’s Guide for
more information on the action of READ.
• Concept of Next Record
READ NEXT is used to read the next record of a file whose access mode is SEQUENTIAL or
DYNAMIC. Files whose access mode is SEQUENTIAL can be read without the NEXT keyword,
but each such read gets the “next record” in the file. The “next record” means “next existing
record within the established key of reference.”
◦ If the last operation on the file was a start operation (or open operation, in the case of
relative, indexed, or queue files), and the record selected by the file position indicator is
still accessible through the file position indicator, that record is read.
◦ If the last operation on the file was a read operation (either a READ KEY or a READ
NEXT), or if the record selected by the file position indicator is no longer accessible
through the file position indicator (due to deletion or a change of the alternate key), the
file position indicator is updated to point to the next existing record in the file, and that
record is read.
◦ If the value of the file position indicator for the file is undefined when execution of the
READ statement begins, the read operation is unsuccessful, and any file-status data item
declared for the file in the file-control entry is updated to specify the reason.
414 Procedure Division Verbs