PropertyHandle :: Move - Move instance to another collection

The function moves an instance from the source collection (source_handle) to the collection of the current property handle. This is the only way, to move dependent or owned instances from one collection to another one. It is also a save way to copy instances avoiding duplicate key problems, that may result from the inverse reference for local collections. The function allows also moving instances between distinct sub collections of an extent.

When the type of source and target instance is the same and when both, source and target property handle have been opened for the same database handle, the instance is removed from the source collection and inserted into the target collection. In this case the instance does not change the local and global identity. When the two collection differ in type, the instance is copied from the source to the target collection and removed/deleted from the source collection afterwards.

When replacing existing instances is required the instance is identified in the target collection by key according to the sort order set for the target collection. When a unique sort order is set and an instance with the same key as the source instance does already exist, the instance is removed/deleted from the target collection before moving the source instance to the target collection.

The function returns an instance handle to the instance selected in the property handle (instance moved). The function returns an empty instance handle, when the it terminates with error.