Guardian Procedure Calls Reference Manual

tag
input
INT(32):value
is for nowait I/O only. tag is a value you define that uniquely identifies the operation associated
with this READ[X].
NOTE: The system stores the tag value until the I/O operation completes. The system then returns
the tag information to the program in the tag parameter of the call to AWAITIO[X], thus indicating
that the operation completed. If READX is used, the user must call the AWAITIOX procedure to
complete the I/O. If READ is used, the user may use either AWAITIO or AWAITIOX to complete
the I/O.
Condition Code Settings
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 this record along that path. A call
< (CCL)
to FILE_GETINFO_ or FILEINFO shows that error 551 occurred; this error is advisory only and does
not indicate an unsuccessful read operation.
indicates that the READ[X] is successful.= (CCE)
for disk and nondisk devices, indicates that the end of file (EOF) is encountered (no more records in
this subset); for the $RECEIVE file, a system message is received (call FILE_GETINFO_ or FILEINFO).
> (CCG)
Considerations
• Waited READ[X]
If a waited READ[X] is executed, the count-read parameter indicates the number of bytes
actually read.
• Nowait READ[X]
If a nowait READ[X] is executed, count-read has no meaning and can be omitted. The
count of the number of bytes read is obtained through the count-transferred parameter
of the AWAITIO[X] procedures when the I/O operation completes.
The READ[X] procedure must complete with a call to the AWAITIO[X] procedure when it is
used with a file that is opened nowait. If READX is used, you must call AWAITIOX to complete
the I/O. If READ 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.
It is possible to initiate concurrent nowait read operations that share the same data buffer. To
do this successfully with files opened by FILE_OPEN_, you must use SETMODE function 72 to
cause the system to use an intermediate buffer in the process file segment (PFS) for I/O transfers.
With files opened by OPEN, a PFS buffer is used by default.
• READ[X] from process files
The action for a READ of a process file is the same as that for a WRITEREAD with zero
write-count.
• READ[X] call when default locking mode is in effect
If the default locking mode is in effect when a call to READ[X] is made to a locked file, but
the filenum of the locked file differs from the filenum in the call, the caller of READ[X] is
1194 Guardian Procedure Calls (R)