• Home
• Libraries
• Participation
• Bugs

lib_mysqludf_udf

This library lib_mysqludf_udf contains a number of functions that allows one to look directly at the internal structures passed to the UDF. It is primarily intended for UDF authors to debug UDFs and to verify what MySQL passes to the UDF.

The udf_arg_% functions in this library correspond directly to the st_udf_args structure defined in mysql_com.h (This header file should be located in the include directory beneath the MySQL installation directory):

enum Item_result {STRING_RESULT=0, REAL_RESULT, INT_RESULT, ROW_RESULT,
                  DECIMAL_RESULT};

typedef struct st_udf_args
{
  unsigned int arg_count;		/* Number of arguments */
  enum Item_result *arg_type;		/* Pointer to item_results */
  char **args;				/* Pointer to argument */
  unsigned long *lengths;		/* Length of string arguments */
  char *maybe_null;			/* Set to 1 for all maybe_null args */
  char **attributes;                    /* Pointer to attribute name */
  unsigned long *attribute_lengths;     /* Length of attribute arguments */
} UDF_ARGS;

This structure is used to represent the arguments passed to a user defined function. Some of its usage is described "argument processing"-section in the mysql reference manual.

The udf_init_% functions correspond to the XXX_init function.

1. udf_arg_attribute - returns the value of the first entry in the attributes array member of the UDF_ARGS structure passed to the UDF.
2. udf_arg_attribute_length - returns the value of the first entry in the attribute_lengths array member of the UDF_ARGS structure passed to the UDF.
3. udf_arg_count - returns the value of the arg_count member of the UDF_ARGS structure passed to the UDF.
4. udf_arg_maybe_null - returns the value of the first entry in the maybe_null array member of the UDF_ARGS structure passed to the UDF.
5. udf_arg_type - returns the value of the first entry in the arg_type array member of the UDF_ARGS structure passed to the UDF.
6. udf_arg_value - returns the value of the first entry in the args array member of the UDF_ARGS structure passed to the UDF.
7. udf_arg_value_is_constant - returns true if the first member of the args array member of the UDF_ARGS structure passed to the UDF is not a null pointer, indicating a constant argument.
8. udf_arg_value_is_null - returns true if the args array member of the UDF_ARGS structure passed to the UDF is a NULL pointer in the row-level function, indicating a NULL argument.
9. udf_arg_value_length - returns the value of the first entry in the lengths array member of the UDF_ARGS structure passed to the UDF.
10. udf_init_const_item - Returns the value of the const_item member of the UDF_INIT structure.
11. udf_init_maybe_null - Returns the value of the maybe_null member of the UDF_INIT structure.
12. udf_init_decimals - Returns the value of the decimals member of the UDF_INIT structure.
13. udf_init_max_lengths - Returns the value of the max_lengths member of the UDF_INIT structure.
14. udf_init_error - Raises an error. Arguments are passed, the first 255 byes of the first argument are used as error message.

Use lib_mysqludf_udf_info() to obtain information about the currently installed version of lib_mysqludf_udf.

udf_arg_attribute

udf_arg_attribute takes one argument of any type and returns the value of the first entry of the attributes array member of the UDF_ARGS struct passed to the UDF. The function is thus implemented:

*length = args->attribute_lengths[0];
return args->attributes[0];

Syntax

udf_attribute(arg1)

Parameters and Return Values

arg1

Any expression of any type.

returns

The value of the corresponding attributes entry. The semantics of the attributes member of the UDF_ARGS struct is not documented, but it seems to be the "name" of the expression text passed to the argument. See the examples for more information.

Installation

Place the shared library binary in an appropriate location. Log in to mysql as root or as another user with sufficient privileges, and select any database. Then, create the function using the following DDL statement:

CREATE FUNCTION udf_arg_attribute RETURNS STRING SONAME 'lib_mysqludf_udf.so';	
	

The function will be globally available in all databases. The deinstall the function, run the following statement:

DROP FUNCTION udf_arg_attribute;
	

Examples

The following example would suggest the attributes array of the UDF_ARGS struct contains the expression texts of the respective arguments:

mysql> select udf_arg_attribute(film_id)
    -> from   sakila.film
    -> limit  1;
+----------------------------+
| udf_arg_attribute(film_id) |
+----------------------------+
| film_id                    |
+----------------------------+
1 row in set (0.16 sec)

However, the following example indicates that it is actually the name of the passed expression rather than the expression text itself:

mysql> select udf_arg_attribute(film_id as id)
    -> from   sakila.film
    -> limit  1;
+----------------------------------+
| udf_arg_attribute(film_id as id) |
+----------------------------------+
| id                               |
+----------------------------------+
1 row in set (0.00 sec)

