Iterator Functions

If you create an iterator function that returns a set one row at a time, BladeSmith adds code to process the set. The Informix database server calls iterator functions repeatedly to process all of the return values.

The Generated Code

In addition to the arguments you specified when creating it, an iterator function contains an MI_FPARAM argument. The Informix 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 Informix database server sets this flag to one of the following values before calling the function:

• 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 Informix 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 Informix 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.

In the generated code, each of these sections has a TO DO: note. To avoid code merging problems, make changes only where indicated.

Completing the Code

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.

For more information on programming iterator functions, see the IBM Informix: DataBlade API Programmer's Guide.

Example

The LoanAmortization() function in the Business DataBlade module is an iterator function.