company logo

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.

Notes:

Für Extents und Relationships werden noch keine Basisextents gepflegt.

Return value:  Instance area ( ::Instance  )

Instances do have the type of the referenced property handle (collection type). The instance contains a pointer to a properly structured instance area.

You can use the !-operator or the GetData () function to check whether the instance refers to data or not.

Implementation details

  1. Move without rename
    ::Instance PropertyHandle  :: Move ( PropertyHandle &source_handle, PIREPL replopt=REPL_none )

    The function moves the instance without renaming. When the instance exists in the target collection the function returns an error.

    • source_handle - Source property handle

      The source property handle must be opened and an instance must be selected in the handle.

    • replopt - Replace option

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

      Default: REPL_none
  2. to list
  3. Move with rename
    ::Instance PropertyHandle  :: Move ( PropertyHandle &source_handle, ::Key new_key, PIREPL replopt=REPL_none )

    The function allows renaming an instance while moving it to the target collection. When the new key does already exist in the target collection the instance is overwritten depending on the replace option.

    • source_handle - Source property handle

      The source property handle must be opened and an instance must be selected in the handle.

    • new_key - New key for the instance

      The key passed for renaming the instance must be structured according to the currently selected sort order.

    • replopt - Replace option

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

      Default: REPL_none
  4. to list