Guardian Procedure Calls Reference Manual

• Structured files
A subset of records for sequential READ[X]s
The subset of records read by a series of calls to READ[X] is specified through the
POSITION or KEYPOSITION 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
than the current key. Subsequent reading of the subset returns successive records until the
last record in the file is read (an EOF indication is then returned).
◦ Reading of a generic subset of records
If a generic subset is being read, the first record returned is the one whose key field, as
designated by the current key-specifier, contains a value equal to the current key
for compare-length bytes. Subsequent reading of the file returns successive records
whose key matches the current key (for compare-length bytes). When the current key
no longer matches, an EOF indication returns.
For relative and entry-sequenced files, a generic subset of the primary key is equivalent
to an exact subset.
◦ Reading of an exact subset of records
If an exact subset is being read, the only records returned are those whose key field, as
designated by the current key-specifier, contains a value of exactly
compare-length bytes (see KEYPOSITION[X] Procedures (Superseded by FILE_SETKEY_
Procedure) (page 750)) and is equal to the key. When the current key no longer matches,
an EOF indication returns. The exact subset for a key field having a unique value is at
most one record.
◦ Indicators after READ[X]
After a successful READ[X], the current-state indicators have these values:
record just readCurrent position
unchangedPositioning mode
unchangedComparison length
set to the value of the primary-key field in the recordCurrent primary-key
value
◦ Read-reverse action on current and next record pointers
Following a call to READ when reverse-positioning mode is in effect, the next-record
pointer contains the record number or address which precedes the current record number
or address.
Following a read of the first record in a file (where current-record pointer = 0) with reverse
positioning, the next-record pointer will contain an invalid record number or address
since no previous record exists. A subsequent call to READ would return an "end-of-file"
error, whereas a call to WRITE would return an "illegal position" error (error 550) since
an attempt was made to write beyond the beginning of the file.
• Unstructured files
READ[X]s
Data transfer begins from an unstructured disk file at the position indicated by the
next-record pointer.
◦
READ[X] Procedures 1197