Guardian Procedure Calls Reference Manual

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.
Disk File Considerations
• Large data transfers for unstructured files using default mode
For the write procedures (WRITE[LOCK] [UNLOCK]), default mode allows I/O sizes for
unstructured files to be as large as 56 KB (57,344), excepting writes to audited files, if the
unstructured buffer size (or block size) is 4 KB (4096). Default mode here refers to the mode
of the file if SETMODE function 141 is not invoked.
For an unstructured file with an unstructured buffer size other than 4 KB, DP2 automatically
adjusts the unstructured buffer size to 4 KB, if possible, when an I/O larger than 4KB is
attempted. However, this adjustment is not possible for files that have extents with an odd
number of pages; in such cases an I/O over 4 KB is not possible. Note that the switch to a
different unstructured buffer size will have a transient performance impact, so it is recommended
that the size be initially set to 4 KB, which is the default. Transfer sizes over 4 KB are not
supported in default mode for unstructured access to structured files.
• Large data transfers using SETMODE function 141
For WRITEX only, large data transfers (more than 4096 bytes) can be done for files opened
with unstructured access, regardless of unstructured buffer size, by using SETMODE function
141. When SETMODE function 141 is used to enable large data transfers, it is permitted to
specify up to 56K (57344) bytes for the write-count parameter. For use of SETMODE
function 141, see Table 44 (page 1319) .
• File is locked
If a call to WRITE[X] is made and the file is locked through a file number other than that
supplied in the call, the call is rejected with file-system error 73 (file is locked).
• Inserting a new record into a file
The WRITE[X] procedure inserts a new record into a file in the position designated by the file's
primary key:
The record is inserted in the position indicated by the value in its primary-key
field.
Key-Sequenced Files
The record is inserted into a file at a unique location. The disk process sets the
timestamp field in the key, which causes the record to be positioned after the
other existing records that have the same high-order user key.
Queue Files
WRITE[X] Procedures 1493