SEDRIS Reference Manual
APPENDIX A - Transmittal Access Level 0 API
Functions
SE InitializeAggregateIterator
extern SE_Return_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_RET_CODE_SUCCESS and the iterator is initialized.
SE_RET_CODE_FAILURE and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RET_CODE_SUCCESS is returned:

SE_STAT_CODE_SUCCESS set if valid parameters were passed in and all operations succeeded.

SE_Status_Code(s) when SE_RET_CODE_FAILURE is returned:

SE_STAT_CODE_UNRESOLVED_INPUT_OBJECT SE_STAT_CODE_UNRESOLVED_INPUT_OBJECT set if start_object is currently unresolved.
SE_STAT_CODE_INACTIONABLE_FAILURESE_STAT_CODE_INACTIONABLE_FAILURE set 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 call fails for any other reason.

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

Last updated: August 23, 2005 Copyright © 2005 SEDRIS™