Definition

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

1. they are associated to the start_object as an immediate associate (an associate that is exactly one link away) via either a 2-way association, or via a 1-way association from the start_object to the associated object. If an object is associated to the start_object via a 1-way association from the associated object to the start_object, then the associated object will not be included in the list of objects returned by this iterator (because if it is a 1-way association into the start_object, then the start_object, by definition, does not know which objects are at the other end of the 1-way associations).



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 associated solely by 1-way incoming associations, or if the start_object does not participate in any associations, then an Associate Iterator for that start_object will not return any objects. An Associate 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 associate 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 itr_traversal is set to an illegal value, 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 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 object whose list of associates will be returned

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 associated objects that
    (1) are associated by an association from the start_object, and
    (2) pass the criteria defined in the search filter (if a search
        filter was provided).

Prev: SE_InitializeAggregateIterator. Next: SE_InitializeComponentIterator. Up:Index.

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