PropertyHandle :: AddReference - Add persistent instance
The function adds an instance selected in another property handle to the collection/reference 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 AddReference() only for not owning collections. Usually the function is used to fill temporary extents with instances, which have been selected for special purposes.
You can only add instances that are defined in the same database as the instances of the target property handle and which are defined in a property handle hierarchy. It is also not possible to add an instance by reference from a server database to a local database or vize versa. It is also not possible to add references from operation path nodes or path nodes.
After adding the instance to the property handle the added instance is the currently selected one.
Events
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.
AddReference is intended for filling transient collections. When applying AddReference on persistent collections, some automatic features will be disabled. Thus, AddReference will not maintain base collection relationships, i.e. adding an instance to a collection will not automatically add the instance to the base collection of the collection. This may cause weak consistency problems.
Inverse relationships are maintained when calling AddReference.
Implementation details
- source_handle
- Source property handle
The source property handle must be opened and an instance must be selected in the handle.
- set_pos0_w
- Position in collection
The position of an instance in a collection depends on the selected index. if the collection is unsorted the position is the only way for accessing the instance.
For sorted collections the position is determined according to the instance key. If is a contradiction between position and key value the position will be ignored.
Special positions are
CUR_INSTANCE (-1) refers to the currently selected instance. If no instance is selected it refers to the first instance.
FIRST_INSTANCE (0) refers to the first instance in a collection according to the selected index (sort order).
FIRST_INSTANCE (0x7fffffff) refers to the last instance in a collection according to the selected index (sort order).
Default: AUTO