29.4.3 Adding a New Native Function

Create a subclass for the function in item_create.cc:

To provide a name by which the function can be referred to in SQL statements, register the name in item_create.cc by adding a line to this array:

static Native_func_registry func_array[]

You can register several names for the same function. For example, see the lines for "LCASE" and "LOWER", which are aliases for Create_func_lcase.

In item_func.h, declare a class inheriting from Item_num_func or Item_str_func, depending on whether your function returns a number or a string.

In item_func.cc, add one of the following declarations, depending on whether you are defining a numeric or string function:

double   Item_func_newname::val()
longlong Item_func_newname::val_int()
String  *Item_func_newname::Str(String *str)

If you inherit your object from any of the standard items (like Item_num_func), you probably only have to define one of these functions and let the parent object take care of the other functions. For example, the Item_str_func class defines a val() function that executes atof() on the value returned by ::str().

If the function is nondeterministic, include the following statement in the item constructor to indicate that function results should not be cached:

current_thd->lex->safe_to_cache_query=0;

A function is nondeterministic if, given fixed values for its arguments, it can return different results for different invocations.

You should probably also define the following object function:

void Item_func_newname::fix_length_and_dec()

This function should at least calculate max_length based on the given arguments. max_length is the maximum number of characters the function may return. This function should also set maybe_null = 0 if the main function cannot return a NULL value. The function can check whether any of the function arguments can return NULL by checking the arguments' maybe_null variable. Look at Item_func_mod::fix_length_and_dec for a typical example of how to do this.