Guardian Procedure Calls Reference Manual

The READ[X] procedure reads records sequentially on the basis of a beginning relative
byte address (RBA) and the length of the records read.
◦ Odd unstructured
If the unstructured file is created with the odd unstructured attribute (also known as
ODDUNSTR) set, the number of bytes read is exactly the number of bytes specified with
read-count. If the odd unstructured attribute is not set when the file is created, the value
of read-count is rounded up to an even number before the READ[X] is executed.
You set the odd unstructured attribute with the FILE_CREATE_, FILE_CREATELIST_, or
CREATE procedure, or with the File Utility Program (FUP) SET and CREATE commands.
◦ READ[X] count
Unstructured files are transparently blocked. The BUFFERSIZE file attribute value, if not
set by the user, defaults to 4096 bytes. The BUFFERSIZE attribute value (which is set by
specifying SETMODE function 93) does not constrain the allowable read-count in any
way. However, there is a performance penalty if the READ[X] does not start on a
BUFFERSIZE boundary and does not have a read-count that is an integral multiple of
the BUFFERSIZE. The DP2 disk process executes your requested I/O in (possibly multiple)
units of BUFFERSIZE blocks starting on a block boundary.
◦ count-read for unstructured READ[X]s
After a successful call to READ[X] for an unstructured file, the value returned in
count-read is determined by:
count-read := $MIN(read-count & eof-pointer - next-record pointer)
◦ Pointers after READ[X]
After a successful READ[X] to an unstructured file, the file pointers are:
– CCG = 1 if the next-record pointer = EOF pointer; otherwise CCG = 0
– current-record pointer = old next-record pointer
– next-record pointer = old next-record pointer + count-read
Errors for READ[X]
The READ[X] procedure returns FEEOF (1) when passed a filenum for an unstructured open of
the primary partition of an enhanced key-sequenced file. For more information on enhanced
key-sequenced files, see the Enscribe Programmer's Guide.
Errors for READX Only
In addition to the errors currently returned from READ, error 22 is returned from READX when:
• The address of a parameter refers to the selectable segment area but no selectable segment
is in use at the time of the call.
• The address of a parameter is extended, but it is an absolute address and the caller is not
privileged.
Example
CALL READ ( FILE^NUM , IN^BUFFER , 72 , NUM^XFERRED );
! The READ permits up to 72 bytes to be read into IN^BUFFER,
! and the count actually read returns into NUM^XFERRED.
1198 Guardian Procedure Calls (R)