PropertyHandle :: Copy - Copy instance

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

The source handle must point to a selected instance that is copied into the target handle collection. The target property handle must be opened for write access.

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 structured are considered without prefix. When the target collection is weak-typed, the type for the target instance must be set by the application before copying the instance (SetType()).

When the instance to be copied does already exist in the target collection, which is determined according to the sort order selected for the target collection, different replace options (PIREPL) may control the copy behavior (replopt). Copying an existing instance without requesting replacement of existing instances will result in an error. When no unique sort order 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 to avoid unlimited recursions. When copying related collection the replace option is passed to the subsequent copy operations.

The copy type supports a two phase copy process. Normally copying an instance owning parts and primary relationships are copied at once. Sometimes this may lead to logical 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 (COPY_instance) and later with a second call of the copy function the primary relationships (COPY_relationship).

When Copy terminates successfully the copied instance is selected in the target property handle and the instance is returned. When terminating with errors the function returns an empty instance.

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 overview

Copy selected instance
PropertyHandle :: Copy ( source_handle, replopt=REPL_none, copy_type=COPY_all )
Copy to position and rename
PropertyHandle :: Copy ( source_handle, new_key, set_pos0, replopt=REPL_none, copy_type=COPY_all )

Implementation details

Copy selected instance
::Instance PropertyHandle :: Copy ( PropertyHandle &source_handle, PIREPL replopt=REPL_none, COPY_Options copy_type=COPY_all )

The function copies the selected instance from the source property handle to the target property handle.
- 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
- copy_type - Copy type
  The copy type determines the way of copying instances. Depending on import, export or copy processes, the meaning differs slightly.
  Default: COPY_all

to list

Copy to position and rename
::Instance PropertyHandle :: Copy ( PropertyHandle &source_handle, ::Key new_key, int32 set_pos0, PIREPL replopt=REPL_none, COPY_Options copy_type=COPY_all )

The function copies the instance passed in source property handle to the given position in an unordered set.

When the passed position is greater that the collection count, the position is changed to the number of instances in the target collection. When passing AUTO, the instance is positioned in front of the selected instance in the target collection (if 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.
- 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.
- set_pos0 - Position in collection
  The position of an instance in a collection depends on the selected index. if the collection is unsorted the position is the only way for accessing the instance.
  
  For sorted collections the position is determined according to the instance key. If is a contradiction between position and key value the position will be ignored.
  
  Special positions are
  
  CUR_INSTANCE (-1) refers to the currently selected instance. If no instance is selected it refers to the first instance.
  
  FIRST_INSTANCE (0) refers to the first instance in a collection according to the selected index (sort order).
  
  FIRST_INSTANCE (0x7fffffff) refers to the last instance in a collection according to the selected index (sort order).
- replopt - Replace option
  Replace options can be passed in order to control the behavior of copy functions.
  Default: REPL_none
- copy_type - Copy type
  The copy type determines the way of copying instances. Depending on import, export or copy processes, the meaning differs slightly.
  Default: COPY_all

to list

to top Comment