company logo

Property :: copy - Copy instance

The function allows copying instances from one property to another. The function creates a new instance that is filled with the data from the source instance. The function also allows copying instances between collections in different databases.

The source handle must refer to a positioned instance that is copied into the target handle collection. The target property handle must be accessible for write.

Source and target property handle may refer to collections of different types. Properties of the copied instances are copied by name. Names of property handles in base types are searched without base type prefix, i.e. properties may change level of inheritance. When the target collection is weak-typed, the type for the target instance must be set by the application before copying the instance (setType(sTypeName)).

When the instance to be copied does already exist in the target property handle, which is determined by the selected access key for the target property handle, different replace options passed in eReplace allow controlling the copy behavior. Copying an existing instance without requesting replacement of existing instances will result in an error. When no unique access key has been selected, instances are considered as not existing and are copied always.

Copying instances includes copying related collections (references and relationships). Only primary relationships (not defined as secondary) are copied in order to avoid infinite recursions. When copying related collection the replace option is passed to the subsequent copy operations.

The copy type passed in eCopyType supports a two phase copy process. Normally, when copying an instance, owning parts and primary relationships are copied at once. Sometimes this may lead to problems, since it is not always possible to ensure that base collections are copied before copying primary relationships based on it. Since this leads to incomplete copy operations, a two phase copy can be used copying first the owning parts (CopyInstances) and later with a second call of the copy function the primary relationships (CopyRelationships).

When Copy terminates successfully the instance copied is selected in the target property handle, which will be returned to the calling function.

When one of the property handle is not valid, when no instance is selected in the source property handle, or when terminating with errors, the function throws an exception.
Notes:

When copying a database, transient attributes having a data source are not resolved. When transient attributes are filled by read handlers, those will be resolved when context handlers are enabled, only (contextEnabled())

Return value:  Property reference ( odaba::Property & )

A property handle refers to a (usually) opened property. Invalid properties may cause an exception.

Implementation overview

Implementation details

  1. Copy to position and rename
    odaba::Property & Property  :: copy ( odaba::Property &cSourceProperty, odaba::Key vNewKey, int32 iPosition, odaba::ReplaceOptions eReplace, odaba::CopyTypes eCopyType )

    The function copies the selected instance in the source property handle to the target property handle by renaming the access key in the instance to vNewKey. When the target collection is unordered, the function copies the selected instance from the source instance at the position passed in iPosition in the target collection.

    When the collection is ordered, the position passed is ignored and the instance is inserted according to the key value passed in vNewKey.

    When no access key is defined, the function throws an exception.

    When the position passed in iPosition is greater that the instance count for the target collection, the position is changed to the number of instances in the target collection. When passing -1, the instance is inserted in front of the selected instance in the target collection when an instance is selected, or appended at the end of the list, otherwise.
    • 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.

    • vNewKey - New key value for instance

      The key passed for renaming the instance must be structured according to the currently selected sort order. Key components within a key must be separated by '|' or ';'. An empty string can be passed in order to indicate no key value.

      In order to pass no key value, an empty string ( String() ) has to be passed.
    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.
    • eReplace - Replace option

      Replace options can be passed in order to control the behavior of copy functions.

    • eCopyType - Copy type

      The copy type defines the amount of data to be copied or exported.
    2. to list
  2. Copy to position
    odaba::Property & Property  :: copy ( odaba::Property &cSourceProperty, int32 iPosition, odaba::ReplaceOptions eReplace, odaba::CopyTypes eCopyType )

    This implementation copies the selected instance from the source instance at the position passed in iPosition in the target collection.

    When the position passed in iPosition is greater that the instance count for the target collection, the position is changed to the number of instances in the target collection. When passing -1, the instance is inserted in front of the selected instance in the target collection when an instance is selected, or appended at the end of the list, otherwise.

    When the collection is ordered, the position passed is ignored and the instance is inserted according to the key value in the source instance.
    • 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.
    • eReplace - Replace option

      Replace options can be passed in order to control the behavior of copy functions.

    • eCopyType - Copy type

      The copy type defines the amount of data to be copied or exported.
    3. to list
  3. Copy selected instance
    odaba::Property & Property  :: copy ( odaba::Property &cSourceProperty, odaba::ReplaceOptions eReplace, odaba::CopyTypes eCopyType )

    The function copies the selected instance from the source property handle to the target property handle.
    • 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.

    • eReplace - Replace option

      Replace options can be passed in order to control the behavior of copy functions.

    • eCopyType - Copy type

      The copy type defines the amount of data to be copied or exported.
    4. to list
  4. Copy and rename
    odaba::Property & Property  :: copy ( odaba::Property &cSourceProperty, odaba::Key vNewKey, odaba::ReplaceOptions eReplace, odaba::CopyTypes eCopyType )

    The function copies the positioned instance in the source property handle to the target property handle by renaming the access key in the instance to vNewKey.

    When no access key is defined, 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.

    • vNewKey - New key value for instance

      The key passed for renaming the instance must be structured according to the currently selected sort order. Key components within a key must be separated by '|' or ';'. An empty string can be passed in order to indicate no key value.

      In order to pass no key value, an empty string ( String() ) has to be passed.
    • eReplace - Replace option

      Replace options can be passed in order to control the behavior of copy functions.

    • eCopyType - Copy type

      The copy type defines the amount of data to be copied or exported.
    5. to list
to top previous next upper table of contents Comment