Find Method
The Find method can locate an element of the array based on the contents of a single attribute of the objects in the array. It lets you find a row with a specified value quickly.
This method has the following syntax:
status = ArrayObject.find([attributename = string,
value = expression] |
[attributename = string, searchstring = string
[, format = string] [, casesensitive = integer]]
[, rownumber = byref(integer_variable)]
[, usedeleted = integer] [, startrow = integer]
[, endrow = integer])
The find method provides two different ways to perform a find:
• By value, if the value parameter is specified
• By search string, if the searchstring parameter is specified (with the optional format and casesensitive parameters)
This method has the following parameters:
attributename
Specifies the attribute that is being searched for. The attribute can be of any supported datatype, including system class and user class object datatypes.
To match object-datatype attributes, specify a reference to the target object as the value parameter. If that object is referenced in the array, the find will succeed. The following example searches an array of frameexecs and finds the first frame whose parentframe is the current frame:
status = frames.Find(attributename='parentframe', value=curframe,
rownumber=Byref(indx));
If the attribute is an object of type DateObject, FloatObject, IntegerObject, MoneyObject, or StringObject, this method also allows you to compare the contents of the object by setting the value or searchstring parameter to match the object's Value attribute. The following example searches an array of fields and finds the first field that contains code:
status = fields.Find(attributename='script', searchstring='%_%',
casesensitive=FALSE, rownumber=Byref(indx));
value
Specifies an expression that evaluates to a type compatible with the specified attribute. The Find method searches for an exact match between the expression and the attribute's value.
For example, assume that the arr array has two attributes (Int of type integer and Dat of type date). The following call to the Find method locates a row whose Int attribute has a value equal to that in the integer_var variable:
status = arr.Find(attributename = 'Int',
value = integer_var, rownumber = byref(row_num));
searchstring
Specifies a string expression. It enables wildcard searches. The following wildcards are allowed:
• % (percent) represents any number of characters, including a possibly empty set.
• _ (underscore) represents exactly one character.
• \ (backslash) is used as the escape character.
Note: If the searchstring itself includes backslash characters, these must be doubled to prevent the backslash being interpreted as a special character. For example, if searching for a particular folder or file names in an array of StringObjects containing file names from different folders, the names may include backslash characters. If the searchstring is specified as 'C:\TEMP\%' for example, it will fail; the searchstring must be specified instead as 'C:\\TEMP\\%'.
For example, the following call to the Find method provides a search string that uses a wildcard to locate a value in the Int attribute:
status = arr.Find(attributename = 'Int',
searchstring = '%123%',
rownumber = byref(row_num));
The preceding statement finds the first row whose Int attribute contains a numeric value that, when converted to a string, contains the string "123". The following values, for example, would be located: 12345, 98123, 9812345.
When including a searchstring parameter, you also may specify format and casesensitive.
When specifying a searchstring with an attributename, each of the field's attribute values is converted to a string using either the default format for the datatype or the format you supply. A comparison is then performed to check whether the formatted string matches the provided searchstring.
format
Used only when searchstring is also specified. Specifies any of the data format templates described in the Workbench User Guide and allowed as an EntryField's FormatString attribute. However, the template must correspond to the attribute type specified in the attributename parameter. If searchstring is specified but format is omitted, OpenROAD chooses a default format template according to the attribute's type.
For example, the following call to the Find method provides both a search string and a format to locate a value in the Dat attribute:
status = arr.Find(attributename = 'Dat',
searchstring = '%JU%',
format = '-d"FEBRUARY 03, 1901"',
rownumber = byref(row_num));
In the preceding example, the Find method converts the date value of the Dat attribute to a string according to the format template defined in the format parameter. The statement finds any date in June or July.
Valid values for the format parameter depend on the data type of the attribute being searched. An EntryField's FormatString attribute represents a valid value for the format parameter. For a description of how to set format templates, see the Programming Guide.
casesensitive
Used only when searchstring is also specified. Specifies whether string comparisons against the search string parameter are case‑sensitive
Default: TRUE
usedeleted
Specifies whether deleted rows are searched
Default: FALSE
startrow
Must be positive unless usedeleted = TRUE. This parameter defaults to 1 if usedeleted = TRUE is not specified. Otherwise, it defaults to the value of arrayobject.FirstRow.
endrow
Must be positive unless usedeleted = TRUE. This parameter defaults to the last row of the array object. If endrow is less than startrow, the search wraps.
Any table field displaying the array is not automatically scrolled to the found row. To force the table field to scroll, use the SetInputFocus method on the table field.
The Find method returns ER_OK if a row was found, ER_ROWNOTFOUND if the row was not found, and ER_FAIL if the find operation failed. Failure is caused by such problems as attempting to compare incompatible data types, specifying incorrect attributes, or failing to double any backslash characters that are part of the searchstring text. Descriptions of system constant values and their numeric equivalents are listed in
Error Codes.
If the Find method fails, it writes a message to the Trace window. On all platforms, the message is additionally written to the log file (%II_SYSTEM%\ingres\files\w4gl.log).
If the rownumber parameter is used to locate a row and the row is found, the integer variable that is associated with the rownumber parameter and passed byref, is set to the number of the row found.
For more complicated examples of using the Find method and an example of using the Find method generically, see "How You Can Find Values in an Array" in the Programming Guide.