LOCATE

The LOCATE statement finds the position of an element within a specified dimension of a dynamic array.

 

COMMAND SYNTAX

LOCATE expression1 IN expression2{<expression3{,expression4}>}, {,expression5} {BY expression6} SETTING Var THEN|ELSE statement(s)

LOCATE(expression1, expression2{,expression3{,expression4}}; Var; expression6) THEN|ELSE statements

 

SYNTAX ELEMENTS

expression1 evaluates to the string that will be searched for in expression2.
expression2 evaluates to the dynamic array within which expression1 will be searched for.
expression3 and expression4, when specified, cause a value or subvalue search respectively.
expression5 indicates the field, value or subvalue from which the search will begin.
BY expression6 causes the search to expect the elements to be arranged in a specific order, which can considerably improve the performance of some searches. The available string values for expression6 are:

AL Values are in ascending alphanumeric order
AR Values are in right justified, then ascending order
AN Values are in ascending numeric order
DL Values are in descending alphanumeric order
DR Values are in right justified, then descending order
DN Values are in descending numeric order

Var will be set to the position of the Field, Value or Sub-Value in which expression1 was found if indeed, it was found. If it was not found and expression6 was not specified then Var will be set to one position past the end of the searched dimension. If expression6 did specify the order of the elements then Var will be set to the position before which the element should be inserted to retain the specified order.

The statement must include one of or both of the THEN and ELSE clauses. If expression1 is found in an element of the dynamic array the statements defined by the THEN clause are executed. If expression1 is not found in an element of the dynamic array the statements defined by the ELSE clause are executed.

 

NOTES

See also FIND, FINDSTR

 

EXAMPLES

Name = "Nelson"
LOCATE Name IN ForeNames BY "AL" SETTING Pos ELSE
    INS Name BEFORE ForeNames<Pos>
END

jBC