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
ADD-RELATION ( parent-buffer-handle , child-buffer-handle , [ pairs-list [ , reposition-mode [ , nested [ , not-active [ , recursive [ , foreign-key-hidden ]]]]]]) |
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.
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.
When working with large ProDataSets, omitting foreign keys in nested child records can yield smaller XML documents, more efficient network transfers, and performance gains with the READ-XML( ) and WRITE-XML( ) methods.
Care must be taken when deciding to use this feature. The READ-XML( ) 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 document. Unless you are sure that the receiver of the XML document will do the same, you should not use this option in your nested data-relations.
For example, while .NET can read this XML document and populate an ADO .NET DataSet, it will create rows in the child DataTable with a null value for the foreign key fields.