Guardian Procedure Calls Reference Manual (G06.25+)

Guardian Procedure Calls (H-K)
Guardian Procedure Calls Reference Manual—522629-013
7-57
KEYPOSITION[X] Procedures
(Superseded by FILE_SETKEY_ Procedure)
length-word input
INT:value
contains two values:
<0:7> compare-length (left byte) specifies, in bytes, the length to use for
key comparisons made to decide when to stop returning records under
the generic or exact positioning modes.
<8:15> key-length (right byte) specifies how many bytes of the key-value
are to be searched for in the file to find the initial position.
•
If length-word is omitted, compare-length and key-length are defined to
be the length of the key (
key-specifier) defined when the file was created.
That is, if
key-specifier is omitted or 0, compare-length and key-length
are the length of the primary key. If
key-specifier is the key specifier for an
alternate key, the length of the alternate-key field is used.
•
If length-word is 0, compare-length and key-length are also 0. This
results in positioning to the beginning of the file. (Although
key-value is still a
required parameter, its value is ignored when
length-word = 0.)
•
If key-length = 0 and compare-length <> 0, file-system error 21 is returned
from KEYPOSITION.
•
If key-length <> 0 and compare-length = 0, compare-length is defined to
be the minimum of
key-length or the key length defined when the file was
created.
•
If key-length <> 0 and compare-length <> 0, the supplied values are used.
See “KEYPOSITION and file-system Error 21” under ”Considerations.”
positioning-mode input
INT:value
<0> if 1, and if a record with exactly the key-length and key-value
specified is found, the record is skipped. If the
key-specifier
indicates a non-unique alternate key, the record is skipped only if both
its alternate key and its primary key match the corresponding portions
of the specified
key-value (which should be an alternate key value
concatenated with a primary key value) for
key-length bytes
(which should be the sum of the alternate and primary key lengths).
This option is not supported for positioning by primary key in relative or
entry-sequenced files.
<1> if 1, specifies that subsequent calls to READ or READLOCK return
records in descending key order (the file is read in reverse).
<2> if 1, and if positioning-mode.<1> = 1 (read-reverse), specifies that
positioning is performed to the last record in the set of records