Programming Guide : Working with Arrays, Table Fields, and Collections : Arrays : How You Can Find Values in an Array
 
Share this page          
How You Can Find Values in an Array
The Find method can locate an element of the array based on the contents of a single attribute of the array's class. The syntax for this method is:
status = ArrayObject.find(attributename = string,
             value = expression | searchstring=string
            [,format = string]  [,casesensitive = integer]
            [,rownumber = byref (integer_variable),
            [,usedeleted = integer] [,startrow =integer]
            [,endrow=integer])
attributename
Specifies the attribute being searched for. Attributes can be of any simple data type, such as varchar or integer. The Find method inspects the object's Value attribute if the attribute is an object of one of the following types:
DateObject
FloatObject
IntegerObject
MoneyObject
StringObject
Other object types are permissible for this parameter, but only for a search by exact value. When you use the Find method to locate a value in an array that has no named attributes, the attributename should be set to 'value'. For an example of using the Find method in conjunction with a pop-up frame that lets the user specify the search conditions, see How You Can Scroll Indirectly with the Find Method.
For more information about the Value attribute of these object types, see the Language Reference Guide.
There are two ways of finding specific rows in an array:
By value, using value = expression
When you specify an expression whose type is compatible with the specified attribute, the Find method searches for an exact match between this expression and the specified attribute.
Numeric values always fall into this category.
By searchstring, using searchstring = expression
When you specify a string expression (and optional format), the Find method searches for a match between the string and specified attribute, converting the attribute's value to a string using the specified (or a default) format.
The searchstring parameter lets you use any of three wildcard characters:
% (percent sign)—represents a character string, possibly a null string
_ (underscore)—represents exactly one character
\ (backslash)—represents the escape character
The following table provides an example of string matching:
Actual
String
Search
Strings
 
 
 
 
abc
%abc
\%abc
%abc%
_abc
Abc
matches
matches
 
matches
 
1abc2
 
 
 
matches
 
%abc
 
matches
matches
matches
matches
Aabc
 
matches
 
matches
matches
The format parameter can be any of the legal OpenROAD format templates for the attribute type for which you are searching. For a list of the format templates, see the Workbench User Guide. For more information about specifying the format parameter, see the Language Reference Guide. If the format attribute is omitted, the default format is used for the specified attribute type.
If the Find method finds a row, the rownumber parameter (if specified) is set to the row number of the found row. Table fields displaying the array are not automatically scrolled to the row found. To move the input focus to this row, you must write your own 4GL code, using SetInput Focus method on the table field.
The other parameters for the Find method are:
casesensitive
Specifies whether case is significant
Default: TRUE
usedeleted
Specifies whether to search through deleted rows
Default: FALSE
startrow
Always specifies a positive number unless usedeleted is TRUE, in which case startrow defaults to array.FirstRow
Default: 1
Endrow
Always specifies a positive number unless usedeleted is TRUE. If endrow is less than startrow, the search wraps
Default: array.LastRow
The value of status is one of the following:
ER_OK
Specifies that the row was found
ER_ROWNOTFOUND
Specifies that the row was not found
ER_FAIL
Specifies that the search failed. Failure is caused problems such as attempting to compare incompatible data types or specifying incorrect attributes.