(mysql.info) udf-aggr-calling

 
 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