Esta sección describe las distintas funciones que necesita definir cuando crea un UDF agregado. Sección 27.2.3, “Añadir una nueva función definida por el usuario” describe el orden en que MySQL llama a estas funciones.
xxx_reset()
Esta función se llama cuando MySQL encuentra el primer
registro en un nuevo grupo. Debe resetear cualquier
variable resumen interna y usar el argumento dado
UDF_ARGS
como primer valor en su
resumen interno del grupo. Declare
xxx_reset()
como se muestra:
char *xxx_reset(UDF_INIT *initid, UDF_ARGS *args, char *is_null, char *error);
xxx_reset()
se necesita sólo antes de
MySQL 4.1.1. NO se necesita usar
desde MySQL 4.1.1, cuando la interfaz UDF cambió para
usar xxx_clear()
en su lugar. Sin
embargo, puede definir xxx_reset()
y
xxx_clear()
si quiere que su UDF
funcione antes y después del cambio de interfaz. (Si no
incluye ambas funciones, la función
xxx_reset()
en muchos casos puede
implementarse internamente llamando
xxx_clear()
para resetear todas las
variables, y luego llamar xxx_add()
para añadir el argumento UDF_ARGS
como
primer valor del grupo.)
xxx_clear()
Esta función se llama cuando MySQL necesita resetear los
resultados resumen. Se llama al principio para cada nuevo
grupo pero sólo puede llamarse para resetear los valores
para una consulta donde no hubieran registros que
coincidan con la búsqueda. Declare
xxx_clear()
como sigue:
char *xxx_clear(UDF_INIT *initid, char *is_null, char *error);
is_null
se asigna para que apunte a
CHAR(0)
antes de llamar a
xxx_clear()
.
Si algo falla, puede almacenar un valor en la variable a
la que apunta el argumento error
.
error
apunta a una variable de un byte,
no a un búfer de cadenas de caracteres.
xxx_clear()
se requiere sólo a partir
de MySQL 4.1.1. Antes de MySQL 4.1.1, use
xxx_reset()
en su lugar.
xxx_add()
Esta función se llama para todos los registros que
pertenezcan al mismo grupo, excepto para el primer
registor. Debe ussarlo para añadir el valor en el
argumento UDF_ARGS
a su variable de
resumen interna.
char *xxx_add(UDF_INIT *initid, UDF_ARGS *args, char *is_null, char *error);
La función xxx()
para un UDF agregado debe
declararse de la misma forma que UDF no agregados. Consulte
Sección 27.2.3.1, “Secuencias de llamada UDF para funciones simples”.
Para un UDF agregado, MySQL llama a la función
xxx()
una vez que todos los registros en el
grupo han sido procesados. Normalmente no debe acceder el
argumento UDF_ARGS
aquí sino devolver un
valor basado en sus variables de resumen internas.
El tratamiento de valores retornados en
xxx()
debe hacerse del mismo modo que para
UDF no agregados. Consulte
Sección 27.2.3.4, “Valores de retorno y tratamiento de errores”.
Las funciones xxx_reset()
y
xxx_add()
tratan sus argumentos
UDF_ARGS
del mismo modo que las funciones
para UDFs no agregados. Consulte
Sección 27.2.3.3, “Proceso de argumentos”.
Los argumentos punteros de is_null
y
error
son los mismos para todas las
llamadas a xxx_reset()
,
xxx_clear()
, xxx_add()
y
xxx()
. Puede usar esto para recordar que
obtuvo un error o si la función xxx()
debería retornar NULL
. No debe almacenar
una cadena de caracteres en *error
!
error
apunta a una variable de un byte, no
a un búfer de cadenas de caracteres.
*is_null
se resetea para cada grupo (antes
de llamar xxx_clear()
).
*error
nunca se resetea.
Si *is_null
o *error
se
asignan cuando xxx()
retorna, MySQL retorna
NULL
como resultado para la función de
grupo.
Ésta es una traducción del manual de referencia de MySQL, que puede encontrarse en dev.mysql.com. El manual de referencia original de MySQL está escrito en inglés, y esta traducción no necesariamente está tan actualizada como la versión original. Para cualquier sugerencia sobre la traducción y para señalar errores de cualquier tipo, no dude en dirigirse a mysql-es@vespito.com.