Release iteration resources

After 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.

Important: Free only resources that you have allocated. Do not attempt to free resources that the database server has allocated (such as the MI_FPARAM structure).

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.

The following code fragment implements an iterator-end function, named fibGen_end(), that the fibGen() iterator function (see Figure 1) calls when it obtains the SET_END iterator-status value.

Figure 1. The fibGen_end() iterator-end function

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 1) 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.