The first time that the database server calls the iterator function,
the database server passes it an MI_FPARAM structure
with the iterator status set to SET_INIT and the user-state pointer
set to NULL. When the iterator function obtains this iterator-status
value, it can perform the following initialization tasks for the iterator
function:
Allocate memory for the structure in which you save the user-state
information with a DataBlade®
API memory-management function such as mi_dalloc()
Make sure that this memory has a memory
duration of PER_COMMAND so that the user state remains for the duration
of all iterations of the iterator function. If the memory has the
default PER_ROUTINE memory duration, the database server automatically
deallocates it after only one iteration of the iterator function.
For more information, see Choose the memory duration.
Save the user-state pointer in the MI_FPARAM structure
with the mi_fp_funcstate() function
Each subsequent
call to the iterator function uses the same MI_FPARAM structure,
so each iteration can reuse the cached user-state memory. The iterator
function must save enough information to return values one at a time
on demand. For more information, see Saving a user state.
You can perform these initialization tasks directly in the iterator
function or you can declare a separate iterator-initialization
function, which the iterator function calls when it receives
the SET_INIT iterator-status value. Declare the iterator-initialization
function to return the same data type as the main iterator function.
However, the database server ignores the return value of this function;
it does not put this return value in the active set.
The following code fragment implements an iterator-initialization
function, call fibGen_init(), which the fibGen() iterator function (The fibGen() iterator
function) calls when it obtains the SET_INIT iterator-status value.
The fibGen_init() function returns an mi_integer value (0) because the main
iterator function, fibGen(), returns an active
set of mi_integer values. However, the database
server does not return this value as part of the active set. After fibGen_init() completes, the database server calls
the next iteration of fibGen() with an iterator-status
value of SET_RETONE to return the first item of the active set.