| Note | This command is defined in a header file and will be preprocessed by the X# preprocessor to a function call. If you disable the standard header (-nostddefs) files then this command will not be available. If you tell the compiler to use a different standard header file (-stddef ) then this command may also be not available |
Purpose
Link a parent work area to one or more child work areas using a key expression, record number, or numeric expression.
Syntax
SET RELATION TO [<uRecID> INTO <xcAlias>] [, [TO] <uRecId> INTO <xcAlias>...] [ADDITIVE] [SCOPED]
Arguments
| TO <uRecID> | Performs an <xcAlias>->DBSeek(<uRecID>) operation if the child work area has a controlling order; otherwise, performs an <xcAlias>->DBGoTo(<uRecID>) operation. The operation serves to position the child work area to a matching index key value or record number each time the record pointer moves in the parent work area. |
| INTO <xcAlias> | The alias identifier for the child work area. If there is no open database file associated with the specified alias, a runtime error is raised. |
| ADDITIVE | Specifies that relations are to be added to the existing relations in the work area. If not specified, existing relations are cleared before the new ones are set. |
| SCOPED | Causes the SET RELATION command to map to the OrdSetRelation(). If not specified, SET RELATION maps to DBSetRelation(). |
SET RELATION TO with no arguments clears all relations defined in the current work area.
Description
Each parent work area can be linked to as many as eight child work areas.
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.
SET RELATION TO when specified with a list of expressions and alias names is functionally equivalent to using several DBSetRelation() (or OrdSetRelation(), if SCOPED is specified) function calls. If no ADDITIVE clause is specified, the command calls DBClearRelation() first.
Notes
Soft seeking: Seek operations that occur as part of relational positioning are never soft seeks (they do not respect the SetSoftSeek() flag). 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.
Cyclical relations: Do not relate a parent work area to itself either directly or indirectly.
Record number relations: To relate two work areas based on matching record numbers, use RecNo() for the SET RELATION TO expression and make sure the child work area has no active indexes.
Examples
This example relates three work areas in a multiple parent-child configuration with CUSTOMER related to both INVOICES and ZIP:
USE invoices INDEX invoices NEW
USE zip INDEX zipcode NEW
USE customer NEW
SET RELATION TO CustNum INTO Invoices, Zipcode INTO Zip
LIST Customer, Zip->City, Invoices->Number, Invoices->Amount
Sometime later, you can add a new child relation using the ADDITIVE clause, like this:
USE backorder INDEX backorder NEW
SELECT customer
SET RELATION TO CustNum INTO Backorder ADDITIVE
Assembly
XSharp.RT.DLL
See Also
DbGoTo(), DBRelation(), DBRSelect(),, DbSeek(), DbSetIndex(), DbSetOrder() , DBSetRelation(), Found(), OrdSetRelation(), RecNo(), SET INDEX, SET ORDER, SetSoftSeek()
