本节介绍创建集合UDF之时需要定义的不同函数。27.2.3节,“添加新的自定义函数” 介绍了MySQL调用这些函数的顺序。
xxx_reset()
当MySQL在一个新组中发现第一行时调用这个函数。它对这个组重置任何内部总和变量,然后使用给定的UDF_ARGS参量作为内部总和值的第一个值。如下说明 xxx_reset() 函数:
char *xxx_reset(UDF_INIT *initid, UDF_ARGS *args, char *is_null, char *error);
在MySQL5.1版中UDF接口不需要或不使用xxx_reset()函数,而是使用xxx_clear()函数作为替代。但是如果你想让UDF也能在老版本的服务器上运行,你也可以定义 xxx_reset() 和 xxx_clear() 函数。(如果你使用了这两个函数,xxx_reset()函数在很多情况下可以通过调用函数来内部实现,即调用xxx_clear()函数重置所有变量,然后添加UDF_ARGS参量作为组的第一个值。)
xxx_clear()
当MySQL需要重置总和结果时调用此函数。对每一个新组,在开始之时调用它,但是它也可以被调用来为一个没有匹配行在其中的查询重置值。如下说明xxx_clear():
char *xxx_clear(UDF_INIT *initid, char *is_null, char *error);
在调用xxx_clear()之前is_null 被设置指向 CHAR(0) 。
如果发生错误,你可以存储一个值在 error参量指向的变量中。error指向一单字节变量,而不是一个字符串缓冲区。
xxx_clear() 是MySQL 5.1必须的。
xxx_add()
为同组除了第一行之外,所有的行调用这个函数。你应该用它在UDF_ARGS参量中向内部总和变量加值。.
char *xxx_add(UDF_INIT *initid, UDF_ARGS *args, char *is_null, char *error);
对集合UDF而言xxx() 函数应该用与非集合UDF一样的方法来说明。请参阅27.2.3.1节,“UDF调用简单函数的顺序”。
对一个集合UDF,MySQL 在组内所有行被处理之后调用xxx()函数。这里你应该一般不会接触到它的UDF_ARGS参量,但是取而代之地根据内部总和变量返回给你值。
在xxx()中处理的返回值应该用与对非集合UDF一样的方法来操作。请参阅27.2.3.4节,“UDF返回值和错误处理”。
xxx_reset() 和 xxx_add() 函数用与非集合UDF一样的方法来处理它们的UDF_ARGS 参量。请参阅27.2.3.3节,“UDF参量处理”。
到is_null和error的指针 参量和所有到xxx_reset(), xxx_clear(), xxx_add() 和 xxx()调用一样。你可以用这个来提醒你获取一个错误或无论xxx()是否返回NULL的一个结果。你不能把一个字符串存到*error!error指向单字节变量而不是字符串缓冲区。
*is_null 对每一个组都重置(调用xxx_clear()前), *error 从不重置。
如果 xxx()返回时,*is_null 或 *error 被设置,MySQL返回 NULL作为组函数的结果。