DBSETRELATION()
 Relate two work areas
------------------------------------------------------------------------------
 Syntax

     DBSETRELATION(<nArea> | <cAlias>, <bExpr>, <cExpr>)
        --> NIL

 Arguments

     <nArea> is a numeric value that specifies the work area number of
     the child work area.

     <cAlias> is a character value that specifies the alias of the child
     work area.

     <bExpr> is a code block that expresses the relational expression in
     executable form.

     <cExpr> is a character value that expresses the relational
     expression in textual form.

 Returns

     DBSETRELATION() always returns NIL.

 Description

     DBSETRELATION() relates the work area specified by <nArea> or <cAlias>
     (the child work area) to the current work area (the parent work area).
     Any existing relations remain active.

     Relating work areas synchronizes the child work area with the parent
     work area.  This is achieved by automatically repositioning the child
     work area whenever the parent work area moves to a new record.  If there
     is an active index in the child work area, moving the parent work area
     causes an automatic SEEK operation in the child work area; the seek key
     is based on the expression specified by <bExpr> and/or <cExpr>.  If the
     child work area has no active index, moving the parent work area causes
     an automatic GOTO in the child work area; the record number for the GOTO
     is based on the expression specified by <bExpr> and/or <cExpr>.

     The relational expression may be a code block (<bExpr>) or both a code
     block and equivalent text (<cExpr>).  If both versions are supplied,
     they must be equivalent.  If the text version is omitted, DBRELATION()
     will return an empty string for the relation.

     DBSETRELATION() performs the same function as the standard SET RELATION
     command with the ADDITIVE clause.  For more information, refer to the
     SET RELATION command.

 Notes

     .  Side effects: DBSETRELATION() is only guaranteed to
        synchronize the work areas as described above.  The relational
        expression is not necessarily evaluated at any particular time, by
        any particular means, or on any particular record or series of
        records.  If the relational expression relies on information external
        to the parent work area or its associated database file, the effect
        is unpredictable.  If the expression changes the state of either work
        area (e.g., by moving to a different record or changing the contents
        of a record), the effect is unpredictable.

     .  Evaluation context: When the relational expression is
        evaluated, the parent work area is automatically selected as the
        current work area before the evaluation; the previously selected work
        area is automatically restored afterward.

     .  Soft seeking: Seek operations that occur as part of relational
        positioning are never soft seeks.  If a relational movement is
        unsuccessful, the child work area is positioned to LASTREC() + 1, its
        FOUND() status returns false (.F.), and its EOF() status returns true
        (.T.).

 Examples

     .  This example demonstrates a typical use of the DBSETRELATION()
        function:

        USE Employee NEW
        USE Department NEW INDEX Dept
        SELECT Employee
        DBSETRELATION("Department", {|| Employee->Dept},;
                        "Employee->Dept")
        LIST Employee->Name, Department->Name

 Files   Library is CLIPPER.LIB.