Click or drag to resize

OrdSetRelation Function

X#
Relate a specified work area to the current work area.

Namespace:  XSharp.RT
Assembly:  XSharp.RT (in XSharp.RT.dll) Version: 2.19
Syntax
 FUNCTION OrdSetRelation(
	uArea,
	cbKey,
	cKey
) AS USUAL CLIPPER
Request Example View Source

Parameters

uArea (Optional)
Type: Usual
The number of the child work area or the alias of the child work area.
cbKey (Optional)
Type: Usual
A code block that expresses the relational expression in executable form.
cKey (Optional)
Type: Usual
An optional string value that expresses the relational expression in textual form.
If cKey is supplied, it must be equivalent to cbKey.
If cKey is omitted, DBRelation() returns a NULL_STRING for the relation.

Return Value

Type: Usual
Remarks
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 cbKey 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 cbKey and/or cKey. OrdSetRelation() is identical to DBSetRelation() (and the SET RELATION...SCOPED 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 and is particularly useful when displaying the related data in a sub-data window. Refer to DBSetRelation() for additional information.
Examples
This example displays each invoice with its related line items:
X#
 1USE lineitem NEW VIA "DBFCDX"
 2SET ORDER TO TAG InvNo
 3USE invoice NEW VIA "DBFCDX"
 4// Set a selective relation from Invoice into LineItem
 5OrdSetRelation("LineItem", {|| Invoice->InvNo}, "Invoice->InvNo")
 6GO TOP
 7DO WHILE !EOF()
 8    ? InvNo, InvDate        // Display invoice fields
 9    SELECT LineItem
10    // Only records for current invoice # are visible
11    LIST "   ", PartNo, Qty, Price
12    SELECT Invoice            // On to next invoice
13    SKIP
14ENDDO
See Also