company logo

Property :: copyCollection - Copy collection

The function copies all instances of the source collection to the target collection. The function works well for multiple references as well as for single references. The function cannot be used for MEMO fields.

The target property handle must be opened in update mode (Write or Update) and accessible.

Source and target need not to refer to the same object type. Attributes and references are copied by property name, i.e. they are assigned by looking for the same property name in the target instance. Data conversion is performed automatically, if possible. This includes also converting embedded instances into references and reverse.

The target property is not emptied automatically. Existing instances in the target are replaced according to the replace option passed to the function.

When successful the function returns the number of instances copied to the target collection (including 0 when the source was empty). When the function has terminated because of an error (e.g. when one of the property handles is invalid), it throws an exception.
Notes:

When a selection (filter) has been set for the source collection, only instances fullfilling the filter condition will be copied (filter()).

Return value:  Number of items ( int32  )

The value contains the number of items to be processed or stored in a collection.

Implementation overview

Implementation details

  1. Copy collection
    int32 Property  :: copyCollection ( odaba::Property &cSourceProperty, odaba::ReplaceOptions eReplace, odaba::CopyTypes eCopyType, bool bInverseCheck )

    The function copies all (filtered) instances from the source collection passed in cSourceProperty to the current collection. Existing instances might be replaced when passing an appropriate replace option in eReplace.

    The value passed in eCopyType determines, the amount of related instances to be copied. In order to perform inverse relationship check, true has to be passed in bInverseCheck.
    • 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.
    • bInverseCheck - Check inverse references

      When this option is set, an inverse reference check is performed for each instance, which checks, whether maintaining the inverse reference will not cause consistency problems. This happens especially, when duplicating instances, which refer to single referenced global object instances.
    2. to list
  2. Copy collection and replace
    int32 Property  :: copyCollection ( odaba::Property &cSourceProperty, odaba::ReplaceOptions eReplace )

    The function copies all (filtered) instances from the source collection passed in cSourceProperty to the current collection. Existing instances might be replaced when passing an appropriate replace option in eReplace.
    • 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.

    3. to list
  3. Copy instances from source collection
    int32 Property  :: copyCollection ( odaba::Property &cSourceProperty )

    The function copies all (filtered) instances from the source collection passed in cSourceProperty to the current collection without replacing existing instances. The function copies instances and instances referenced in relationships.
    • 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.

    4. to list
to top previous next upper table of contents Comment