Property :: insertReference - Insert persistent instance
The function inserts an instance selected in another property handle to a collection of the current property handle. Both property handles must have the same type or the same base type (when the source is weak-typed or has a shared base type, which corresponds to the property handle type). You can use the function only for collections not owning the instances. Usually the function is used to fill temporary or transient collections with instances, which have been selected for special purposes.
Source and target property handle must be defined for the same database. The target property handles must not be a property handle in the parent hierarchy of the source property handle. It is not possible to add an instance by reference from a server database to a local database or reverse. It is also not possible to add references from operation path nodes, which are usually not persistent.
When the property defines a weak-typed collection and the instance to be added inherits from shared base instances, the smallest shared base instance inheriting from the collection type will be added as reference..
In the source property, an instance must be selected. Otherwise, the function throws an exception.
After adding the instance to the property handle the added instance is the currently positioned one.
Events are generated as described for insert().
When a filter has been set for the collection, no instance will be selected in the property handle, when the instance created does not match the filter condition.
insertReference() is intended for filling transient collections. When applying insertReference() on persistent collections, some automatic features will be disabled. Thus, insertReference() will not maintain super set hierarchies for relationships, i.e. inserting an instance to a collection will not automatically insert the instance to the super set hierarchy. This may cause weak consistency problems.
Inverse relationships are maintained when calling insertReference().
When adding an instance to a collection the function fires an insert event and an inserted event. You can use the insert event for checking the operation and deny it.
When the post event handler has been modifying the instance an additional stored event might be created. When selecting the instance in the property handle a final read event is generated.
A property handle refers to a (usually) opened property. Invalid properties may cause an exception.
Implementation overview
- Insert reference
Property :: insertReference ( cSourceProperty ) - Insert reference at position
Property :: insertReference ( cSourceProperty, iPosition )
Implementation details
-
Insert reference
odaba::Property & Property :: insertReference ( odaba::Property &cSourceProperty )
The function inserts the instance selected in cSourceProperty to a collection. When the collection is ordered, the instance is inserted at position according to the access key. When the collection is unordered, the instance is inserted in front of the currently selected instance or at the end when no instance is selected.
When no instance is selected in the passed property handle, the function throes an exception.
- cSourceProperty
- Source property handle
The source property handle is a reference to an opened Property. Invalid or not opened property handles may cause an exception.
to list
- cSourceProperty
- Source property handle
-
Insert reference at position
odaba::Property & Property :: insertReference ( odaba::Property &cSourceProperty, int32 iPosition )
The function inserts the instance to an unordered collection. The instance selected in cSourceProperty is inserted at position passed in iPosition.When -1 is passed in iPosition,the instance will be appended to the end of collection.
When the collection is ordered or when no instance is selected in the passed property handle, the function throws an exception.
- cSourceProperty
- Source property handle
The source property handle is a reference to an opened Property. Invalid or not opened property handles may cause an exception.
- iPosition
- Position in collection
The position of an element in a collection is beginning with 0 for the first element.
to list
- cSourceProperty
- Source property handle