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

• Relative Key Data Item of Relative Files
A successful execution of the READ statement for a relative file also assigns the relative record
number of the retrieved record to the file’s relative key data item if the file description defines
one. The relative key data item is optional for relative files being accessed sequentially.
• LOCK Phrase
When the READ statement includes a LOCK phrase, the read operation also locks the retrieved
record. The concept of record locking applies only to disk files and queued files. A successful
record lock operation guarantees you exclusive access to the record until the program executes
one:
◦ A REWRITE statement with the UNLOCK option for the same record
◦ An UNLOCKRECORD statement for the same record
◦ An UNLOCKFILE statement for the file
If the program already holds a record lock for the record in question, the read operation notes
this and preserves the lock.
If your HP COBOL process opens the same file twice (that is, treats the file as two separate
files with separate file-control entries, each with its own file-name, executes a READ LOCK
statement on one file-name and then executes another READ LOCK statement on the other
file-name ), the process deadlocks. This problem does not occur if the process opens the
file only once or if you use time limits.
• Interaction of LOCKFILE and READ LOCK Statements
If your process executes a READ LOCK statement on a file that it or any other process has
locked with a LOCKFILE statement, or your process executes a LOCKFILE statement against a
file that has an outstanding READ LOCK, the TIME LIMIT phrase determines what happens.
If the second statement attempting to lock the file has a TIME LIMIT phrase, it keeps trying to
lock the file until the time limit expires. Either it fails and then times out or it succeeds in locking
the file.
If the second statement attempting to lock the file has no TIME LIMIT phrase, it suspends
execution until the statement succeeds because the contending lock is removed or until the
program is terminated by an external agency such as the TACL command STOP.
• INTO Phrase
When the READ statement includes an INTO phrase, the retrieved logical record is moved
from the file record area to the data item specified in the INTO phrase.
Any specified subscript or index evaluation involved occurs after the record is retrieved and
placed in the record area and just before it is moved to the data item.
The size of the sending operand in the implicit MOVE statement is the size of the record as
placed into the record area.
This move does not occur if the execution of the READ statement is unsuccessful for any reason.
See INTO Phrase (page 247).
• GUARDIAN-ERR Special Register
The GUARDIAN-ERR special register is updated each time a file-manipulating statement is
executed. The value of GUARDIAN-ERR usually provides more specific information about the
cause of an unsuccessful completion signaled by the file-status data item. For example, if the
file status is “30” (permanent error), GUARDIAN-ERR contains the file system error number
identifying the cause. See Diagnosing Input-Output Errors (page 251).
412 Procedure Division Verbs