This operation copies an instance graph within one edmModel or between two edmModels. The source instance graph consists of all instances that are directly or indirectly refered to by the source instance. The target instance(s) will be implicitly created, hence copying between existing instances can not be performed by this operation.
Optionally this operation may copy a partial instance graph by using the <exclude_or_include> argument. This argument is a listing of instance types that shall be included or excluded from the graph. If an instance type is excluded, all instances of that type, and the entire branch of referenced instances below it, will be omitted from the copying operation. Omitted instances will not be created in the target model and of course no references to them may be generated either. Hence, attributes referencing instances in the source model will be unset in their corresponding target instances even if the instance was copied.
Related functions: edmiRemoteConditionalDeepCopyInstance, edmiConditionalDeepCopyInstance, edmiConditionalDeepCopyInstances
Header:
#include "sdai.h"
Prototype:
EdmiError edmiRemoteConditionalDeepCopyInstance(SdaiServerContext serverContextId,
SdaiInstance sourceInstancesId,
SdaiVersion version,
SdaiModel modelId,
SdaiInteger options,
SdaiEntity *exclude_or_include,
SdaiInstance *newInstancesId,
SdaiInvocationId *edmiInvocationId);
Arguments:
serverContextId |
Context identification, from edmiDefineServerContext |
sourceInstancesId |
A numeric instanceID that uniquely identifies the instance to be copied in the remote _EDMdatabase{_}. |
version |
The version of the edmModel to apply this fuction call on. The version argument is a sequence number counting from one by increments of one for each new model version created. A zero version number means the current version of the edmModel. |
modelId |
The numeric modelID that uniquely identifies the edmModel in which the target instances shall be created. The target and source models must be populations of the same underlying Express Schema. |
options |
See description of available options below. |
exclude_or_include |
A zero-terminated buffer of entityIds to be either included in or excluded from the instance graph to be copied. A NULL value means that the entire graph will be copied to the target model. If the option EXCLUDE_INSTANCES is used, the contents of this buffer will be interpreted as instanceIds to be excluded from the source instance graph. |
newInstancesId |
A zero-terminated buffer that will receive th instanceIds of all the instances that were created within the target model. |
edmiInvocationId |
Currently not used. |
Options: Descriptions:
COPY_INSTANCES |
|
VALIDATE_ORIGINAL_INSTANCES |
|
SUBTYPES |
Will add any subtypes of the entities listed in the <exclude_or_include> argument to the <exclude_or_include> argument. |
DELETE_INSTANCES |
|
VALIDATE_COPIED_INSTANCES |
|
INCLUDE_TYPES |
Instances of the entities listed in the <exclude_or_include> argument are the only instances that will be copied to the target model. However, instances within the graph that are only being referenced from instance types that are not explicitly included by the <exclude_or_include> argument will not be copied. |
EXCLUDE_TYPES |
Instances of the entities listed in the <exclude_or_include> argument will not be copied to the target model. Any instance within the graph that is only being referenced from excluded instances will be excluded as well, even if the instance type is not explicitly excluded by the <exclude_or_include> argument. |
EXCLUDE_INSTANCES |
The <exclude_or_include> argument will be interpreted as a zero-terminated buffer of instanceIds to be excluded from the copying. |
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. |
USE_MAPPED_INSTANCES |
|
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. |
INCLUDE_INVERSE_ROLES |
|
EXCLUDE_INVERSE_ROLES |
|
INCLUDE_ALL_INVERSE_ROLES |
|
DELETE_COPIED_INSTANCES |
|
DO_NOT_COPY_INSTANCES |
|
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;
SdaiServerContext myContext;
SdaiInteger index, nHits;
SdaiQueryResult qexRes;
SdaiInstance johnnysId, johnnysNewId, excludeIds[2];
SdaiModel modelId;
/* Create Server Context */
rstat = edmiDefineServerContext("MyContext",
"Johnny", "Supervisor", "cf37ftr",
"TCP", "9090", "MyServerHost",
NULL, NULL, NULL, NULL, NULL, &myContext);
/* Get Johnnys PERSON instance Id from
his primary key attribute 'PID' */
nHits = 1;
index = 0;
rstat = edmiRemoteSelectInstances(myContext,
"DataRepository", "SocialRelations",
"Person", "PID = '16126353127'",
(ONLY_INSTANCE_IDS | SUBTYPES),
NULL, NULL, NULL,
&index, &nHits, &qexRes,
NULL, NULL, NULL, NULL);
if (!nHits) {
printf("\nRequested pid not found.");
goto err;
}
johnnysId = qexRes->instanceIds[0];
/* Get Lucys PERSON instance Id from
her primary key attribute 'PID' */
rstat = edmiRemoteSelectInstances(myContext,
"DataRepository", "SocialRelations",
"Person", "PID = '10046746112'",
(ONLY_INSTANCE_IDS | SUBTYPES),
NULL, NULL, NULL,
&index, &nHits, &qexRes,
NULL, NULL, NULL, NULL);
excludeIds[0] = qexRes->instanceIds[0];
excludeIds[1] = 0; /* zero-terminate */
/* Create a social relations model
for Johnnys relations only. */
rstat = edmiRemoteCreateModel(myContext, "JohnnysRepository",
"JohnnysSocialRelations", "SocialRelations",
0, NULL);
rstat = edmiRemoteGetModelBN(myContext, "JohnnysRepository",
"JohnnysSocialRelations", &modelId, NULL);
/* Copy Johnnys social relations graph
to a model containing only his own
social relations. Exclude Lucy!! */
rstat = edmiRemoteConditionalDeepCopyInstance(myContext,
johnnysId, 0, modelId, EXCLUDE_INSTANCES,
&excludeIds[0], &johnnysNewId, NULL);
. . .