DbSetRelation Function |  |
Relate a specified work area to the current work area.
Namespace: XSharp.RT
Assembly: XSharp.RT (in XSharp.RT.dll) Version: 2.21
SyntaxRequest Example
View Source
TRUE if successful; otherwise, FALSE.
Parameters
- xAlias (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 character 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. - cName (Optional)
- Type: Usual
An optional name for the relation. Defaults to ParentName + "_" + ChildName.
Return Value
Type: LogicTRUE if successful; otherwise, FALSE.
Remarks
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 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. DBSetRelation() performs the same function as the SET RELATION command with the ADDITIVE clause.
For more information, refer to the SET RELATION command.
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. DBSetRelation() performs the same function as the SET RELATION command with the ADDITIVE clause.
For more information, refer to the SET RELATION command.
 Tip |
|---|
|
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 (for example, 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, and its EOF() status returns TRUE. |
Examples
This example demonstrates a typical use of the DBSetRelation() function:
X#
1USE employee NEW 2USE department NEW INDEX dept 3SELECT employee 4DBSetRelation("Department", {|| Employee->Dept}, "Employee->Dept") 5LIST Employee->Name, Department->Name
See Also