| Pick/BASIC | Index Level | LE |
| Syntax | KEY('operator', root.variable , index.key, item.id {, vc.expression} ) {THEN | ELSE statement.block} |
| Category | BASIC |
| Type | Statement |
| Description |
Locates an item using a b-tree index key, and returns the item in a variable, providing the ability to sequentially "cruise" on the items in the file based on the index.
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 release 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, it returns the next "index.key" and "item.id". If the "item.id" is passed as null, then this returns the first "item.id" which matches the passed "index.key". 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 Returns all the item id's exactly matching 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. 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 7.0 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. |
| Options | |
| See Also | THEN | ELSE statement.block cruising verify-index ROOT |
| 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. |
| Warnings | |
| Compatibility | D3 7.0 AP AP 6.1 |
| Pick/BASIC | Index Level | LE |