(mysql.info) udf-aggr-calling
Info Catalog
(mysql.info) udf-calling
(mysql.info) adding-udf
(mysql.info) udf-arguments
24.2.4.2 UDF Calling Sequences for Aggregate Functions
......................................................
This section describes the different functions that you need to define
when you create an aggregate UDF. adding-udf, describes the
order in which MySQL calls these functions.
* `xxx_reset()'
This function is called when MySQL finds the first row in a new
group. It should reset any internal summary variables and then use
the given `UDF_ARGS' argument as the first value in your internal
summary value for the group. Declare `xxx_reset()' as follows:
char *xxx_reset(UDF_INIT *initid, UDF_ARGS *args,
char *is_null, char *error);
`xxx_reset()' is not needed or used in MySQL 5.0, in which the UDF
interface uses `xxx_clear()' instead. However, you can define both
`xxx_reset()' and `xxx_clear()' if you want to have your UDF work
with older versions of the server. (If you do include both
functions, the `xxx_reset()' function in many cases can be
implemented internally by calling `xxx_clear()' to reset all
variables, and then calling `xxx_add()' to add the `UDF_ARGS'
argument as the first value in the group.)
* `xxx_clear()'
This function is called when MySQL needs to reset the summary
results. It is called at the beginning for each new group but can
also be called to reset the values for a query where there were no
matching rows. Declare `xxx_clear()' as follows:
char *xxx_clear(UDF_INIT *initid, char *is_null, char *error);
`is_null' is set to point to `CHAR(0)' before calling
`xxx_clear()'.
If something went wrong, you can store a value in the variable to
which the `error' argument points. `error' points to a single-byte
variable, not to a string buffer.
`xxx_clear()' is required by MySQL 5.0.
* `xxx_add()'
This function is called for all rows that belong to the same
group, except for the first row. You should use it to add the
value in the `UDF_ARGS' argument to your internal summary variable.
char *xxx_add(UDF_INIT *initid, UDF_ARGS *args,
char *is_null, char *error);
The `xxx()' function for an aggregate UDF should be declared the same
way as for a non-aggregate UDF. See udf-calling.
For an aggregate UDF, MySQL calls the `xxx()' function after all rows
in the group have been processed. You should normally never access its
`UDF_ARGS' argument here but instead return a value based on your
internal summary variables.
Return value handling in `xxx()' should be done the same way as for a
non-aggregate UDF. See udf-return-values.
The `xxx_reset()' and `xxx_add()' functions handle their `UDF_ARGS'
argument the same way as functions for non-aggregate UDFs. See
udf-arguments.
The pointer arguments to `is_null' and `error' are the same for all
calls to `xxx_reset()', `xxx_clear()', `xxx_add()' and `xxx()'. You can
use this to remember that you got an error or whether the `xxx()'
function should return `NULL'. You should not store a string into
`*error'! `error' points to a single-byte variable, not to a string
buffer.
`*is_null' is reset for each group (before calling `xxx_clear()').
`*error' is never reset.
If `*is_null' or `*error' are set when `xxx()' returns, MySQL returns
`NULL' as the result for the group function.
Info Catalog
(mysql.info) udf-calling
(mysql.info) adding-udf
(mysql.info) udf-arguments
automatically generated byinfo2html