Guardian Procedure Calls Reference Manual

• Waited WRITEUPDATE[X]
If a waited WRITEUPDATE[X] is executed, the count-written parameter indicates the
number of bytes actually written.
• Nowait WRITEUPDATE[X]
If a nowait WRITEUPDATE[X] is executed, count-written has no meaning and can be
omitted. The count of the number of bytes written is obtained through the
count-transferred parameter of the AWAITIO[X] procedure when the I/O completes.
The WRITEUPDATE[X] procedure must finish with a corresponding call to the AWAITIO[X]
procedure when used with a file that is opened nowait. For files audited by the Transaction
Management Facility (TMF), the AWAITIO[X] procedure must be called before the
ENDTRANSACTION or ABORTTRANSACTION procedure is called.
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 write 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 write and another
I/O operation because this creates the possibility of changing the contents of the write buffer
before the write is completed.
• Invalid write operations to queue files
Attempts to perform WRITEUPDATE[X] operations are rejected with an error 2.
• 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.
4. Define memory pools for the allocated extended data segments.
5. Use the POOL_GETSPACE_PAGE_ procedure to obtain a block of memory, which will
be used as the read or write buffer.
6. When the no-wait I/O operation is complete, use the POOL_PUTSPACE_ procedure to
return the memory to the pools.
On non-NSAA systems, reads and writes larger than 4KB on key-sequenced files may be
performed directly from or into the application’s buffer.
1512 Guardian Procedure Calls (W-Z)