How You Can Find Values in an Array

6. Working with Arrays, Table Fields, and Collections : Arrays : How You Can Find Values in an Array

Share this page

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 (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.