Skip to content

Filter Constraints

Filter constraints represent all non-relational constraints that are used to filter records by any set of restrictions. Filter constraints are defined within a DDO's OnConstrain method and are specified within this method by using the Constrain command.

Object oCustomer_DD Is A Customer_DataDictionary
    Procedure OnConstrain
        Constrain Customer.Status eq "A"
    End_Procedure
End_Object    // oCustomer_DD

Filter constraints are additive. If multiple constraints are defined within an OnConstrain event, all constraints must be satisfied for a record to be found. Filter constraints will also be added to a relates-to constraint. In the following example, only orders will be found if they:

  1. Are related to the current customer
  2. The order type is N
  3. The shipper is FEDEX
Object oCustomer_DD Is A Customer_DataDictionary
End_Object    // oCustomer_DD

Object oOrderHea_DD Is A OrderHea_DataDictionary
    Set DDO_Server To oCustomer_DD
    Set Constrain_File To Customer.File_Number

    Procedure OnConstrain
        Constrain OrderHea.Shipper eq "FEDEX"
        Constrain OrderHea.Type eq "N"
    End_Procedure
End_Object    // oOrderHea_DD

Constraints from parent DDOs are inherited by their child DDOs. This default behavior may not always be desired, and it can be disabled by setting the [pbInheritConstraints](Inheritance_of_Constraints.md) property to false.

Types of Filter Constraints

The Constrain command supports two main types of filter constraints:

File.Field Filter

The File.Field filter is used to specify that a table field’s value must match a specified value. It has the general format of:

Constrain {filename.fieldname} {mode} {value}

Some examples of File.Field filters are:

Constrain OrderHea.Shipper eq "FEDEX"
Get pbLowerDate to dLowerDate
Constrain OrderHea.Date gt dLowerDate
Get psStatusConstraint to sStat
If (sStat <> "") Begin
    Constrain Customer.Status eq sStat
End

File.Field filters are created and evaluated when a constraint is built and not each time a record is found. This has certain advantages. Because the constraint engine knows what field is being filtered and what type of evaluation is being applied, it is capable of determining if the constraint, given the index used for finding, can be optimized. If it can be optimized, the record search will be much faster.

Constrain-As Filter

The Constrain-As filter is used to specify that the record must match some criteria defined by an expression. It has the general format of:

Constrain {filename} As (expression)

Some examples of Constrain-As filters are:

Constrain Customer As (Uppercase(Customer.Name) Contains "DATA")
Constrain Customer As ( (Customer.Name Contains "DATA") Or ;
                         ( (Customer.Type = "COMPUTER") And ;
                           (Customer.Area_Code Matches "3?5") ))
Constrain Customer As (TestValidity(Self))

The expression must return a true or false value. If true, the record is valid; if false, it is filtered.

The expression constraint is the most flexible. You may put any expression you wish, of any level of complexity. You will usually use the expression comparisons with and/or to do this. You may also call functions within the expression. However, due to its flexibility, this is also the slowest constraint type. The expression is evaluated each time a record is found. In addition, because the constraint engine has no idea what the expression is actually doing, an expression constraint cannot be optimized (it cannot jump into or out of an index). Therefore, it can be very slow in large tables. If a File.Field filter type can do the same job, it should be used.

The Constrain-As filter can be used with other filters. If the other filters are capable of optimizing a find, the constraint engine will use those optimizations to perform index jumps and jump outs. This can greatly reduce the number of records that need to be tested using the Constrain-As filters and can provide satisfactory performance.

Object oCustomer_DD Is A Customer_DataDictionary
End_Object    // oCustomer_DD

Object oOrderHea_DD Is A OrderHea_DataDictionary
    Set DDO_Server To oCustomer_DD
    Set Constrain_File To Customer.File_Number

    Procedure OnConstrain
        Constrain OrderHea.Type eq "N"
        Constrain OrderHea As (OrderHea.Shipper="FEDEX" or OrderHea.Shipper="UPS")
    End_Procedure
End_Object    // oOrderHea_DD

See Also

Constraints and Filters