See also

• udf_arg_attribute_length

udf_arg_attribute_length

arg_attribute_length takes one argument of any type and returns the value of the first entry of the attribute_lengths array member of the UDF_ARGS struct passed to the UDF. The function is thus implemented:

return args->attribute_lengths[0];

Syntax

udf_arg_attribute_length(arg1)

Parameters and Return Values

arg1

Any expression of any type.

returns

The value of the corresponding attribute_lengths entry. The semantics of the attribute_lengths member of the UDF_ARGS struct is not documented, but it seems to be the string length of the corresponding entry in the attributes member of UDF_ARGS

Installation

Place the shared library binary in an appropriate location. Log in to mysql as root or as another user with sufficient privileges, and select any database. Then, create the function using the following DDL statement:

CREATE FUNCTION udf_arg_attribute_length RETURNS INTEGER SONAME 'lib_mysqludf_udf.so';	
	

The function will be globally available in all databases. The deinstall the function, run the following statement:

DROP FUNCTION udf_arg_attribute_length;
	

Examples

The following examples seem to indicate that the attributes and attribute_lengths arrays are related to each other like the args and the lengths arrays: contains the expression texts of the respective arguments:

mysql> select udf_arg_attribute(film_id)
    -> ,      udf_arg_attribute_length(film_id)
    -> from   sakila.film
    -> limit  1;
+----------------------------+-----------------------------------+
| udf_arg_attribute(film_id) | udf_arg_attribute_length(film_id) |
+----------------------------+-----------------------------------+
| film_id                    |                                 7 |
+----------------------------+-----------------------------------+
1 row in set (0.00 sec)

mysql> select udf_arg_attribute(film_id as id)
    -> ,      udf_arg_attribute_length(film_id as id)
    -> from   sakila.film
    -> limit  1;
+----------------------------------+-----------------------------------------+
| udf_arg_attribute(film_id as id) | udf_arg_attribute_length(film_id as id) |
+----------------------------------+-----------------------------------------+
| id                               |                                       2 |
+----------------------------------+-----------------------------------------+
1 row in set (0.00 sec)

See also

• udf_arg_attribute

udf_arg_count

udf_arg_count takes any number of arguments of any type and returns the value of the arg_count member of the UDF_ARGS struct passed to the UDF. The function is thus implemented:

return args->arg_count;

Syntax

udf_arg_count([arg1,...,argN])

Parameters and Return Values

arg1,...,argN

A list of zero or more expressions of any type.

returns

The value of the arg_count member of the UDF_ARGS struct passed to the UDF. The value should be equal to the number of arguments in the argumentlist.

Installation

Place the shared library binary in an appropriate location. Log in to mysql as root or as another user with sufficient privileges, and select any database. Then, create the function using the following DDL statement:

CREATE FUNCTION udf_arg_count RETURNS INTEGER SONAME 'lib_mysqludf_udf.so';	
	

The function will be globally available in all databases. The deinstall the function, run the following statement:

DROP FUNCTION udf_arg_count;
	

Examples

mysql> select udf_arg_count();
+-----------------+
| udf_arg_count() |
+-----------------+
|               0 |
+-----------------+
1 row in set (0.00 sec)

mysql> select udf_arg_count(1,2,3);
+----------------------+
| udf_arg_count(1,2,3) |
+----------------------+
|                    3 |
+----------------------+
1 row in set (0.00 sec)

udf_arg_maybe_null

udf_arg_maybe_null takes one argument of any type and returns the value of the first entry of the maybe_null array member of the UDF_ARGS struct passed to the UDF. The function is thus implemted:

return args->maybe_null[0];

Syntax

udf_maybe_null(arg1)

Parameters and Return Values

arg1

Any expression of any type.

returns

The value of the corresponding maybe_null entry. The value 1 indicates the argument can be NULL; a value of 0 indicates the argument will never be NULL.

Installation

Place the shared library binary in an appropriate location. Log in to mysql as root or as another user with sufficient privileges, and select any database. Then, create the function using the following DDL statement:

CREATE FUNCTION udf_arg_maybe_null RETURNS INTEGER SONAME 'lib_mysqludf_udf.so';	
	

The function will be globally available in all databases. The deinstall the function, run the following statement:

DROP FUNCTION udf_arg_maybe_null;
	

Examples

None yet.

udf_arg_type

udf_arg_type takes one argument of any type and returns the value of the first entry of the arg_type array member of the UDF_ARGS struct passed to the UDF. The function is thus implemted:

return args->arg_type[0];

Syntax

udf_arg_type(arg1)

Parameters and Return Values

arg1

Any expression of any type.

returns

The value of the corresponding arg_type entry. This returns one of the values of the Item_result enum declared in mysql_com.h. The values are:

