Skip navigation links
27.2.3.3 Proceso de argumentos »
Section Navigation      [Toggle]

27.2.3.2. Secuencias de llamada UDF para funciones agregadas

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.