Iterator functions

In addition to the arguments you specified when creating it, an iterator function contains an MI_FPARAM argument. The HCL OneDB database server uses an MI_FPARAM structure to control iteration over the set. The generated code includes a C switch statement with different cases to process the set. The switch statement uses the mi_fp_request() function to obtain the request flag from the MI_FPARAM structure. The HCL OneDB database server sets this flag to one of the following values before calling the function:

Table 1. MI_FPARAM structure request flags

Request flag	Description
SET_INIT	The initial call to the iterator function. The iterator function allocates and initializes memory for state information. The memory allocated must use the mi_alloc(size, PER_COMMAND) function to be available in subsequent calls.
SET_RETONE	The iterator function is called with this request flag once for each value in the set. For each value in the set, the function places the address of the next value in the set in the Gen_RetVal argument and returns Gen_RetVal. When there are no more values to return, the iterator function must call the mi_fp_setisdone() function to signal the HCL OneDB database server that all of the set values have been returned, as follows: mi_fp_setisdone(Gen_fparam, MI_TRUE); On this call, the iterator function returns a null pointer.
SET_END	The request flag the HCL OneDB database server sets after all values in the set have been returned. The iterator function frees allocated memory and releases any other resources it has obtained.

To complete the iterator code, you must:

• Add information declarations.
• Initialize the iterator function.
• Allocate private state information.
• Compute the value of the iteration.
• Call mi_fp_setisdone() when the iteration is complete.
• Free private resources.