IdmaRelationshipOrdering

This interface provides methods for manipulating the relative ordering of multiple relationship 'arrows' pointing out of a single Head or into a single Tail.

The methods below affect only the local scratch copies of the objects. To make these changes persistent, IdmaConnection::ExecuteChange() or IdmaBatch::ExecuteChanges() must be invoked on the relationship object.

IdmaRelationshipOrdering::SetOrdering

Support for this method is optional.

Syntax
DmaRC IdmaRelationshipOrdering::SetOrdering (
Dmapv pIHeadRelationship,
DmaInteger32 ulHeadWhere,
Dmapv pITailRelationship,
DmaInteger32 ulTailWhere)

Parameters

This method manipulates the relative ordering of multiple relationship 'arrows' pointing out of a single Head or into a single Tail. It allows inserting before or after a specified existing relationship object, or first or last in the enumeration, or in an arbitrary document-space-defined order.

The values for ulHeadWhere and ulTailWhere are selected from the following set: DMA_POS_BEFORE inserts the current object immediately before the other object. DMA_POS_AFTER inserts the current object immediately after the other object. DMA_POS_FIRST inserts the current object as the first element of the enumeration. DMA_POS_LAST inserts the current object as the last element of the enumeration. DMA_POS_NO_CHANGE does not change the ordering (useful for setting an initial ordering). DMA_POS_DEFAULT leaves the choice of where the current object is inserted up to the doc space implementation. Only DMA_POS_DEFAULT is required to be supported if this interface is implemented. For DMA_POS_FIRST and DMA_POS_LAST, the 'other object' argument must be NULL.

In the context of containment, the Head and Tail properties of a Referential Containment Relationship object, for instance, are objects of class Containable and Container, respectively. The reflective property for Head is Containers in an object of class Containable. The reflective property for Tail is Containees in an object of class Container. Thus, invoking this method on a Referential Containment Relationship object after setting the Head and Tail properties will insert the relationship object into the Containers and Containees enumerations of the related Containable and Container objects.

Similarly, the Head and Tail properties of a Direct Containment Relationship object are objects of class Containable and Container, respectively. The reflective property pairs are Head and Parent, and Tail and Children. Note that Parent is a singleton Direct Containment Relationship object, rather than an enumeration, due to the 1:N nature of direct containment. In this case, the only valid values for pIHeadRelationship and ulHeadWhere are null and DMA_POS_DEFAULT, respectively.

If multiple calls are made to this method without intervening calls on ExecuteChange or ExecuteChanges, each such call completely replaces the intended effect of the preceding call. Thus, when ExecuteChange or ExecuteChanges is invoked, the only ordering change to the persistent store will be those reflecting the most recent call to SetOrdering.

Return Values