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

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: July 16, 2004 Copyright © 2004 SEDRIS™