basic.key Statement/BASIC Program

basic.key

Command basic.key Statement/BASIC Program
Applicable release versions: AP, AP 6.2, AP 6.1
Category BASIC Program (486)
Description provides the ability to sequentially "cruise" on any defined b-tree index for an item-id.

The "root" statement must precede the "key" statement.

The "operator" indicates the type of index search to use, and may be one of the following choices:

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.

l Returns the last partial key. If a non-null "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 which still matches the passed key. This feature is only available in releases 6.1.0 and greater.

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, or if the "item.id" is null, 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, this returns the previous "item.id". 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 Works like the "n" option, but returns ALL item-id's matching the given key as a dynamic array. 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. The vc.expression, if present, returns the number of elements found with an original value position not equal to 1. If vc.expression is non-zero, then the item-id list may contain duplicate item-id's. Available in releases of AP 6.2 and higher.

root.variable is 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.

item.id is 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.

vc.expression is the value number of the key attribute containing the "index.key", returned to the "vc.expression" by the "key" statement. This only works with the 'c', 'n', 'p' and 'r' operators.

The "then" clause is executed if the item-id is found or if the "index.key" verifies with the "v" operator.

The "else" clause is executed if the item-id is not found or if the "index.key" does not verify with the "v" operator.

See the "then/else construct" for an explanation on the use of "then" and "else" clauses in statements that allow or require them.
Syntax key('operator', root.variable , index.key, item.id {, vc.expression} ) {then | else statement.block}
Options
Example
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

In the "root" statement, "employee" is the file that 
contains the pre-defined 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 which contains the search string and "item.id" is the 
variable to which the actual item-id will be assigned, if it is found.
Purpose
Related basic.then/else.construct
cruising
tcl.verify-index
basic.root