edmiConditionalDeepCopyInstance

This operation copies an instance graph within one data model> or from one data model to another. The source instance graph consists of all instances that are directly or indirectly used by the source instance. The target instance(s) will implicitly be created, hence copy between existing instances cannot be performed by this operation.
Optionally this operation can copy a partial instance graph, one complete or one partial instance.
The data model locating the source instance must be open for read access and the target data model must be open for write access, before this operation can be successfully performed.
Related functions: edmiDeepDeleteInstance
Header:
#include "sdai.h"
Prototype:
EdmiError edmiConditionalDeepCopyInstance(SdaiInstance sourceInstanceId,
                                           SdaiModel    modelId,
                                           SdaiInteger  options,
                                           SdaiEntity   *exclude_or_include,
                                           SdaiInstance *newInstanceId);
Arguments:

sourceInstanceId	A numeric instanceID that uniquely identifies the instance to be copied in the EDMdatabase.
modelId	A numeric modelID that uniquely identifies the data model locating the target instance(s). This target model must be a population of the same schema as the model that locates the <sourceInstanceId>.
options	Specifies the options to be used in the invocation of the edmiConditionalDeepCopyInstance function. The <options> value can be specified as a bitwise OR between the actual options to enable. All option names are defined on the header file sdai.h. See detailed descriptions of the available options below.
exclude_or_include	Address of an array of instances or instance types (entities). The content is dependent of the value of the <options> argument. An instanceID = 0 terminates the <exclude_or_include> array. When appropriate, NULL can be the value of this argument.
newInstanceId	An address to a variable that will receive a numeric instanceID that will uniquely identify the created instance (target instance) in the EDMdatabase.

Option: Description:

INCLUDE_TYPES	Only instances of the type specified in the <exclude_or_include> argument will be copied. When the SUBTYPES options is set, additionally instances that are subtypes of the specified types in <exclude_or_include> argument can be copied. The content of the <exclude_or_include> argument must be an array of SdaiEntity, each defining an instance type. A SdaiEntity with the value 0 (zero) terminates the array. The option values INCLUDE_TYPES , EXCLUDE_TYPES and EXCLUDE_INSTANCES are mutually exclusive.
EXCLUDE_TYPES	Instances of type specified in the <exclude_or_include> argument will not be copied. When the SUBTYPES options is set, additionally instances that are subtypes of the specified types in <exclude_or_include> argument will not be copied. The content of the <exclude_or_include> argument must be an array of SdaiEntity, each defining an instance type. A SdaiEntity with the value 0 (zero) terminates the array. The option values INCLUDE_TYPES , EXCLUDE_TYPES and EXCLUDE_INSTANCES are mutually exclusive.
SUBTYPES	This option has only effect when used together with INCLUDE_TYPES or EXCLUDE_TYPES options.
EXCLUDE_INSTANCES	The instances specified in the <exclude_or_include> argument will not be copied. The content of the <exclude_or_include> argument must be an array of SdaiAppInstance. A SdaiAppInstance with the value 0 (zero) terminates the array. The option values INCLUDE_TYPES , EXCLUDE_TYPES and EXCLUDE_INSTANCES are mutually exclusive.
COPY_SHALLOW	Only the source instance will be copied, i.e., no instance graph will be copied. The operation will be a shallow copy operation. When the source model and the target model is the same, the instance references in the source instance will be copied to the target instance.
EXCLUDE_ALL_INSTANCES	Only the source instance will be copied. The operation will be a shallow copy operation. No instance references will be copied, only attributes of primitive data types, including aggregates of primitive data types, will be copied.

Returns:
A completion code of datatype EdmiError is the returned function value. The completion code has the following values:
Completion code = 0: Operation successfully performed.
Completion code != 0: Error in operation. Completion code is an EDMinterface error code. Use edmiGetErrorText to get the error text corresponding to the error code.
EXAMPLE
EdmiError rstat;
SdaiInstance sourceInstanceId, newInstanceId;
SdaiModel modelId;
. . .
if (rstat = edmiConditionalDeepCopyInstance (sourceInstanceId,
modelId,
0,
NULL,
&newInstanceId)) {
/* Error in operation */
printf("\nError: %s in edmiConditionalDeepCopyInstance \n",
edmiGetErrorText(rstat));
goto error;
}
. . .