Guardian Procedure Calls Reference Manual

Considerations
• Waited I/O READ
If a waited I/O WRITEREAD[X] is executed, the count-read parameter indicates the number
of bytes actually read.
• Nowait I/O READ
If a nowait I/O WRITEREAD[X] is executed, count-read has no meaning and can be omitted.
The count of the number of bytes read is obtained when the I/O operation completes through
the count-transferred parameter of the AWAITIO[X] procedure.
The WRITEREAD[X] procedure must complete with a corresponding call to the AWAITIO[X]
procedure when used with a file that is opened nowait. If WRITEREADX is used, you must call
AWAITIOX to complete the I/O. If WRITEREAD is used, you can use either AWAITIO or
AWAITIOX to complete the I/O.
WARNING! When using nowait file I/O, data corruption might occur if the READ or WRITE
buffers are modified before the AWAITIOX that completes the call. The buffer space must not
be freed or reused while the I/O is in progress.
Do not change the contents of the data buffer between the initiation and completion of a
nowait WRITEREAD operation. This is because a retry can copy the data again from the user
buffer and cause the wrong data to be written. Avoid sharing a buffer between a WRITEREAD
and another I/O operation because this creates the possibility of changing the contents of the
data buffer before the write is completed.
• Carriage return/line feed sequence after the write
There is no carriage return/line feed sequence sent to the terminal after the write part of the
operation.
Considerations for WRITEREADX Only
• The buffer and count transferred may be in the user stack or in an extended data segment.
The buffer and count transferred cannot be in the user code space.
• 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.
• If the file is opened for nowait I/O, and the buffer is in an extended data segment, you cannot
deallocate or reduce the size of the extended data segment before the I/O completes with a
call to AWAITIOX or is canceled by a call to CANCEL or CANCELREQ.
• If the file is opened for nowait I/O, and the I/O has been initiated with these routines, the
I/O must be completed with a call to AWAITIOX (not AWAITIO).
• If the file is opened for nowait I/O, the extended segment containing the buffer need not be
in use at the time of the call to AWAITIOX.
• Nowait I/O initiated with these routines may be canceled with a call to CANCEL or
CANCELREQ. The I/O is canceled if the file is closed before the I/O completes or AWAITIOX
is called with a positive time limit and specific file number and the request times out.
• If the extended address of the buffer is odd, bounds checking rounds the address to the next
lower word boundary and checks an extra byte as well. The odd address is used for the
transfer.
WRITEREAD[X] Procedures 1507