Skip to content

Constrained_Find

See Also: Constraints, Constrain, Constrained_Clear, Constraint_Set, Constraint_Validate, Find, Found, OnConstrain

Purpose

To find records within the constraints in the current constraint set.

The DataDictionary class provides superior functionality that replaces the need for this command in some cases.

Syntax

Constrained_Find {mode} {table}
by {-1 | recnum | Index#}

Where {table} is the name or filelist number of a database table; and {mode} must be one of LT, LE, EQ, GT, GE, FIRST, LAST, or NEXT.

When the last argument is -1, the index to use will be determined automatically from the constraints in force themselves.

What it Does

Constrained_Find finds records that qualify under the current constraint set according to the find {mode} (First | Last | Next | LT | LE | EQ | GE | GT), in the table and index specified. A Relate command is then performed to find all related records (according to which records in {table} may also be constrained).

Constrained_Find next respects the direction (GT, LT), table, and index of the last Constrained_Find or Constrained_Clear command executed for the current constraint set.

Open Vendor
Constraint_Set 1
Constrain Vendor.State Between "CA" and "CT"
Constrain Vendor.Name Matches "D*"
Constrained_Find First Vendor By 1
While (Found)
    Showln Vendor.Name
    Constrained_Find Next
Loop

The above program will print the name field for every vendor record whose state field has a value between "CA" and "CT", and whose name field starts with a "D". Since index one is based on the name field, only the records with names starting with "D" will be scanned.

A Constrained_Find executed with no constraint set current behaves exactly like a (unrestricted) Find command.

Constrained_Find sets the Boolean expressions Found and Finderr differently from the way the Find command does. Constrained_Find always fills the record buffer when a record can be found, but Found becomes TRUE only if the record satisfies the constraint set in effect. Found becomes FALSE if the record fails to satisfy the requirements of the constraints.

Notes

  • The First and Last find modes clear the record buffer before finding. The other find modes do not clear the record buffer; all finding is done relative to the current contents of the record buffer.

  • When no more records qualifying for the constraints can be found, Found will return False.

  • The table parameter may be passed as a table name or a table number.

  • All constrained finds attempt to optimize the find by using the index specified. If possible, Constrained_Find will seed the record buffer with data to "jump in" to the index and will "jump out" of the index when no qualifying records could exist past the current point in the index.

  • The use of Constrained_Find Next instead of Constraint_Find with the LT, LE, GT, or GE is more efficient and therefore recommended. Use the LT, LE, GT, GE, or EQ mode with the Constrained_Find First (or Last) and then use Constrained_Find Next for subsequent finds.

  • An ending argument of -1 will allow the constraint set to pick the best index to use for the search. If a constraint set contains an expression (constrain ... as (expression)), no index will be used, and records will be accessed in record number order.

  • Constrained_Find Next is useful even with no constraint set in effect when used after a Constrained_Clear command to set the table, index, and direction for constrained finds.