PropertyHandle :: CopySet - 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 (PI_Write).
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 collection 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 it returns AUTO (-1). No instance is selected in source and target handle after terminating the function.
When a selection (filter) has been set for the source collection, only instances fullfilling the filter condition will be copied (SetFilter()).
The value contains the number of items (characters, entries, instances etc.).
Implementation details
- csource_handle - Source property 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
- inverse_check
- Check inverse reference
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.
Default: NO