Guardian Procedure Calls Reference Manual (G06.25+)

Guardian Procedure Calls (H-K)
Guardian Procedure Calls Reference Manual—522629-013
7-58
KEYPOSITION[X] Procedures
(Superseded by FILE_SETKEY_ Procedure)
matching the key criteria. If positioning-mode.<1> = 0, this bit is
ignored.
<14:15> indicates the type of key search to perform and the subset of records
obtained.
0 approximate
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).
1 generic
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.
2 exact
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
< (CCL) indicates that an error occurred (call FILE_GETINFO_ or FILEINFO).
= (CCE) indicates that the KEYPOSITION was successful.
> (CCG) indicates that this is not a structured disk file.
Considerations
•
The calling application process is not suspended because of a call to
KEYPOSITION.
•
The KEYPOSITION and KEYPOSITIONX procedures expect primary-key values
for relative and entry-sequenced files to be in 4-byte form. Thus, these procedures
cannot be used with format 2 files (which require keys in 8-byte form). If an
attempt is made to use these procedures with format 2 files, error 581 is returned.
See the FILE_SETKEY_ Procedure
for information on how to perform the
equivalent task with format 2 files.
•
Error if incomplete nowait operations pending
A call to the KEYPOSITION procedure is rejected with an error indication if there
are any incomplete nowait operations pending on the specified file.
•
Positioning on duplicate or nonexistent records