OnConstrain - DataSet

Defines constraint sets in a DataDictionary object (DDO)

Type: Event

Parameters: None

Syntax

Procedure OnConstrain

Description

OnConstrain defines constraint sets in a DataDictionary object (DDO).

Constraints are used to limit the records that are considered to be members of the data set. Each DDO may have, at most, one OnConstrain procedure, but this procedure may contain as complex a set of constraints (including constraints whose values can be changed by users at runtime) as you may need.

Sample

A simple hard-coded constraint.

Procedure OnConstrain
    Constrain Customer.Status eq "A"
End_Procedure

Note that OnConstrain is not called every time a record is found. It is called when the DataDictionary builds a constraint set. Once a constraint set is built, that same set is applied to all records until a new set is created. Constraints are built when a view is activated or when the Rebuild_Constraints message is explicitly sent to a DataDictionary object (DDO). You will never send the message OnConstrain. If you need to dynamically change a constraint, then you must change the appropriate properties and then send the Rebuild_Constraints message to the DDO.

Sample

Object Invt_DD is an Invt_DataDictionary
    Property Boolean pbAllowOld False

    Procedure OnConstrain
        Boolean bAllowOld

        Get pbAllowOld to bAllowOld

        // Conditional constraint
        If Not bAllowOld Begin
            Constrain Invt.Status eq "A"
        End

        // Unconditional constraint
        Constrain Invt.Qty gt 100
    End_Procedure
    :
End_Object

The above procedure could be called within a view with the following code:

Set pbAllowOld of Invt_DD to True
Send Rebuild_Constraints of Invt_DD

Within objects, it is suggested that you use OnConstrain and not procedure Constrain for creating constraints.

The commands Begin_Constraints and End_Constraints are obsolete. You should use the procedure OnConstrain in their place.

Procedure OnConstrain
    Boolean bAllowOld

    Get pbAllowOld to bAllowOld

    // Conditional constraint
    If Not (bAllowOld) Begin
        Constrain Invt.Status eq "A"
    End

    // Unconditional constraint
    Constrain Invt.Qty gt 100
End_Procedure

A special type of constraint called a relates-to constraint establishes a constrained parent child relationship between two files. Because this type of constraint is used so often, a property is provided to define this relationship. This constraint is set within the child DDO and is normally set with the Constrain_File property.

// this is used to create a relates to constraint (parent-child)
Set Constrain_File to ParentFile.File_Number

It is assumed that a child will only have a constrained relates-to relationship with a single parent. A relates-to constraint is the only type of constraint type that is not placed inside of the OnConstrain procedure - it is placed directly within the object.

Object Child_DD is a Child_DataDictionary
    Set DDO_Server to (ParentFileDD(Self))
    Set Constrain_File to ParentFile.File_Number
End_Object

Relates-to constraints not only affect the finding of records, the clearing of records as well. In general, any time a child-file DDO is cleared, its parent files' DDO(s) will also be cleared if and only if the child has no constraints that depend upon the parent. For example:

Object Parent1_DD is a Parent1_DataDictionary
End_Object

Object Parent2_DD is a Parent2_DataDictionary
End_Object

Object Child_DD is a Child_DataDictionary

    Set DDO_Server to (Parent1_DD (Self))
    Set DDO_Server to (Parent2_DD (Self))

    // this is used to create a relates to constraint  (parent child)
    Set Constrain_File to Parent2.File_Number

    // OnConstrain is used to set all other constraints
    Procedure OnConstrain
        Constrain Child.Status ne "X"
    End_Procedure

End_Object

If Child_DD is asked to clear (by one of its data entry objects (DEOs), etc.), the relates-to constraint from Child to parent2 will prevent Parent2_DD from clearing, but Parent1_DD will clear, since Child_DD's constraints do not depend on Parent1.