LOCATE statement

Syntax (IDEAL, REALITY)

LOCATE expression IN dynamic.array [ < field# [ ,value#] > ] [ 
,start] [BY seq] SETTING variable {THEN statements [ELSE statements] | ELSE statements}

Syntax (PICK)

LOCATE (expression, dynamic.array [ ,field# [ ,value#] ] ; variable [ 
;seq] )
 {THEN statements [ELSE statements] | ELSE statements}

Syntax (INFORMATION)

LOCATE expression IN dynamic.array < field# [ ,value# [ ,subvalue#] 
] > 
 [BY seq] SETTING variable {THEN statements [ELSE statements] | ELSE statements}

Description

Use a LOCATE statement to search dynamic.array for expression and to return a value indicating one of the following:

  • Where expression was found in dynamic.array
  • Where expression should be inserted in dynamic.array if it was not found

The search can start anywhere in dynamic.array.

expression evaluates to the string to be searched for in dynamic.array. If expression or dynamic.array evaluate to the null value, variable is set to 0 and the ELSE statements are executed. If expression and dynamic.array both evaluate to empty strings, variable is set to 1 and the THEN statements are executed.

field#, value#, and subvalue# are delimiter expressions, specifying:

  • Where the search is to start in dynamic.array
  • What kind of element is being searched for

start evaluates to a number specifying the field, value, or subvalue from which to start the search.

In the IDEAL and PICK syntaxes the delimiter expressions specify the level of the search, and start specifies the starting position of the search. In INFORMATION syntax the delimiter expressions specify the starting position of the search.

If any delimiter expression or start evaluates to the null value, the LOCATE statement fails and the program terminates with a run-time error message.

variable stores the index of expression. variable returns a field number, value number, or a subvalue number, depending on the delimiter expressions used. variable is set to a number representing one of the following:

  • The index of the element containing expression, if such an element is found
  • An index that can be used in an INSERT function to create a new element with the value specified by expression

During the search, fields are processed as single-valued fields even if they contain value or subvalue marks. Values are processed as single values, even if they contain subvalue marks.

The search stops when one of the following conditions is met:

  • A field containing expression is found.
  • The end of the dynamic array is reached.
  • A field that is higher or lower, as specified by seq, is found.

If the elements to be searched are sorted in one of the ascending or descending ASCII sequences listed below, you can use the BY seq expression to end the search. The search ends at the place where expression should be inserted to maintain the ASCII sequence, rather than at the end of the list of specified elements.

Use the following values for seq to describe the ASCII sequence being searched:

"AL" or "A"
Ascending, left-justified (standard alphanumeric sort)
"AR"
Ascending, right-justified
"DL" or "D"
Descending, left-justified (standard alphanumeric sort)
"DR"
Descending, right-justified

seq does not reorder the elements in dynamic.array; it specifies the terminating conditions for the search. If a seq expression is used and the elements are not in the sequence indicated by seq, an element with the value of expression might not be found. If seq evaluates to the null value, the statement fails and the program terminates.

The ELSE statements are executed if expression is not found. The format of the ELSE statement is the same as that used in the IF...THEN statement.

Use the INFO.LOCATE option of the $OPTIONS statement to use the INFORMATION syntax in other flavors.

If NLS is enabled, the LOCATE statement with a BY seq expression uses the Collate convention as specified in the NLS.LC.COLLATE file to determine the sort order for characters with ascending or descending sequences. The Collate convention defines rules for casing, accents, and ordering.

IDEAL, REALITY, and PICK Syntax

The following sections describe the three possible outcomes from the different uses of delimiter expressions in the IDEAL, REALITY, and PICK versions of the LOCATE statement.

Case 1:
If field# and value# are omitted, the search starts at the first field in dynamic.array.
Case 2:
If only field# is specified and it is greater than 0, the search starts at the first value in the field indicated by field#. If field# is less than or equal to 0, both field# and value# are ignored.
Case 3:
If both field# and value# are specified, the search starts at the first subvalue in the value specified by value#, in the field specified by field#. If field# is greater than 0, but value# is less than or equal to 0, LOCATE behaves as though only field# is specified.

If a field, value, or subvalue containing expression is found, variable returns the index of the located field, value, or subvalue relative to the start of dynamic.array, field#, or value#, respectively (not the start of the search). If a field, value, or subvalue containing expression is not found, variable is set to the number of fields, values, or subvalues in the array plus 1, and the ELSE statements are executed.

INFORMATION Syntax

When you use the INFORMATION flavor syntax of LOCATE, three outcomes can result depending on how the delimiter expressions are used. The results are described as case 1, case 2, and case 3.

Case 1:
If both value# and subvalue# are omitted or are both less than or equal to 0, the search starts at the field indicated by field#.
Case 2:
If subvalue# is omitted or is less than or equal to 0, the search starts at the value indicated by value#, in the field indicated by field#. If field# is less than or equal to 0, field# defaults to 1.
Case 3:
If field#, value#, and subvalue# are all specified and are all nonzero, the search starts at the subvalue indicated by subvalue#, in the value specified by value#, in the field specified by field#. If field# or value# are less than or equal to 0, they default to 1.

If a field, value, or subvalue containing expression is found, variable is set to the index of the located field relative to the start of dynamic.array, the field, or the value, respectively (not the start of the search).

If no field containing expression is found, variable is set to the number of the field at which the search terminated, and the ELSE statements are executed. If no value or subvalue containing expression is found, variable is set to the number of values or subvalues plus 1, and the ELSE statements are executed.

If field#, value#, or subvalue# is greater than the number of fields in dynamic.array, variable is set to the value of field#, value#, or subvalue#, respectively, and the ELSE statements are executed.

Examples

The examples show the IDEAL and REALITY flavor LOCATE statement. A field mark is shown by F, a value mark is shown by V, and a subvalue mark is shown by S.

Q='X':@SM:"$":@SM:'Y':@VM:'Z':@SM:4:@SM:2:@VM:'B':@VM
PRINT "Q= ":Q
LOCATE "$" IN Q <1> SETTING WHERE ELSE PRINT 'ERROR'
PRINT "WHERE= ",WHERE
LOCATE "$" IN Q <1,1> SETTING HERE ELSE PRINT 'ERROR'
PRINT "HERE= ", HERE
NUMBERS=122:@FM:123:@FM:126:@FM:130:@FM
PRINT "BEFORE INSERT, NUMBERS= ",NUMBERS
NUM= 128
LOCATE NUM IN NUMBERS <2> BY "AR" SETTING X ELSE
NUMBERS = INSERT(NUMBERS,X,0,0,NUM)
PRINT "AFTER INSERT, NUMBERS= ",NUMBERS
END

This is the program output:

Q= XS$SYVZS4S2VBV
ERROR
WHERE= 5
HERE=  2
BEFORE INSERT, NUMBERS= 122F123F126F130FAFTER INSERT, NUMBERS=  122F128F123F126F130F
Parent topic: BASIC Statements and Functions