LOCATE Statement

Finds the location within a dynamic array of an attribute, value or subvalue that exactly matches the result of an expression:

Syntax

LOCATE searchExpr IN dynArray{<attr# {,value#}>}{,start#} {BY sequence} SETTING settingVar [THEN statement(s) | ELSE statement(s)]

LOCATE(searchExpr,dynArray{,attr#{,value#{,start#}}};settingVar{;sequence}) [THEN statement(s) | ELSE statement(s)]

Syntax Elements

searchExpr An expression that evaluates to the string or value to be located. This must not contain attribute marks, carets (^) or brackets ([, ]).

dynArray The dynamic array to be searched.

attr# The number of the attribute to search within dynArray.

value# The number of the value to search within the specified attribute.

start# The attribute, value or subvalue where the search begins. Default, 1.

Note

When using the second form of the LOCATE statement, if you specify start#, you must also specify attr# and value#. To search attributes in the array, specify attr# = 0 and value# = 0. Similarly, to search values within an attribute, specify value# = 0.

settingVar The name of a variable that will be assigned the value of the position of the string or value being searched for.

sequence Specifies that the elements in the dynamic array have been sorted. Must be one of the following string values:

"AL" Ascending, left-aligned (standard alphanumeric sort).

"AR" Ascending numeric sort.

"DL" Descending, left-aligned (standard alphanumeric sort).

"DR" Descending numeric sort.

Note

  • The sequences AR and DR are intended for numeric data only. How the system handles right-aligned non-numeric data is undefined and consistency of operation cannot be guaranteed.

    This behaviour can be changed with the RT.LOCATE compatibility option.

  • If keyword case-insensitivity is selected, this parameter can be in any combination of upper or lower case. Otherwise, it must be upper case.

statement(s) A THEN or ELSE clause (or both). A statement must be included. The THEN clause is executed if the string or value is found. Otherwise the ELSE clause is executed.

Return Value

On return, settingVar will contain the number of the attribute, value or subvalue containing searchExpr, depending on whether attributes, values or subvalues were searched.

If searchExpr is not found, the value returned depends on whether BY sequence was specified:

Operation

If attr# is not specified, an attribute search takes place with start# specifying the attribute where the search begins. This allows you to skip over unwanted attributes. A value of 1, or not specifying start#, searches the entire dynamic array.

If attr# is specified and value# is not specified, a multivalue search of the attribute takes place with start# specifying the multivalue where the search begins. A value of 1, or not specifying start#, searches the entire attribute.

When searching values, searchExpr must not contain any value marks.

If both attr# and value# are specified, a subvalue search occurs, within the specified multivalue, that is contained inside the specified attribute. The start# refers to the subvalue mark where the search is to begin. searchExpr cannot contain any subvalue marks.

Note

If start# is greater than the number of elements specified, settingVar will be set to this number. If used with a dynamic array insertion, the value is placed at this position with null attributes, values or subvalues in between.

Case Insensitivity

If data case insensitive mode is selected (see Case Sensitivity), case is ignored when searching dynArray for searchExpr.

Example 1

LOCATE "CALIF" IN DA SETTING POS ELSE PRINT 'NO "CALIF"';STOP

Locates attribute with string value CALIF in dynamic array DA, starting the search with the first attribute. If "CALIF" is not found, error message is printed. If "CALIF" is found, POS is set to a value indicating the position of the attribute in DA.

Example 2

ITEM = "24^RESISTOR^243]523]311]10]3"
A = 10
LOCATE A IN ITEM<3>,2 SETTING K ELSE PRINT "NOT FOUND"; STOP

Locates a multivalue equal to 10 in the third attribute of dynamic array ITEM. Search begins with the second multivalue. K is set to 4, as 10 is the fourth value in that attribute.

Example 3

I=3
A=2
V=5
PRINT "ENTER QTY TO DELETE":
INPUT QTY
LOCATE QTY IN ARRAY(I)<A,V> SETTING J ELSE PRINT "QTY NOT FOUND"; STOP
DEL ARRAY(I)<A,V,J>

Prompts for terminal input, then locates the subvalue QTY in the second attribute and the fifth multivalue in the dynamic array assigned to the third element of ARRAY. Scanning begins with the first subvalue. J is set to a value indicating the position of the value of QTY. If found, it is deleted; otherwise, the message is printed.

Example 4

DEPT="PERSNL"
LOCATE DEPT IN ITEM<2> BY "AL" SETTING X ELSE 
  INS DEPT BEFORE ITEM<2,X>
END

Locates multivalue PERSNL in second attribute of dynamic array ITEM. The multivalues in the second attribute are sorted in ascending order, left-aligned. If the value of DEPT (PERSNL) is not found, it is inserted in the proper order, as defined by X. For example, if ITEM=19^ACCT]ENG]PROD^12]6, it would now be 19^ACCT]ENG]PERSNL]PROD^12]6.

Example 5

INFO=22^76^24]523]21^9]7\4\54
LOCATE(76,INFO;K) ELSE PRINT "NOT THERE"; STOP

Searches dynamic array INFO for 76. Returns 2, because 76 was found in the second attribute.

Example 6

INFO=22^76^24]523]21^9]7\4\54
LOCATE 54 IN INFO<4,2> SETTING K ELSE PRINT "NOT FOUND"; STOP

Searches all subvalues within attribute 4, value 2 and returns a 3.

Example 7

INFO=22^76^24]523]21^9]7\4\54
LOCATE(523,INFO,3;K) ELSE GOTO 10

Searches values in attribute 3 and returns 2.

See Also

FIND statement, FINDSTR statement.