Guardian Procedure Calls Reference Manual

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 four-byte form. Thus, these procedures cannot be used with
format 2 files (which require keys in eight-byte form). If an attempt is made to use these
procedures with format 2 files, error 581 is returned. See the FILE_SETKEY_ Procedure
(page 506) 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
No searching of indexes is done by KEYPOSITION; therefore, a nonexistent or duplicate
record is not reported until a subsequent READ, READUPDATE, WRITEUPDATE, LOCKREC,
READLOCK, READUPDATELOCK, or WRITEUPDATEUNLOCK is performed.
• KEYPOSITION and disk seeks
KEYPOSITION does not cause the disk heads to be repositioned; the heads are repositioned
when a subsequent I/O call (READ, READUPDATE, WRITE, and so forth) transfers data.
• Positioning exact
If an exact KEYPOSITION is performed, and a compare-length is specified which is less
than that specified when the file was created, compare-length must match the variable
key length specified when the record is entered into the file. Otherwise, a subsequent call to
READ, READUPDATE, WRITEUPDATE, LOCKREC, READLOCK, READUPDATELOCK, or
WRITEUPDATEUNLOCK is rejected.
• Current-state indicators after a KEYPOSITION
Current-state indicators following a successful KEYPOSITION are:
is that of the record indicated by the key-value, key-specifier,
positioning-mode, and key-length, or the subsequent record if
positioning-mode.<0> is set to l.
current position
is from positioning-mode if it is supplied; otherwise, it is approximate mode.positioning mode
is determined as follows for generic searches:
IF length-word.<0:7> <> 0
THEN length-word.<0:7>
compare length
ELSE
IF length-word.<8:15> > length of key-specifier
THEN length of key-specifier
ELSE length-word.<8:15>
• Positioning to the middle of a duplicate alternate key
Positioning with an alternate key is usually done by giving the alternate key value you want.
This always positions the file to the first record of the set of records that contains duplicates
of the specified alternate key value.
To position to an arbitrary record within the set of duplicate records, you can specify a
key-value consisting of the alternate key value concatenated with the primary key value of
the desired record within the set, and specify the key-length as the sum of the alternate
key length and the primary key length (except for insertion-ordered keys).
KEYPOSITION[X] Procedures (Superseded by FILE_SETKEY_ Procedure) 753