Property :: setTransientReference - Setting property handle for transient property (reference)

This function sets the property handle for a transient reference property to the property handle (cursor) passed in cProperty.. The function will not automatically create a copy of the cursor passed in cProperty.. The associated handle is registered, only.

When a cursor copy of the passed property handle is required, the application has to create the copy before setting the transient reference (cursorCopy()). After associating the cursor copy of the passed property handle, it can be destroyed, because it is registered in the transient reference property and will be destroyed when resetting the transient reference or when setting another property handle.

When creating a copy of a transient reference property, the copy will refer to the property handle currently set for the transient reference. Properties set in transient references and its copies are maintained automatically, when setting a new property in the original transient reference or one of its copies.

Property handles in transient references are destroyed automatically, when they are part of a persistent object instance and this instance is destroyed. When, however, referring recursively to a property handle by associating a parent or higher property handle with a subordinated property handle this may result in never deleting the cursor object in the property handle. You may call markUsed() and markUnused() in order to handle this problem.

You can release the associated property handle using the resetTransientProperty() function or by passing an empty (not opened) property handle.

When the property handle or the passed property handle is invalid, the function throws an exception.