Guardian Procedure Calls Reference Manual

• Queue files
READ[X] can be used to perform a nondestructive read of a queue file record. If
KEYPOSITION[X] is used to position to the beginning of the file, the first READ[X] performed
returns a record with a length of 8 bytes and contents of all zeroes. Subsequent READ[X] calls
will return data from records written to the file.
• 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.
Disk File Considerations
• Large data transfers for unstructured files using default mode
For the read procedures (READ[UPDATE] [LOCK] [X]), using default mode allows I/O sizes
for unstructured files to be as large as 56 kilobytes (57,344), if the unstructured buffer 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 READX only, large data transfers (more than 4096 bytes) can be done for unstructured
access to structured or unstructured files, 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 read-count parameter. See
Table 44 (page 1319) for use of SETMODE function 141.
1196 Guardian Procedure Calls (R)