Aggregate functions

If you created a user-defined aggregate with the Aggregate wizard, BladeSmith generates aggregate functions in the udr.c source code file.

The generated code

BladeSmith generates only templates for aggregate functions.

The generated function declares the function, its return type, and arguments. In addition to the arguments you specified when creating the function, these functions also have an MI_FPARAM argument. Only generated functions that allow null values have code that uses the MI_FPARAM argument. The generated code in these functions uses the MI_FPARAM to set the return value of the function to NULL.

Complete the code

To complete the code for aggregate functions, you must:
  • Add your declarations, if necessary.
  • Remove the call to mi_db_error_raise(), which raises an error stating that the routine is not implemented.
  • Compute the return value and store it in the Gen_RetVal argument.
  • Remove the call to mi_fp_setreturnisnull() that sets the return value of your routine to NULL, if necessary.

For more information about programming aggregate functions, see the Informix® DataBlade® API Programmer's Guide.

The initialization function
If you selected an initialization function, AggregateInit(), you must add code to it to initialize the state type required by the aggregate computation. You can set up smart large objects or temporary files for storing intermediate results as the state type. The AggregateInit() function returns the state type.

The first argument of the AggregateInit() function is a placeholder argument whose value is always NULL. The second argument is an optional initialization parameter to customize aggregate computation. The initialization parameter cannot be a lone host variable reference.

The iteration function
You must add code to the iteration function, AggregateIter(), to perform the aggregate computations.
The AggregateIter() function does not maintain additional states in its MI_FPARAM argument because the MI_FPARAM argument is not shared among the aggregate functions. However, you can use the MI_FPARAM argument to hold information that does not affect the aggregate result.
Tip: Although the iteration function is called by the database server multiple times to calculate the aggregation, it is not implemented as an iterator function that returns a set of results.
The combine function
If you selected a combine function, AggregateComb(), you must add code to it to merge one partial result with another and return the updated state type.
The final function
If you selected a final function, AggregateFinl(), you must add code to convert the state type to the result type.

You can also add code to the AggregateFinl() function to release resources acquired by the initialization function. However, the AggregateFinl() function must not free the state type.