Guardian Procedure Calls Reference Manual

• Saving current position
When positioning by standard (not insertion-ordered) alternate key, you can save the current
file position for later access by concatenating alternate-key value and primary key values in
a temporary buffer. This permits you to return to that position in a key-sequenced file; for
example:
temporary-buffer ':='
record.altkeyfield FOR $LEN (record.altkeyfield)
& record.primarykey FOR $LEN (record.primarykey);
Use this to reposition to the same record:
KEYPOSITION ( filenum , temporary-buffer
, key-specifier,
$LEN (record.altkeyfield) +
$LEN (record.primarykey),
positioning-mode );
Use this to reposition to the next record:
KEYPOSITION ( filenum , temporary-buffer ,
key-specifier ,
$LEN (record.altkeyfield) +
$LEN (record.primarykey),
%100000 + positioning-mode );
In either case, if generic positioning is desired, the generic length would be placed in the
upper eight bits of the length-word parameter.
This method will not work when positioning with an insertion-ordered alternate key, because
the value of the timestamp portion of the alternate key is not contained in the primary record.
However, you can use the SAVEPOSITION and REPOSITION procedures to save and restore
the current position when positioning to an insertion-ordered alternate (or any other) key is in
effect.
• Positioning to the start of a file
To position to the first record of a key-sequenced file, you can use this call to specify a zero
length-word:
INT ZERO := 0;
CALL KEYPOSITION ( FILENUM , ZERO ,, ZERO );
• Position-to-Last Option
The standard operation of KEYPOSITION is to position to the first record that satisfies the
positioning criteria specified by key-value, key-length, compare-length, and
positioning-mode. When reading a file in reverse order, however, you might want to
position to the last record in the set of records matching the positioning criteria. Consider
these records:
Key ValueRecord Number
AAA0
ABA1
ABB2
ABC3
ACA4
Following an approximate KEYPOSITION to key-value = "AB", key-length = 2, and
positioning-mode = read-reverse, a call to READ would return record number 1 from the
set of records shown above. The same call to KEYPOSITION, but with position-to-last also
specified, would result in record number 3 being returned from READ.
754 Guardian Procedure Calls (H-K)