The statcollect() function

When you run UPDATE STATISTICS, the database server calls the appropriate statcollect() function for each column that the database server scans.

The statcollect() function takes four arguments:
  • The first argument is of the same data type as the UDT for which the statcollect() function is called.

    The database server uses this argument to resolve the function and to pass in values.

    The first time the database server invokes this function, it sets this parameter to null. On subsequent invocations, this argument contains the column value.

  • The second argument is a double-precision value that indicates the number of rows that the database server must scan to gather the statistics.
  • The third argument is a double-precision value that is the resolution specified by the UPDATE STATISTICS statement. The resolution value specifies the bucket size for the distribution. However, you might choose to ignore this parameter if it does not make sense for your UDT.
  • The fourth argument is an MI_FPARAM structure that the database server uses to pass information to the UDR as well as a place to store state information.

On the first call to statcollect(), MI_FPARAM contains a SET_INIT value. Check for this value in statcollect() and perform any initialization operations, such as allocating memory and initializing values.

On subsequent calls to statcollect(), MI_FPARAM contains a SET_RETONE value. At this point, statcollect() should read the column value from the first argument and place it in your distribution structure.

After all rows have been processed, the last call to statcollect() puts a value of SET_END in MI_FPARAM. For this final call, statcollect() should put the statistics in the stat data type and perform any memory deallocation.

You must declare the statcollect() function with HANDLESNULLS, but the function itself can ignore nulls if desired.

Allocate any memory used across multiple invocations of statcollect() from the PER_COMMAND pool and free it as soon as possible. Any memory not used across multiple invocations of statcollect() should be allocated from the PER_ROUTINE pool.