The key statement locates an item using a B-tree index key and returns the item in a variable. This provides the ability to sequentially search the items in the file based on the index.
key(’operator’, root.var, index.key, item-ID{,vc.exp}) {then|else statement.block}
operator | Must be enclosed in single quotes and indicates the type of index search to use, and can be one of these: | |
c | Compares, left-to-right, against the index key and returns the first item-ID whose index
matches into item-ID.
|
|
l | Returns the last partial key.
|
|
n | Returns the next index key and item-ID.
After all item-IDs for an index key have been returned, it returns the next index key and item-ID. |
|
p | Returns the previous index key and item-ID.
|
|
r | Returns the index key and item-ID only on an exact match with the index key. | |
v | Verifies the index. Locates the given index key and item-ID and verifies that an exact match can be found. | |
x | Returns all item-IDs that exactly match the passed key.
The vc.exp parameter, if present, returns the number of elements found with an original value position not equal to 1. If the vc.exp parameter is specified on input, then the item-ID on output is affected as follows:
|
|
root.var | Indicates the B-tree root FID associated with the target index.
It must be initialized by the root statement and must be defined prior to using the key statement. |
|
index.key | Specifies a mandatory variable containing the search string.
The variable must be defined before using the key statement. The actual string found is returned into the variable when using the c, n, or p operators. The r and v operators expect an exact match. The index.key variable is used as a pair with the item.ID variable. These are the input and output parameters that specify the starting position within the index. |
|
item-ID | Indicates the variable that is assigned the item-ID of the item
that contains the key. The item-ID need not be preassigned when using the p or n operators, but must be preassigned when using the v operator. The item.ID variable is used as a pair with the index.key variable. These are the input and output parameters that specify the starting position within the index. |
|
vc.exp | Indicates the value number of the key attribute containing the index key, returned to the value count expression by the key statement. This only works with the c, n, p, and r operators. | |
then | The then clause is executed if the item-ID is found or if the index key verifies with the v operator. | |
else | The else clause is executed if the item-ID is not found or if the index key does not verify with the v operator. |
The root statement must precede the key statement. Although the root statement does not require it, it is highly recommended to use the then/else clause since using the key statement on an invalid root variable will cause a runtime abort.
In the root statement, employee is the file that contains the predefined index. If the index is found, the root FID is assigned to the variable e.root.
In the key statement, n indicates that the next matching string is to be located. e.key is the variable that contains the search string and item-ID is the variable to which the actual item-ID is assigned, if it is found.
employee.index =’a5’; * phone number attribute execute "create-index employee ":employee.index root ’employee’,employee.index to e.root else print "the index ":employee.index:" not found" end print "Enter phone number to match ": input e.key key(’n’,e.root,e.key,item-ID) then print item-ID