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.

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])

• By search string, if the searchstring parameter is specified (with the optional format and casesensitive parameters)

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:

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));

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:

Specifies a string expression. It enables wildcard searches. The following wildcards are allowed:

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:

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

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:

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.

Used only when searchstring is also specified. Specifies whether string comparisons against the search string parameter are case‑sensitive

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.

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