Guardian Procedure Calls Reference Manual

to FILE_GETINFO_ or FILEINFO shows that an error 551 occurred; this error is advisory only and does
not indicate an unsuccessful read operation.
indicates that the READLOCK[X] is successful.= (CCE)
indicates end of file (EOF). There are no more records in this subset.> (CCG)
Considerations
• 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.
WARNING! When using nowait file I/O, data corruption might occur if the READ buffer is
modified before the AWAITIOX that completes the call. The buffer space must not be freed or
reused while the I/O is in progress.
• 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 pointer is set to the previous next-record pointer plus read-count. This
process repeats for each subsequent call to READLOCK[X].
• Performing concurrent large no-wait I/O operations on NSAA systems
In H06.28/J06.17 RVUs with specific SPRs and later RVUs, reads and writes of up to 27,648
bytes can be performed on structured opens of format 2 legacy key-sequenced files and
enhanced key-sequenced files that have increased limits. (For a list of the required
H06.28/J06.17 SPRs, see SPR Requirements for Increased Enscribe Limits for the
H06.28/J06.17 Release (page 31).)
On NSAA systems, data being read or written may be stored in the 32MB process file segment
(PFS) along with the open file information. This segment provides an upper limit on the number
of concurrent no-wait I/O operations with large read-count or write-count values for those
applications with a large number of open files. You can work around this limitation by following
these guidelines in your application:
1. Define read and write buffers with sizes that are multiples of 16 KB.
2. Call the USERIOBUFFER_ALLOW_ procedure before issuing any large no-wait I/Os.
3. Allocate the extended data segments using the SEGMENT_ALLOCATE_ procedure. More
than one segment might be required, depending on the maximum number of concurrent
large no-wait I/Os and the total size of the memory required by the application.
1210 Guardian Procedure Calls (R)