• STRING_RESULT - numerically 0. The argument is a string value.
• REAL_RESULT - numerically 1. The argument is a floating point value.
• INT_RESULT - numerically 2. The argument is an integer type.
• DECIMAL_RESULT - numerically 4. The argument is a string that represents a decimal value.

The Item_result enum also defines the ROW_RESULT entry (numerically 3), but this is currently never passed.

Installation

Place the shared library binary in an appropriate location. Log in to mysql as root or as another user with sufficient privileges, and select any database. Then, create the function using the following DDL statement:

CREATE FUNCTION udf_arg_type RETURNS INTEGER SONAME 'lib_mysqludf_udf.so';	
	

The function will be globally available in all databases. The deinstall the function, run the following statement:

DROP FUNCTION udf_arg_type;
	

Examples

The following function illustrates the effect of different types:

mysql> select udf_arg_type('')   //STRING_RESULT
    -> ,      udf_arg_type(pi()) //REAL_RESULT
    -> ,      udf_arg_type(1)    //INT_RESULT
    -> ,      udf_arg_type(1.1)  //DECIMAL_RESULT
    -> ;
+------------------+--------------------+-----------------+-------------------+
| udf_arg_type('') | udf_arg_type(pi()) | udf_arg_type(1) | udf_arg_type(1.1) |
+------------------+--------------------+-----------------+-------------------+
|                0 |                  1 |               2 |                 4 |
+------------------+--------------------+-----------------+-------------------+

udf_arg_value

udf_arg_value takes one argument of any type and returns the string value of the first entry of the args array member of the UDF_ARGS struct passed to the UDF. The function is thus implemented:

*length = args->lengths[0];
return args->args[0];

Syntax

udf_arg_value(arg1)

Parameters and Return Values

arg1

Any expression of any type.

returns

The string value of the corresponding args entry. This represents the actual value of the argument.

Installation

Place the shared library binary in an appropriate location. Log in to mysql as root or as another user with sufficient privileges, and select any database. Then, create the function using the following DDL statement:

CREATE FUNCTION udf_arg_value RETURNS STRING SONAME 'lib_mysqludf_udf.so';	
	

The function will be globally available in all databases. The deinstall the function, run the following statement:

DROP FUNCTION udf_arg_value;
	

Examples

None Yet.

See also

• udf_arg_value_length

udf_arg_value_length

udf_arg_value_length takes one argument of any type and returns the value of the first entry of the lengths array member of the UDF_ARGS struct passed to the UDF. The function is thus implemted:

return args->lengths[0];

Syntax

udf_value_length(arg1)

Parameters and Return Values

arg1

Any expression of any type.

returns

The value of the corresponding lengths entry. This is the number of bytes in the corresponding entry in the args array that contains the value for the argument.

Installation

Place the shared library binary in an appropriate location. Log in to mysql as root or as another user with sufficient privileges, and select any database. Then, create the function using the following DDL statement:

CREATE FUNCTION udf_arg_value_length RETURNS INTEGER SONAME 'lib_mysqludf_udf.so';	
	

The function will be globally available in all databases. The deinstall the function, run the following statement:

DROP FUNCTION udf_arg_value_length;
	

Examples

None yet.

See also

• udf_arg_value

udf_init_error

udf_init_error Raises an error. If an argument is passed, the first 255 bytes of the first argument are used as error message. The function is implemented in the XXX_init function:

	char *msg;
	int unsigned msg_length;
	if(args->arg_count>0){
		args->arg_type[0] = STRING_RESULT;
		msg = args->args[0];
		msg_length = args->lengths[0]>255?255:args->lengths[0]
	} else {
		msg = "";
		msg_length = 0;
	}
	memcpy(
		message
	,	msg
	,	msg_length
	);
	message[msg_length] = '';
	return 1;

Syntax

udf_init_error([arg1])

Parameters and Return Values

arg1

Optional. If passed, the first 255 bytes are used as error message. Otherwise,the default error message is used.

returns

Nothing - the function fails before it can return a proper result.

Installation

Place the shared library binary in an appropriate location. Log in to mysql as root or as another user with sufficient privileges, and select any database. Then, create the function using the following DDL statement:

CREATE FUNCTION udf_init_error RETURNS INTEGER SONAME 'lib_mysqludf_udf.so';	
	

The function will be globally available in all databases. The deinstall the function, run the following statement:

DROP FUNCTION udf_init_error;
	

Examples

Just raise an error:

mysql> select udf_init_error();
ERROR 1123 (HY000): Can't initialize function 'udf_init_error';
	

Raise an error with a custom message:

mysql> select udf_init_error('Error - can''t proceed.');
ERROR:
Error - can't proceed.