Function Name: Get Next Object

Definition

Iterates over objects available through an iterator.

This function returns the following two items (via out parameters):

• the next object from the iterator
• the link class object (a.k.a. association class object) traversed to find the 'next object' that was returned from the iterator

Returns

SE_DIFFERENT_TRANSMITTAL - if valid parameters were passed in, the iterator is configured to automatically resolve inter-transmittal references (ITR), an ITR reference was encountered in searching for the next object, and the iterator successfully resolved it and continued to search in the new, different transmittal until the next object from the iterator was found. In this case, *next_object_out_ptr is set to point to the next object from the iterator, and *association_class_object_out_ptr is set appropriately, unless the user passed in a NULL for that value.

SE_UNRESOLVED_OBJECT - if valid parameters were passed in, an inter- transmittal reference (ITR) was encountered in searching for the next object, and either the iterator is configured to automatically resolve ITR references but was unable to do so, or it is configured to stop at ITR references. In these cases, *next_object_out_ptr is set to point to the unresolved object, and *association_class_object_out_ptr is set appropriately, unless the user passed in a NULL for that value.

SE_NULL_REQUIRED_PARAMETER - if next_object_out_ptr was NULL. In this case, the output parameter values are left unaltered.

SE_NO_OBJECT - if the iterator is out of objects to return. In this case, the *next_object_out_ptr and, if not NULL, the *association_class_object_out_ptr values are set to NULL.

SE_OUT_OF_MEMORY - if the API cannot allocate memory for the next object to be returned. In this case, the output parameter values are set as for SE_NO_OBJECT.

SE_FAILURE - and the output parameter values are set as for SE_NO_OBJECT, if

1. the iterator is not legal, or
2. the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Prototype

Parameters Notes

iterator

 the iterator whose next object is being requested.

next_object_out_ptr

 a pointer to a variable in the user's memory space,
    into which the next object of the iterator will be copied.

association_class_object_out_ptr

 a pointer to
    a variable in the user's memory space, into which then link object
    traversed to reach the 'next object' will be copied. If no association
    class object was attached to the link used to reach the next object,
    then *association_class_object_out_ptr will be set to NULL.