Function Name: Initialize Aggregate Iterator

Definition

Creates an iterator to (traverse over the list of)/(return pointers to) aggregate objects that meet the following conditions:

  1. they contain the start_object as an immediate component (a component that is exactly one link away) via a 2-way aggregation relationship. If an aggregate contains the start_object with a 1-way aggregation, then the aggregate will not be included in the list of objects returned by this iterator (because if it is a 1-way aggregation, then the start_object, by definition, does not know which objects aggregate the start_object).

  2. they satisfy the rules specified in the search filter, if a search filter is defined for the iterator. If NULL is passed in for the search filter, then no filtering is applied, and only condition (1) must be satisfied.
If a start_object is contained solely by 1-way aggregation relationships (if all of the aggregation relationships in the DRM Diagram go into the start_object with an arrow pointing into the start_object), then an Aggregate Iterator for that start_object will not return any objects. An Aggregate Iterator would be created, but it would have a length of 0 and would not return any objects.

To get the next object from an iterator, call SE_GetNextObject().

To find out the remaining length of an iterator (the number of objects remaining inside the iterator), call SE_GetIterationLengthRemaining().

When finished with an iterator, free it with a call to the SE_FreeIterator() function. Iterators can be freed at any time (they can be freed before all of their objects have been returned, that is, before their remaining length == 0, if the user so desires).

Returns

SE_SUCCESS - and a handle for the newly created aggregate iterator is copied into *iterator_out_ptr, if valid parameters were passed in and all operations succeeded.

SE_NULL_REQUIRED_PARAMETER - and *iterator_out_ptr is left unaltered, if iterator_out_ptr was NULL.

SE_INVALID_OR_NULL_OBJECT - and *iterator_out_ptr is set to NULL, if start_object is not a handle to a valid, active (i.e., unfreed) SEDRIS object.

SE_UNRESOLVED_START_OBJECT - and *iterator_out_ptr is set to NULL, if start_object is currently unresolved.

SE_OUT_OF_MEMORY - and *iterator_out_ptr is set to NULL, if memory allocation failed.

SE_FAILURE - and *iterator_out_ptr is set to NULL, if

  1. inter_transmittal_referencing_traversal is set to an illegal value,
  2. a search filter is provided, but is not a handle to a valid, active (i.e., unfreed) search filter defined by the specified API implementation, or
  3. the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Prototype


extern SE_STATUS_CODE_ENUM
SE_InitializeAggregateIterator
(
SE_OBJECT start_object, (notes)
SE_SEARCH_FILTER filter, (notes)
SE_ITR_TRAVERSAL_ENUM inter_transmittal_referencing_traversal, (notes)
SE_ITERATOR *iterator_out_ptr (notes)
);

Parameters Notes

start_object

 the component object for which the user wants a list of
    the aggregate objects that contain this component object.

filter

 a search filter that will be used to filter
    the output of this iterator.

inter_transmittal_referencing_traversal

 the user must choose how
    the iterator will behave when it encounters an Inter-Transmittal
    Reference (ITR). The iterator could automatically resolve such
    references and continue the search within the new transmittal;
    report all ITR references without resolving them; or just ignore
    them completely and continue to search within the current
    transmittal.

iterator_out_ptr

 a pointer to the freshly created
    iterator that will iterate over the aggregate objects that
    (1) contain the given component start_object via a 2-way aggregation
    and (2) pass the criteria defined in the search filter (if one was
    was provided).
Prev: Identify Object. Next: Initialize Associate Iterator. Up:Index.