sdaiCreateNestedAggrByIterator

---

Creates an aggregate instance and sets the created aggregate as an element in an already existing aggregate instance, i.e., a nested aggregate is the result of this operation. The already existing aggregate will be the parent aggregate of the new created aggregate and the new created aggregate will be a child aggregate of the already existing aggregate. The position of the new aggregate in the parent aggregate is specified by an iterator.
This operation is legal for all parent aggregate types but the element position of the new aggregate in the parent aggregate will differ according to the type of the parent aggregate as follows:
ARRAY – The new created aggregate will be inserted at the element pointed to by the specified iterator. If an aggregate already exists in this element position, the existing aggregate will be deleted before the new aggregate is inserted in this element.
LIST – The new created aggregate will be inserted in the element after the element pointed to by the specified iterator. Hence, it will be an InsertAfter operation. When the iterator is pointing at the beginning of the aggregate, i.e. before the first element, the new created aggregate will be inserted as the first element in the parent aggregate. When the specified iterator is pointing to the end of the parent aggregate, i.e. after the last element, the new created aggregate will be appended as the last element in the parent aggregate. The actual iterator will point to the element containing the created aggregate after the completion of this operation.
BAG and SET – The new created aggregate will be inserted in an arbitrary element position in the parent aggregate.
Any levels of nesting is legal provided that the levels of nesting is according to the actual attribute declaration of the attribute that owns the outer-most aggregate, i.e., the aggregate created by the sdaiCreateAggr or sdaiCreateAggrBN operation. The actual aggregate type to be created is defined by the attributed declaration in the related EXPRESS schema.
A numeric aggregateID that uniquely identifies the new created aggregate instance in the EDMdatabase^ will be the returned function value. This aggregateID should be used to identify this particular aggregate instance in subsequent EDMinterface^ operations. An aggregateID is persistent and fixed, i.e. it is constant throughout the lifetime of the actual aggregate instance.
An aggregateID can never be used as a data value in any of the _EDMinterface^_ put operations, it can only be returned as data value in _EDMinterface^_ get operations.
This operation is only applicable on aggregates owned by application instances.
The model that will hold the new created aggregate must be open for write access before this function can be successfully performed.
See related function: sdaiCreateAggr , sdaiCreateAggrBN , sdaiCreateNestedAggr, sdaiCreateNestedAggrByIndex, edmiCreateTypedAggr , edmiCreateTypedAggrBN , edmiCreateNestedTypedAggr , edmiCreateNestedTypedAggrByIndex , edmiCreateNestedTypedAggrByIterator , edmiCreateScratchAggr , edmiCreateNestedScratchAggr , edmiCreateSubtypeAggr , edmiCreateSubtypeAggrBN , edmiCreateUnionAggr , edmiCreateUnionAggrBN
Header:
#include "sdai.h"
Prototype:
SdaiAggr sdaiCreateNestedAggrByIterator(SdaiIterator iterator);
Arguments:

Returns:
A numeric aggregateID that uniquely identifies the new created aggregate instance in the EDMdatabase^.
aggregateID != 0 : operation successfully performed.
aggregateID = 0 : operation failed, use sdaiErrorQuery function to get error reason.
Example:
SdaiAppInstance anInst;
SdaiAggr parentAggr, aggrId;
SdaiIterator iterId;
...
parentAggr = SdaiCreateAttrBN(anInst, "Attr");
. . .
iterId = sdaiCreateIterator(parentAggr);
. . .
aggrId = sdaiCreateNestedAggrByIterator (iterId);
if (! aggrId) {
/* Error in operation */ 
printf("\nError: %s in sdaiCreateNestedAggrByIterator \n", 
edmiGetErrorText(sdaiErrorQuery())); 
goto error; 
}
. . .