Property :: appendReference - Append persistent instance

The function supports appending an instance to an unordered collection. The function appends an instance selected in another property handle to the collection of the current property handle, but does not create a copy from the instance.

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). The function can be called for unordered collections, only, that do not own the instances. Usually the function is used for filling temporary or transient collections with instances, which have been selected for special purposes.

Source and target property handle have to 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 selected one.

Events are generated as being described for insert().