Guardian Procedure Calls Reference Manual (G06.25+)

Guardian Procedure Calls (R)
Guardian Procedure Calls Reference Manual—522629-013
13-23
READLOCK[X] Procedures
Condition Code Settings
< (CCL) indicates that an error occurred (call FILE_GETINFO_ or FILEINFO).
< (CCL) is also returned following a successful read with an insertion-ordered
alternate key path if the alternate key value of the current record is equal to
the alternate key value in the following record along that path. A call to
FILE_GETINFO_ or FILEINFO shows that an error 551 occurred; this error
is advisory only and does not indicate an unsuccessful read operation.
= (CCE) indicates that the READLOCK[X] is successful.
> (CCG) indicates end of file (EOF). There are no more records in this subset.
Considerations
•
READLOCK versus READLOCKX
Use READLOCK if the buffer has a 16-bit address and use READLOCKX if the
buffer has a 32-bit extended address. Therefore, the data buffer for READLOCKX
can be either in the caller’s stack segment or any extended data segment.
•
Nowait I/O and READLOCK[X]
If the READLOCK[X] procedure is used to initiate an operation with a file-opened
nowait, it must complete with a corresponding call to the AWAITIO[X] procedure. If
READLOCKX is used, you must call AWAITIOX to complete the I/O. If
READLOCK is used, you may use either AWAITIO or AWAITIOX to complete the
I/O.
•
READLOCK[X] for key-sequenced, relative, and entry-sequenced files
For key-sequenced, relative, and entry-sequenced files, a subset of the file
(defined by the current access path, positioning mode, and comparison length) is
locked and read with successive calls to READLOCK[X].
For key-sequenced, relative, and entry-sequenced files, the first call to
READLOCK[X] after a positioning (or open) locks and then returns the first record
of the subset. Subsequent calls to READLOCK[X] without intermediate positioning
locks, returns successive records in the subset. After each of the subset’s records
are read, the position of the record just read becomes the file’s current position.
An attempt to read a record following the last record in a subset returns an EOF
indication.
•
Locking records in an unstructured file
READLOCK[X] can be used to lock record positions, represented by a relative byte
address (RBA), in an unstructured file. When sequentially reading an unstructured
file with READLOCK[X], each call to READLOCK[X] first locks the RBA stored in
the current next-record pointer and then returns record data beginning at that
pointer for
read-count bytes. After a successful READLOCK[X], the current-
record pointer is set to the previous next-record pointer, and the next-record