Searches for a record in a table referenced in JSDO memory and returns a reference to that record if found. If no record is found, it returns null.

Return type: progress.data.JSRecord class

Applies to: progress.data.JSDO class, table reference property (JSDO class)

Working record: After completing execution, any record found becomes the working record for the associated table. If the searched table has child tables in the same multi-table resource, and the useRelationships property is true, the working record of the result set for each child is set to the first record as determined by the relationship to its respective parent. If a record is not found, the working record is not set, and the working records of any child tables are also not set.

Syntax

jsdo-ref.find ( funcRef )
jsdo-ref.table-ref.find ( funcRef )
jsdo-ref
A reference to the JSDO. You can call the method on jsdo-ref if the JSDO has only a single table reference.
table-ref
A table reference on the JSDO.
funcRef
A reference to a JavaScript callback function that returns a boolean value and has the following signature:

Syntax:

function [ func-name ] ( jsrecord-ref )

Where func-name is the name of a callback function that you define external to the find( ) parameter list and jsrecord-ref is a JSRecord reference to the next available record on the specified table reference. You can then pass func-name to the find( ) method as the funcRef parameter. Alternatively, you can specify funcRef as the entire inline function definition without func-name.

The find( ) method executes your funcRef callback for each record of the table reference, until it returns true, indicating that the callback has found the record. You can then test the field values on the data property of jsrecord-ref to determine the result. Otherwise, your callback returns false and the find( ) method executes the callback again on the next available record.

If your funcRef callback finds the record, find( ) completes execution with both its return value and the record property of the associated table reference set to the JSRecord reference of the found working record. If find( ) reaches the end of the available records without funcRef returning true, find( ) completes execution with both its return value and the record property on the table reference set to null, indicating that the sought for record was not found.

If the associated table reference is for a child table in a multi-table resource, if the useRelationships property is true, find( ) uses the relationship to filter out all but the child records of the working record in the parent table. However, if the working record of the parent is not set, find( ) throws an error. If useRelationships is false, the search includes all records of the child table and no error is thrown.

Example

In following code fragment, jsdo references a single customer table: 

var jsdo = new progress.data.JSDO( 'customer' );

jsdo.find(function(jsrecord) {
  return (jsrecord.data.CustNum == 10);
});

The inline function passed to find( ) returns true or false based on the value of the CustNum property of the object returned by the data property for the currently available JSRecord reference.

See also:

data property, foreach( ) method, record property