ORDSETRELATION()
 Relate a specified work area to the current work area
------------------------------------------------------------------------------
 Syntax

     ORDSETRELATION(<nArea> | <cAlias>,<bKey>, [<cKey>])
         --> NIL

 Arguments

     <nArea> is the number of the child work area.

     <cAlias> is the alias of the child work area.

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

     <cKey> is an optional string value that expresses the relational
     expression in textual form.  If <cKey> is supplied, it must be
     equivalent to <bKey>.  If <cKey> is omitted, ORDSETRELATION() returns a
     null string ("") for the relation.

 Returns

     ORDSETRELATION() always returns NIL.

 Description

     ORDSETRELATION() 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 a controlling order 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 <bKey> and/or <cKey>.  If
     the child work area has no controlling order, moving the parent work
     area causes an automatic "go to" in the child work area; the record
     number for the "go to" is based on the expression specified by <bKey>
     and/or <cKey>.

     ORDSETRELATION() is identical to DBSETRELATION() (and the SET RELATION
     command), but it also sets up a scope on the order in the child work
     area.  This means that whenever you select the child work area, only the
     records related to the current parent record will be visible.  This
     allows straightforward handling of one-to-many relationships.  Refer to
     DBSETRELATION() for more information.

 Examples

     .  This example displays each invoice with its related line
        items:

        USE LineTtem NEW VIA "DBFCDX"
        SET ORDER TO TAG InvNo

        USE Invoice NEW VIA "DBFCDX"

        // Set a selective relation from Invoice into
        // LineItem
        ORDSETRELATION("LineItem", {|| Invoice->InvNo}, ;
           "Invoice->InvNo")

        GO TOP
        DO WHILE !EOF()
           ? InvNo, InvDate            // Display invoice fields

           SELECT LineItem
           // Only records for current invoice # are visible
           LIST "   ", PartNo, Qty, Price
           SELECT Invoice               // On to next invoice
           SKIP
        ENDDO

 Files   Library is CLIPPER.LIB.