Releasing Iteration Resources

Once the mi_fp_setisdone( ) function sets the iterator-completion flag to 1, the database server calls the iterator function one last time with the iterator-status value in the MI_FPARAM structure set to SET_END. When the iterator function obtains this iterator-status value, it can perform any tasks needed to deallocate resources that the iterator function has allocated.

You can perform these deallocation tasks directly in the iterator function or you can declare a separate iterator-end function, which the iterator function calls when it receives the SET_END iterator-status value. Declare the iterator-end 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.

Figure 92 implements an iterator-end function, named fibGen_end( ), that the fibGen( ) iterator function (see Figure 89) calls when it obtains the SET_END iterator-status value.

mi_integer fibGen_end(fparam)
   MI_FPARAM *fparam;
{
   fibState   *fibstate;

   fibstate = (fibState *)mi_fp_funcstate(fparam); 
   mi_free(fibstate);

   return (0); /* return value is ignored */
}

The fibGen_end( ) function uses the mi_fp_funcstate( ) function to obtain the user-state pointer from the MI_FPARAM structure. It then calls the mi_free( ) function to free the resources in the fibstate state structure, which the fibGen_init( ) function (see Figure 90) has allocated. The fibGen_end( ) function returns an mi_integer value (0) because the main iterator function, fibGen( ), returns an active set of mi_integer values.