BASICBASIC statementskey statement

key statement

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.

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 non-null item-ID is passed, then this operation is identical to the p operator.
  • 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.
  • If the item-ID is passed as null, then the first item-ID that matches the passed index key is returned.

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.
  • 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 non-null, then the list for the next key is returned.
  • If the data is multivalued, then the item-ID list can contain duplicate item-IDs.

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:

  • If the vc.exp parameter is specified and equals 0, then no corresponding value numbers are returned.
  • If the vc.exp parameter is specified and does not equal 0, then the corresponding value numbers are returned.
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.

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

See also

Cruising and zooming commands, root statement, then/else statement blocks, verify-index command

Parent topic: BASIC statements