Adds a data-relation object for a pair of parent and child buffers to a dynamic ProDataSet object.

Return type: HANDLE

Applies to: ProDataSet object handle

Syntax

ADD-RELATION ( parent-buffer-handle , child-buffer-handle , 
 [ pairs-list [ , reposition-mode [ , nested [ , not-active [ , recursive 
 [ , foreign-key-hidden  ]]]]]])
parent-buffer-handle
A handle to the parent buffer in the data-relation object.
child-buffer-handle
A handle to the child buffer in the data-relation object.
pairs-list
A character expression that evaluates to a comma-delimited list of parent-field, child-field pairs describing the relationship between parent and child buffers in the data-relation object using the following syntax:
"parent-field1,child-field1[,parent-fieldn,child-fieldn ]..."

The first field in the pair is from the parent buffer, the second field is from the child buffer. This list can contain no embedded spaces. When filling the ProDataSet object, the AVM retrieves data for the child buffer based on an equality match between all pairs of fields unless the data-delation is deactivated or there is an explicit query definition for the data source of the child buffer.

You can define a query for the data source of the child buffer, or you can supply custom logic in response to FILL events that take over complete responsibility for filling one level of the ProDataSet object. In these cases, the pairs-list is not used.

reposition-mode
The reposition mode of the relation between the parent and child temp-tables. If TRUE, the relation mode is REPOSITION. If FALSE, the relation mode is SELECTION. The default value is FALSE.

When the relation mode is SELECTION, the method fills the child temp-table of the data-relation object with all records related to the current parent. When the relation mode is REPOSITION, the relation is effectively ignored during a FILL, and the child of the relation is treated as if it were a top-level buffer.

When navigating a filled ProDataSet object with a SELECTION relation, related data is filtered as it is browsed. This means the child query of the relation is filtered to make available only children of the current parent, and the query is re-opened each time the parent table is repositioned. When navigating a filled ProDataSet object with a REPOSITION relation, the child table query is always set to match all the rows in the child table, and is not re-opened when the parent changes. Only the buffer for the child is repositioned to the matching child for the current parent.

nested
A LOGICAL expression where TRUE directs the AVM to nest child rows of ProDataSet buffers within their parent rows when writing the XML representation of data. This also causes the XML Schema definitions for the related temp-tables to be nested. When FALSE, all child rows are written after all parent rows are written. The default value is FALSE.
not-active
An optional LOGICAL expression where FALSE causes the data-relation to be inactive. This allows you to have two relations between the same two ProDataSet temp-table buffers, but only have one active relation at a time.
recursive
An optional LOGICAL expression where TRUE causes the data-relation to be filled recursively. This mode instructs the ProDataSet FILL to load self-referencing elements. That is, an element can reference a child element that already either directly or indirectly references the parent element in the hierarchy. Examples of this hierarchy are bill-of-materials parent/child tables or organization chart manager/employee relationship tables.
foreign-key-hidden
An optional LOGICAL expression where TRUE directs the AVM to omit foreign key fields in nested data-relations when writing the XML or JSON representation of data. For XML, this also causes the XML Schema definition for the ProDataSet to indicate that the foreign key fields are optional. Since the parent record in a nested relationship contains the foreign key, suppressing it in the nest child record is efficient. If this option is used, the NESTED argument must be TRUE.

When working with large ProDataSets, omitting foreign keys in nested child records can yield smaller XML or JSON documents, more efficient network transfers, and performance gains with the READ-XML()/READ-JSON() and WRITE-XML()/WRITE-JSON() methods.

Care must be taken when deciding to use this feature. The READ-XML()/READ-JSON() method automatically populates foreign keys in nested child records with the values in the outer parent record when the foreign key is omitted from the XML or JSON document. Unless you are sure that the receiver of the XML or JSON document will do the same, you should not use this option in your nested data-relations.

For example, while .NET can read this document and populate an ADO .NET DataSet, it will create rows in the child DataTable with a null value for the foreign key fields.

See also

FOREIGN-KEY-HIDDEN attribute, RECURSIVE attribute