27.3.4.1. UDF Calling Sequences for Simple Functions
This section describes the different functions that you need
to define when you create a simple UDF.
Section 27.3.4, “Adding a New User-Defined Function”, describes the order in which
MySQL calls these functions.
The main xxx() function should be declared
as shown in this section. Note that the return type and
parameters differ, depending on whether you declare the SQL
function XXX() to return
STRING, INTEGER, or
REAL in the CREATE
FUNCTION statement:
For STRING functions:
char *xxx(UDF_INIT *initid, UDF_ARGS *args,
char *result, unsigned long *length,
char *is_null, char *error);
For INTEGER functions:
long long xxx(UDF_INIT *initid, UDF_ARGS *args,
char *is_null, char *error);
For REAL functions:
double xxx(UDF_INIT *initid, UDF_ARGS *args,
char *is_null, char *error);
The initialization and deinitialization functions are declared
like this:
my_bool xxx_init(UDF_INIT *initid, UDF_ARGS *args, char *message);
void xxx_deinit(UDF_INIT *initid);
The initid parameter is passed to all three
functions. It points to a UDF_INIT
structure that is used to communicate information between
functions. The UDF_INIT structure members
follow. The initialization function should fill in any members
that it wishes to change. (To use the default for a member,
leave it unchanged.)
-
my_bool maybe_null
xxx_init() should set
maybe_null to 1 if
xxx() can return
NULL. The default value is
1 if any of the arguments are declared
maybe_null.
-
unsigned int decimals
The number of decimal digits to the right of the decimal
point. The default value is the maximum number of decimal
digits in the arguments passed to the main function. (For
example, if the function is passed
1.34, 1.345, and
1.3, the default would be 3, because
1.345 has 3 decimal digits.
-
unsigned int max_length
The maximum length of the result. The default
max_length value differs depending on
the result type of the function. For string functions, the
default is the length of the longest argument. For integer
functions, the default is 21 digits. For real functions,
the default is 13 plus the number of decimal digits
indicated by initid->decimals. (For
numeric functions, the length includes any sign or decimal
point characters.)
If you want to return a blob value, you can set
max_length to 65KB or 16MB. This memory
is not allocated, but the value is used to decide which
data type to use if there is a need to temporarily store
the data.
-
char *ptr
A pointer that the function can use for its own purposes.
For example, functions can use
initid->ptr to communicate allocated
memory among themselves. xxx_init()
should allocate the memory and assign it to this pointer:
initid->ptr = allocated_memory;
In xxx() and
xxx_deinit(), refer to
initid->ptr to use or deallocate the
memory.
-
my_bool const_item
xxx_init() should set
const_item to 1 if
xxx() always returns the same value and
to 0 otherwise.
