Guardian Procedure Calls Reference Manual

• KEYPOSITION and file-system error 21
If any of these conditions are true, error 21 is returned by KEYPOSITION:
◦ If the primary file is a key-sequenced file and one of these is true:
key-specifier is omitted or 0 and key-length is greater than the key length
defined for the primary file.
–
– compare-length is greater than key-length.
◦ If the key-specifier is not zero and one of these is true:
– key-length is greater than the sum of length of the alternate-key field and the
length of the primary key of the file.
– key-length is less than or equal to the length of the alternate-key field, and
compare-length is greater than key-length.
– key-length is greater than the length of the alternate-key field and the primary
file is not key-sequenced, and the difference of key-length and compare-length
is less than 4.
– key-length is greater than the length of the alternate-key field and the primary
file is not key-sequenced, and the key-length is less than the sum of the length of
the alternate-key field and the length of the primary key of the file.
• KEYPOSITIONX error
In addition to the errors returned from KEYPOSITION, error 22 is returned from KEYPOSITIONX
in either of these cases:
◦ the address of the key-value parameter is extended, but no segment is in use at the
time of the call or the segment in use is invalid.
◦ the address of the key-value parameter is extended, but it is an absolute address and
the caller is not privileged.
• Queue Files
To read a queue file in last-in, first-out order, set positioning-mode<0:2> : = 3. There
are no alternate keys for queue files; the key-specifier parameter must be 0 or omitted.
When using approximate or generic positioning, the compare-length and key-length
parameters must exclude the trailing 8 bytes of the record, because this field contains a
system-generated timestamp. Consequently, length-word is typically used with queue files.
• Increased key limits for format 2 key-sequenced files are not supported
The KEYPOSITION[X] procedures do not support the increased key limits for format 2
key-sequenced files (in H06.28/J06.17 RVUs with specific SPRs and later RVUs) because they
cannot handle keys greater than 255 bytes in length. This limitation is the result of the two
1-byte length fields passed to the procedures in the 2-byte length-word parameter. The left
byte contains a compare-length value, and the right byte contains a key-length value.
An FEINVKEY (46) error is returned if the key-specifier parameter designates a primary
or secondary key with a length greater than 255 bytes.
Example
KEY ':=' "BROWN";
COMPARE^LEN := 5;
CALL KEYPOSITION ( INFILE , KEY , , COMPARE^LEN );
756 Guardian Procedure Calls (H-K)