|
The KEY statement allows an application to scan an alternate key index.
Format
KEY(operator, scan.var, index.key, item.id)
{THEN statement(s)}
{ELSE statement(s)}
where
| operator | identifies the operation to be performed. |
| scan.var | is a data collection variable returned by earlier use of the ROOT statement. Applications should make no assumptions about the content of this variable as it may change in future releases. |
| index.key | is a variable containing the indexed value to be found. It is updated by some index operations. |
| item.id | is returned as the id of the record found. |
The brackets around the statement arguments are optional in the QM implementation of KEY. The vc.expr argument in the D3 implementation of KEY is not available in QM.
At least one of the THEN and ELSE clauses must be present. The THEN clause will be executed if the action is successful. The ELSE clause will be executed if the action fails. Use of the STATUS() function will return the error code.
The ROOT and KEY statements are provided to ease migration to QM from other multivalue products. New developments should preferably use the SETLEFT and SELECTRIGHT statements.
The case insensitive operator codes and their actions are:
| C | Scans left to right for the first item with an indexed value equal to or beyond index.key. The index.key variable is updated to be the actual indexed value and item.id is set to the record id of the first record with this indexed value. |
| L | If index.key is a null string, returns the indexed value and last record id for the rightmost index entry. For a non-null index.key this operator is identical to the P operator described below. |
| N | Returns index.key and item.id as the next index entry beyond the supplied index.key and item.id. |
| P | Returns index.key and item.id as the next index entry before the supplied index.key and item.id. |
| R | Returns index.key and first item.id for an exact match with the supplied index.key. |
| V | Verifies that an index entry that is an exact match for the supplied index.key and item.id exists. |
| X | Returns item.id as a field mark delimited list of record ids for which the indexed value is index.key. |
Example
ROOT 'SALES', 'ITEM' TO IDX ELSE STOP 'Cannot find index'
VALUE = ''
ID = ''
LOOP
KEY 'N', IDX, VALUE, ID ELSE EXIT
DISPLAY VALUE, ID
REPEAT
The above program fragment scans the ITEM index in the SALES file, producing a simple report showing the indexed value (product code) and record id (order number) for each index entry.
See also:
Alternate key indices, ROOT, SETLEFT, SELECTRIGHT
| 
