Guardian Procedure Calls Reference Manual

A similar situation arises when you read a key-sequenced file with duplicate alternate keys.
When an alternate-key file allows duplicate alternate keys that are ordered by primary-key
value (the standard ordering method), key-value must be thought of as having two parts:
the alternate-key value and the primary-key value. You can specify both parts or you can
specify the alternate-key value only. Consider these records:
Primary KeyAlternate KeyRecord Number
30AAA0
10BBB1
20BBB2
40CCC3
Following an approximate KEYPOSITION to key-value = "BBB", key-length = 3, and
position-mode = read-reverse, the position would be just before record 1 and after record
0. This position results because, when key-value is specified as "BBB", the primary-key part
is null (the lowest possible key value). A call to READ would return record 0. The same call to
KEYPOSITION, but with position-to-last specified, would result in record 2 being returned from
READ.
For the primary key of relative and entry-sequenced files, the key-value parameter to
KEYPOSITION is a four-byte string containing a doubleword record number value. When
read-reverse and approximate positioning are specified, initial positioning is performed to
the first record whose record number is equal to or less than the record number passed in
key-value. Records are returned in descending record number order from successive calls
to READ. The position-to-last option has no effect (is ignored) for a KEYPOSITION to an exact
record number in a relative or entry-sequenced file.
Positioning to the last record in a file with KEYPOSITION is accomplished by specifying
approximate mode, read-reverse, and position-to-last in the positioning-mode parameter,
and setting key-length to 0. A subsequent call to READ will return the last record in the
file.
• Read Reverse and SAVEPOSITION
When saving the current position in a relative or entry-sequenced file with no alternate keys,
the SAVEPOSITION procedure requires an additional three words in the positioning buffer,
for a total of seven words when read-reverse positioning is in effect. If you have programs
currently using SAVEPOSITION with a four-word positioning buffer, please note this change.
• 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 "invalid position" error (error 550) since an
attempt was made to write beyond the beginning of the file.
KEYPOSITION[X] Procedures (Superseded by FILE_SETKEY_ Procedure) 755