Returns the instances that have one or more relations to the specified instance. The number of relations each instance has with the specified instance cannot be found by this function. Only relations between instances in an Explicit attribute role are returned.
It can be viewed that all instances that have at least one relation to one particular instance are held in an aggregate. The edmiGetInstanceReferences function operates on this aggregate. The index of the aggregate element to start on and the number of instances to return in one invocation of this function can be specified as arguments. This method makes it convenient to read the referencing instances in an incremental way, i.e. by several invocation of the edmiGetInstanceReferences function.
Each referencing instance is identified by a numeric instanceID that uniquely identifies an instance in an EDMdatabase.
This operation is only applicable on application instances.
The actual data model that holds the specified instance must be open before this function can be successfully performed.
Note: It is possible to disable the storing instance references option for each individual data model at model creation time. When the storing instance references option is disabled, then the edmiGetInstanceReferences operation will return an error code.
Related function: edmiUsedIn , edmiUsedInBN , edmiDeleteInstanceReferences .
Header:
#include "sdai.h"
Prototype:
EdmiError edmiGetInstanceReferences(SdaiInstance currInst,
SdaiInteger index,
SdaiInteger *numberOfRefs,
SdaiInstance *resultBuffer);
Arguments:
currInst |
A numeric instanceID that uniquely identifies the instance of interest in the EDMdatabase. |
index |
The reference index to start on. |
numberOfRefs |
In-value: The maximum referencing instances to return. This value should be less or equal to the number of instanceID that can be placed in the buffer specified by the <resultBuffer> argument to prevent writing past this buffer. |
resultBuffer |
The address of a buffer in the calling application that will receive an instanceID for all returned instances that have one or more relations to the specified instance. The argument <numberOfRefs> should be set according to the size of this buffer to prevent this function from writing past buffer. |
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
int i;
EdmiError rstat;
SdaiInstance currInst,resultBuffer[MAX_REFS];
SdaiInteger index,nrefs;
. . .
index = 0;
for(;
{
nrefs = MAX_REFS;
if (rstat = edmiGetInstanceReferences(currInst,
index,
&nrefs,
resultBuffer)) {
/* Error in operation */
printf("\nError: %s in edmiGetInstanceReferences\n",
edmiGetErrorText(rstat));
goto error;
}
if (! nrefs) break; /* No more references */
/* print referencing instances */
for (i = 0; i < nrefs; i++) {
printf("\n#%lu",resultBuffer[i]);
}
index += nrefs;
}
. . .