Collect the statistics

The statcollect() user-defined function is an iterator function; that is, the database server calls statcollect() for each of the rows on whose column of a user-defined data type UPDATE STATISTICS is collecting statistics. As with other iterator functions, the database server uses an iterator-status constant to indicate when the statistics-collection function is called.

Important: The database server passes the value of the iterator-status constant within the MI_FPARAM structure. Therefore, your statistics-collection function must declare an MI_FPARAM structure as its last parameter. Otherwise, it cannot access the value of the iterator-status constant with the mi_fp_request() function.

The following table summarizes the values of the iterator-status constant for the statcollect() function.

When is the statcollect() function called?	What does statcollect() need to do?	Iterator-status constant in MI_FPARAM
The first time that statcollect() is called	Perform any initialization operations, such as allocating memory for a statistics-collection structure and initializing values First argument (udt_arg) is a NULL value.	SET_INIT
Once for each row for which statistics are being collected	Return one item of the active set Read the column value from the first argument (udt_arg) and place it in your statistics-collection structure.	SET_RETONE
After all rows have been processed	Release iteration resources Put the statistics in the stat data type and perform any memory deallocation	SET_END

To obtain the iterator-status constant in each iteration, your statcollect() function can use a switch statement on the return value of the mi_fp_request() function, as follows:

switch ( mi_fp_request(fparam_ptr) )
{
   case SET_INIT:
      ...
   case SET_RETONE:
      ...
   case SET_END:
      ...
}

If statcollect() raises an error, UPDATE STATISTICS terminates the statistics collection for that column.

The following sections summarize the steps that statcollect() must take for each of these iterator-status constants. For general information about iterator-status constants, see Table 1.