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

file-name
is the file description name of the file to lock. For LOCKFILE to work, file-name must specify
a disk file.
wait-time
is a numeric literal or the name of a numeric data item. Its value must have no more than seven
digits preceding any decimal point. Any fractional portion is rounded to two decimal places.
For example:
03 WAIT-TIME PIC 9(7)V9(2) COMPUTATIONAL.
A nonnegative wait-time is the number of seconds within which the LOCKFILE operation
must finish. If the LOCKFILE operation does not finish within that time, it terminates with no error
message. The I-O status code has the value “30” and the GUARDIAN-ERR register has the
value 40.
If wait-time is negative or no wait-time is specified, the LOCKFILE operation has no
time limit. The program can wait indefinitely.
If file-name was not opened with a TIME LIMITS phrase, including wait-time in the
LOCKFILE statement causes a run-time error.
Usage Considerations:
• Action of the LOCKFILE Statement
The LOCKFILE statement has no effect if the process has already locked the file or if the file is
not a disk file. Whether effective or not, the LOCKFILE statement does not affect the key of
reference, the file position indicator, or the contents of the record area associated with the
file.
• I-O Status Code
If the file has an associated file-status data item, the LOCKFILE statement assigns it an
appropriate I-O status code. The possible I-O status codes that result from LOCKFILE operations
are:
MeaningI-O Status Code
LOCKFILE executed successfully.“00”
Either the specified (nonnegative) time limit elapsed before the LOCKFILE completed
(in which case, GUARDIAN-ERR is also set to 40), or the LOCKFILE operation failed
due to non-COBOL causes. The file might or might not have been locked.
“30”
The file was not open.“42”
The wait-time is nonnegative but the file was not opened with time limits enabled.
An error message is delivered to the process’s home terminal.
“90”
• One File Open Under Multiple Names
If a file-system file is opened twice or more times, using two or more distinct file descriptions,
only one of the file descriptions can have the file locked at a time.
• Declarative Procedures
If a declarative procedure applies to the file and the time interval expires, the declarative
procedure is performed, and program execution continues with the statement following the
LOCKFILE 359