Syntax

The Data-Relation object only exists with respect to a ProDataSet. Therefore, a dynamic Data-Relation is created by executing a ProDataSet object method, not with a CREATE statement for a separate object. You cannot delete a Data-Relation. When the ProDataSet object is deleted or cleared, its Data-Relation objects are automatically deleted.

Use the ADD-RELATION method to add a relation to a dynamic ProDataSet. This is the syntax for the ADD-RELATION method:

dataset-handle:ADD-RELATION( parent-buffer-handle, child-buffer-handle,
  [ pairs-list [,reposition-mode [, nested [, recursive [, not active ]
  ] ] ] ]) .

In the ADD-RELATION method:

  • parent-buffer-handle is the buffer-handle of the Data-Relation parent.
  • child-buffer-handle is the buffer-handle of the Data-Relation child.
  • pairs-list is an expression that evaluates to a comma-delimited list of parent-field, child-field pairs to describe the relation between parent and child, using the same form as the Data-Relation phrase in a static DEFINE DATASET statement. Make sure that the list does not contain any embedded spaces. The AVM does not trim the elements in the list.
  • reposition-mode is a logical value. If true, it makes the Data-Relation a reposition relation; if it is false, the Data-Relation is a selection relation, which is the default.
  • nested is an optional logical value. If true, the AVM nests child rows of ProDataSet buffers within their parent rows when serializing the data into XML or JSON.
  • recursive is an optional logical value. If true, 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. You can check to see if a Data-Relation is recursive using the readable RECURSIVE attribute of the Data-Relation object handle.
  • not active is an optional logical value. If false, the Data-Relation is inactive. This allows you to have two relations between the same two ProDataSet temp-table buffers, but only have one active at a time.

You can add a multiple Data-Relation involving the same parent member temp-table. A table can be a child in only one active relation.

If the buffer handles specified are not in the ProDataSet, or fields supplied are not in the indicated tables, the AVM raises an error at run time.

The ADD-RELATION method returns a handle to the Data-Relation object, or the Unknown value (?) if there is an error.

A buffer for a temp-table does not have to have any Data-Relations at all. In this case, it is treated as an independent top-level data table within the ProDataSet. It must therefore be filled independently, either individually or when the ProDataSet as a whole is filled. There can be any number of top-level data tables (tables that are not the child in a Data-Relation). Each top-level table can have child tables or not.

You cannot take a static ProDataSet and add a buffer to it using the ADD-BUFFER method, or replace its buffers using SET-BUFFERS, or erase its buffer definition using the CLEAR method. However, you can add a dynamic Data-Relation to a static ProDataSet. This could be useful in the case where you need to use relations to navigate the ProDataSet but which are not necessary for filling it. Another case could be where a single ProDataSet might require different relations, depending on how it is used.

A difference in the ProDataSet's relations does not cause an error when the ProDataSet is passed as a parameter. If the ProDataSet is received dynamically using the DATASET-HANDLE form, then the AVM creates the Data-Relations that are defined in the caller as dynamic relations in the ProDataSet in the called procedure.

If the ProDataSet is received statically using the DATASET parameter form, then the AVM ignores the relations in the caller and uses the Data-Relation definitions in the receiving procedure's static ProDataSet definition. This means, for example, that you could pass a static ProDataSet from server to client, add a Data-Relation to it dynamically on the client, and then pass the ProDataSet back to the server without error. If the server-side definition is static, the extra relation on the client is simply ignored when it arrives on the server.