Guardian Procedure Calls Reference Manual

• Nowait I/O and FILE_READLOCK64_
If the FILE_READLOCK64_ procedure is used to initiate an operation with a file opened nowait,
it must complete with a corresponding call to either FILE_AWAITIO64_ or FILE_COMPLETEL_.
WARNING! When using nowait file I/O, data corruption might occur if the read buffer is
modified before either FILE_AWAITIO64_ or FILE_COMPLETEL_ completes the call. The buffer
space must not be freed or reused while the I/O is in progress.
• FILE_READLOCK64_ 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 FILE_READLOCK64_.
For key-sequenced, relative, and entry-sequenced files, the first call to FILE_READLOCK64_
after a positioning (or open) locks and then returns the first record of the subset. Subsequent
calls to FILE_READLOCK64_ 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
FILE_READLOCK64_ 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
FILE_READLOCK64_, each call to FILE_READLOCK64_ 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 FILE_READLOCK64_, the current-record pointer is set to the previous
next-record pointer, and the next-record pointer is set to the previous next-record pointer plus
read-count. This process repeats for each subsequent call to FILE_READLOCK64_.
• Buffer considerations
The buffer and count transferred can be in the user stack or in an extended data segment.
The buffer and count transferred cannot be in the user code space.
◦
◦ The buffer and count transferred address must be relative; they cannot be an absolute
extended address.
◦ If the buffer or count transferred is in a selectable extended data segment, the segment
must be in use at the time of the call. Flat segments allocated by a process are always
accessible to the process.
◦ The size of the transfer is subject to current restrictions for the type of file.
◦ If the file is opened for nowait I/O, and the buffer is in an extended data segment, you
must not deallocate or reduce the size of the extended data segment before the I/O
finishes with a call to FILE_AWAITIO64_ or FILE_COMPLETEL_ or is canceled by a call
to CANCEL or CANCELREQL.
◦ If the file is opened for nowait I/O, you must not modify the buffer before the I/O finishes
with a call to FILE_AWAITIO64_ or FILE_COMPLETEL_. This also applies to other processes
that might be sharing the segment. It is the application's responsibility to ensure this.
◦ If the file is opened for nowait I/O, a selectable extended data segment containing the
buffer need not be in use at the time of the call to FILE_AWAITIO64_ or FILE_COMPLETEL_.
◦ Nowait I/O initiated with this routine can be canceled with a call to CANCEL or
CANCELREQL. The I/O is canceled if the file is closed before the I/O finishes or
FILE_AWAITIO64_ is called with a positive time limit and specific file number, and the
request times out.
484 Guardian Procedure Calls (F)