Updated March 2016; see History
xcall FLOCK, action, mode, status, file, rec
FLOCK.SBR provides a scheme for implementing shared and exclusive file and record locks, with an option to wait or return an in-use code. The A-Shell version is fully upward compatible with the AMOS version, and in addition goes beyond the various 64K limits in the AMOS version to support file channels and record number values up to 2 billion.
action (Num) ([in]
Numeric code indicating the action to perform:
|
Value |
Description |
|
0 |
Request permission to open file (see File) |
|
1 |
Inform FLOCK that file has been closed |
|
2 |
Program terminating – requests all locks on all files for this user to be released |
|
3 |
Request permission to read record (see File, Rec) |
|
4 |
Request permission to read/write all records of File |
|
5 |
Release Rec (previously locked with Action 3) |
|
6 |
Release File (previously locked with Action 4) |
mode (Num) [in]
Flags for exclusive and wait options:
|
Value |
Description |
|
0 |
Non exclusive lock, wait until request can be granted |
|
2 |
Exclusive lock, wait until request can be granted |
|
4 |
Non exclusive lock, no wait (return immediately with Status = 1 if request cannot be granted) |
|
6 |
Exclusive lock, no wait (return immediately with Status = 1 if request cannot be granted) |
status (F,6)
Return code (for actions indicated in parentheses):
|
Value |
Description |
|
0 |
Success |
|
1 |
Resource unavailable (0,3,4) |
|
2 |
Open request already granted (0) |
|
3 |
Permission to open must first be granted (1,3-6) |
|
4 |
Duplicate request for some record in file (3,4) |
|
5 |
Permission to use record must first be granted (5,6) |
|
100 |
Unimplemented action |
|
101 |
File channel not open for random processing (3-6) |
|
102 |
File channel already open for ISAM (0) |
|
103 |
Less than 15 queue blocks available (0,3,4) |
|
104 |
Illegal record (3-6) |
file (Num)
Numeric value indicating the file channel
rec (Num)
Numeric value indicating the record number
FLOCK.SBR uses the queue block system to store the locks. You can specify the number of available queue blocks, and the location of the queue file (on disk or in memory) using the QUEUE= property in miame.ini. Note that since the memory option (available under UNIX/Linux only) is much faster, it is highly recommended if you are using FLOCK or XLOCK.
QUTL can be used to display the locks in use and to manually clear locks left by an aborted job. It also displays locks that are pending (i.e. that a job is waiting on), which can be very useful in determining why a job appears to be hung. (An application can, and probably should, warn the user directly when it is stuck waiting on a lock, by using the no-wait mode flags 4 and 6.)
A-Shell’s implementation of FLOCK.SBR has an additional feature in that after waiting for more than 10 seconds for a lock, it will write out a "pending" lock record to the queue. This has no effect except that it can be displayed in the QUTL utility (which can also be executed under program control to create a list file) and thus allows for possibility of reporting to the user who has the lock that he or she is waiting for.
The system parameter setting TRACE=LOCKS causes information about the conflicting lock that you are waiting for to be displayed on the bottom status line of the terminal.
History
2016 March, A-Shell 6.2.1425: FLOCK bug fix/refinement: The memory allocation for the FLOCK cache now registers the name "FLKCACHE" in the log, which is useful when debugging memory handle use with the MALLOC TRACE. Also, close a memory leak whereby the cache was needlessly reallocated if FLOCK called within an SBX.