key Statement

The key statement locates an item using a B-tree index key, and returns the item in a variable, providing the ability to sequentially search the items in the file based on the index.

Syntax

key(’operator’, root.var , index.key, item-ID {, vc.exp}) {then|else statement.block}

Parameter(s)

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. If no match is found, the next sequentially higher index and first associated item-ID are returned. If the item-ID is passed as null, then this returns the first item-ID that matches the passed index key.
	l	Returns the last partial key. If a nonnull item-ID is passed, then this operation is identical to the p operator. However, if a null item-ID is passed, then this function returns the highest valued key in the index that still matches the passed key.
	n	Returns the next index key and item-ID. If more than one item-ID exists for an index key, this returns the next item-ID. After all item-IDs for an index key have been returned, it returns the next index key and item-ID. If the item-ID is passed as null, then the first item-ID that matches the passed index key is returned.
	p	Returns the previous index key and item-ID. If more than one item-ID exists for an index key, the previous item-ID is returned. After the first item-ID for an index key has been returned, or if item-ID is null, it returns the previous index key and the last 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. If no match is found, then it returns all matching IDs for the next key. If the passed item-ID is null, then the data for the passed key is returned. If the passed item-ID is nonnull, then the list for the next key is returned. The value count expression, if present, returns the number of elements found with an original value position not equal to 1. If vc.exp is nonzero, then the item-ID list can contain duplicate item-IDs.
root.var	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	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	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.

Example(s)

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