Skip navigation links
MySQL 5.0 Reference Manual :: 27 Extender MySQL :: 27.2 Añadir nuevas funciones a MySQL :: 27.2.3 Añadir una nueva función definida por el usuario
27.2.3.1 Secuencias de llamada UDF para funciones simples »
Section Navigation      [Toggle]

27.2.3. Añadir una nueva función definida por el usuario

[+/-]

27.2.3.1. Secuencias de llamada UDF para funciones simples
27.2.3.2. Secuencias de llamada UDF para funciones agregadas
27.2.3.3. Proceso de argumentos
27.2.3.4. Valores de retorno y tratamiento de errores
27.2.3.5. Compilar e instalar funciones definidas por el usuario
27.2.3.6. Precauciones de seguridad en funciones definidas por usuarios

Para que funciones el mecanismo UDF, las funciones deben escribirse en C o C++ y su sistema operativo debe soportar carga dinámica. La distribución fuente de MySQL incluye un fichero sql/udf_example.cc que define 5 nuevas funciones. Consulte este fichero para ver cómo funcionan las convenciones de llamadas de UDF.

Para poder usar UDFs, necesita lincar mysqld dinámicamente. No configure MySQL usando --with-mysqld-ldflags=-all-static. Si quiere usar una UDF que necesite acceder a símbolos desde mysqld (por ejemplo la función metaphone en sql/udf_example.cc que usa default_charset_info), debe lincar el programa con -rdynamic (consulte man dlopen). Si planea usar UDFs, la rula es configurar MySQL con --with-mysqld-ldflags=-rdynamic a no ser que tenga una muy buena razón para no hacerlo.

Si usa una distribución precompilada de MySQL, use MySQL-Max, que contiene un servidor lincado dinámicamente que soporta carga dinámica.

Para cada función que quiera usar en comandos SQL, debe definir las funciones correspondientes en C (o C++). En la siguiente discusión, el nombre “xxx” se usa como nombre de función de ejemplo. Para distinguir entre el uso de SQL y C/C++ , XXX() (mayúsculas) indicata una llamada de función SQL, xxx() (minúsculas) indica una llamada de función C/C++ .

Las funciones C/C++ que escribe para implementar la interfaz para XXX() son:

  • xxx() (requerido)

    La función principal. Es donde el resultado de la función se computa. La correspondencia entre los tipos de datos de la función SQL y el tipo de retorno de la función C/C++ se muestra aquí:

    SQL Type C/C++ Type
    STRING char *
    INTEGER long long
    REAL double

  • xxx_init() (opcional)

    La función de inicialización para xxx(). Puede usarse para:

    • Chequea el número de argumentos para XXX().

    • Chequea que los argumentos son de un tipo requerido o, alternativamente, le dice a MySQL que coercione argumentos a los tipos que quiera cuando se llama a la función principal.

    • Reserva cualquier memoria requerida por la función principal.

    • Especifica la longitud máxima del resultado.

    • Especifica (para funciones REAL ) el máximo número de decimales.

    • Especifica si el resultado puede ser NULL.

  • xxx_deinit() (opcional)

    La función de deinicialización para xxx(). Debe liberar cualquier memoria reservada por la función de inicialización.

Cuando un comando SQL invoca XXX(), MySQL llama a la función de inicialización xxx_init() para que realice cualquier inicialización necesaria, tales como chequeo de argumentos o reserva de memoria. Si xxx_init() retorna un error, el comando SQL se aborta con un mensaje de error y no se llama ni a la función principal ni a la de deinicialización. En caso contrario, se llama a la función principal xxx() una vez para cada registro. Tras procesar todos los registros, se llama a la función de deinicialización xxx_deinit() para que pueda realizar cualquier limpieza requerida.

Para funciones agregadas que funcionan como SUM(), debe proporcionar las siguientes funciones:

  • xxx_reset() (necesaria antes de 4.1.1)

    Resetea el valor agregado actual e inserta el argumento como valor agregado inicial para un nuevo grupo.

  • xxx_clear() (requerido a partir de 4.1.1)

    Resetea el valor agregado actual pero no inserta el argumento como valor agregado inicial para un nuevo grupo.

  • xxx_add() (requerido)

    Añade el argumento al valor agregado actual.

MySQL trata UDFs agregados como sigue:

  1. Llama a xxx_init() para permitir a la función agregada reservar la memoria necesaria para ordenar resultados.

  2. Ordena la table según la expresión GROUP BY.

  3. Llama a xxx_clear() para el primer registro en cada grupo.

  4. Llama a xxx_add() para cada nuevo registro que permita al mismo grupo.

  5. Llama a xxx() para obtener el resultado del agregado cuando el grupo cambia o cuando el último registro se ha procesado.

  6. Repite 3-5 hasta que se procesan todos los registros

  7. Llama a xxx_deinit() para permitir al UDF liberar la memoria reservada.

Todas las funciones deben ser flujos seguros. Esto incluye no sólo la función principal,también las funciones de inicialización o deinicialización, y las funciones adicionales requeridas por las funciones agregadas. Una consecuencia de esta restricción es que no se le permite reservar ninguna variable global o estática que cambien! Si necesita memoria, debe reservarla en xxx_init() y liberarla en xxx_deinit().

É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.