Caché MultiValue Basic Reference
FIND
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Finds an element of a dynamic array by exact value.
Synopsis
FIND data IN dynarray SETTING f[,v[,s]] [THEN statements] [ELSE statements]
Arguments
data The data value of an element. This value must be the complete value of the element.
dynarray Any valid dynamic array.
f A variable that receives an integer denoting the Field level of the dynamic array where the element data was found. Fields are counted from 1.
v Optional — A variable that receives an integer denoting the Value level of the dynamic array where the element data was found. Values are counted from 1 within a Field.
s Optional — A variable that receives an integer denoting the Subvalue level of the dynamic array where the element data was found. Subvalues are counted from 1 within a Value.
Description
The FIND statement locates the data value in a dynamic array and returns its location by setting the f, v, and s variables to integers. For example, if data is located in the third Value of the second Field, FIND sets f=2 and v=3.
The data value must be an exact match with the full value of an element in dynarray. It cannot be a substring of an element value. Matching is case-sensitive. If data does not match an element value, f, v, and s are unchanged and retain their previous values.
The f, v, and s arguments accept a single dynamic array reference (A<i>), a single substring reference (A[s,l]), or a substring reference nested inside a dynamic array reference (A<i>[s,l]).
You can optionally specify a THEN clause, an ELSE clause, or both a THEN and an ELSE clause. If data is located in dynarray, the THEN clause is executed. If data is not located in dynarray, the ELSE clause is executed. The statements argument can be the NULL keyword, a single statement, or a block of statements terminated by the END keyword. A block of statements has specific line break requirements: each statement must be on its own line and cannot follow a THEN, ELSE, or END keyword on that line.
The FIND statement returns the f, v, and s position of a dynamic array element by specifying the element's exact value. The FINDSTR statement returns the f, v, and s position of a dynamic array element by specifying a substring found in that element. The EXTRACT function returns the value of a dynamic array element by specifying its f, v, and s position.
You can use the <> operator or the REPLACE function to replace an element value in a dynamic array based on position. For further details, see the Dynamic Arrays page of this manual.
Examples
The following example uses the FIND statement to find the second value from the first field of a dynamic array:
cities="New York":@VM:"London":@VM:
"Chicago":@VM:"Boston":@VM:"Los Angeles"
FIND "London" IN cities SETTING v,f,s
PRINT v,f,s
See Also