SEDRIS Reference Manual
APPENDIX A - LEVEL 0 READ and WRITE API
Functions
SE InitializeAggregateIterator
extern SE_Status_Code
SE_InitializeAggregateIterator
(
SE_Object start_object, (notes)
SE_Search_Filter filter, (notes)
SE_ITR_Behaviour itr_traversal, (notes)
SE_Iterator *iterator_out_ptr (notes)
);

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.


  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_STAT_CODE_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_STAT_CODE_NULL_REQUIRED_PARAMETER and *iterator_out_ptr is left unaltered, if iterator_out_ptr was NULL.
SE_STAT_CODE_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_STAT_CODE_UNRESOLVED_START_OBJECT and *iterator_out_ptr is set to NULL, if start_object is currently unresolved.
SE_STAT_CODE_OUT_OF_MEMORY and *iterator_out_ptr is set to NULL, if memory allocation failed.
SE_STAT_CODE_FAILURE and *iterator_out_ptr is set to NULL, if
  1. itr_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.

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.

itr_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: SE_IdentifyObject. Next: SE_InitializeAssociateIterator. Up:Index.

Last updated: May 15, 2003 Copyright © 2003 SEDRIS™