Guardian Procedure Calls Reference Manual

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
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
<0>
its alternate key and its primary key match the corresponding portions of the specified key-value
(which is an alternate key value concatenated with a primary key value) for key-length bytes (which
is 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.
if 1, specifies that subsequent calls to READ or READLOCK return records in descending key order (the
file is read in reverse).
<1>
if 1, and if positioning-mode.<1> = 1 (read-reverse), specifies that positioning is performed to the
last record in the set of records matching the key criteria. If positioning-mode.<1> = 0, this bit is
ignored.
<2>
indicates the type of key search to perform and the subset of records obtained.<14:15>
approximate0
Positioning occurs to the first record whose key field, as designated by the key-specifier,
contains a value equal to or greater than key-value for key-length bytes (equal to or less
than when read-reverse is used).
generic1
Positioning starts at the first record whose key field, as designated by the key-specifier,
contains a value equal to or greater than key-value for key-length bytes (equal to or less
than when read-reverse is used). Records will be accessed until one is reached whose key field
does not start with a value equal to key-value for compare-length bytes.
exact2
Positioning occurs to the first record whose key field, as designated by the key-specifier,
contains a value of exactly compare-length bytes and is equal to key-value.
If positioning-mode is omitted, 0 is used.
Condition Code Settings
indicates that an error occurred (call FILE_GETINFO_ or FILEINFO).< (CCL)
indicates that the KEYPOSITION was successful.= (CCE)
indicates that this is not a structured disk file.> (CCG)
752 Guardian Procedure Calls (H-K)