Guardian Procedure Calls Reference Manual

(PFS) for I/O transfers. A file opened by OPEN uses a PFS buffer for I/O transfers, except
for large transfers to DP2 disks.
◦ 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.
• Queue files
FILE_READ64_ can be used to perform a nondestructive read of a queue file record. If
FILE_SETKEY_ (or KEYPOSITION[X]) is used to position to the beginning of the file, the first
FILE_READ64_ performed returns a record with a length of 8 bytes and contents of all zeroes.
Subsequent FILE_READ64_ calls will return data from records written to the file.
WARNING! On NSAA systems, the FILE_READ64_, FILE_WRITE64_ and FILE_WRITEREAD64_
procedures use the process file segment (PFS) of the caller to store the data being read or written.
The maximum PFS size is 32 MB. This limits the number of concurrent no-wait operations with large
read-count or write-count values. Perform the following steps to work around this limit:
1. Define the read and write buffers with sizes in multiples of 16KB
2. Call the USERIOBUFFER_ALLOW_ procedure before making any calls to these procedures.
3. Allocate extended data segments using the SEGMENT_ALLOCATE64_ procedure.
4. Define a pool on the segment using the POOL64_DEFINE_ procedure.
5. Allocate buffers from the pool boundaries. See the FILE_AWAITIO64_ procedure for an
example.
Disk File Considerations
• Large data transfers for unstructured files using default mode
For the read procedures, 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
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.
• Structured files
A subset of records for sequential FILE_READ64_ calls
The subset of records read by a series of calls to FILE_READ64_ is specified through the
FILE_SETPOSITION_ (or POSITION) or FILE_SETKEY_ (or KEYPOSITION[X]) procedures.
◦
◦ Reading of an approximate subset of records
If an approximate subset is being read, the first record returned is the one whose key
field, as indicated by the current key-specifier, contains a value equal to or greater
FILE_READ64_ Procedure 479