Возвращаемые значения и обработка ошибок

Функция инициализации должна возвращать 0, если ошибок нет, и 1 в противном случае. Если происходит ошибка, xxx_init() должна поместить сообщение об ошибке с завершающим '\0' в параметр message. Сообщение будет возвращено клиенту. Буфер сообщения имеет длину MYSQL_ERRMSG_SIZE символов, но надо стараться, чтобы сообщение не превышало 80 символов - для соответствия ширине стандартного экрана терминала.

Возвращаемое главной функцией xxx() значение является значением функции для функций long long и double. Строковые функции должны возвращать указатель на результат и помещать длину строки в аргумент length.

Эти величины следует устанавливать равными содержимому и длине возвращаемого значения. К примеру:

memcpy(result, "result string", 13);

*length = 13;

Размер буфера result, передаваемого вычислительной функции, составляет 255 байтов. Если этого достаточно для полученного результата, то о распределении памяти для результатов беспокоиться нечего.

Если строковая функция должна возвращать строку длиннее, чем 255 байтов, то для строки необходимо выделять память с помощью malloc() в функции xxx_init()или в функции xxx() и освобождать ее в функции xxx_deinit(). Указатель на распределенную память можно сохранить в поле ptr структуры UDF_INIT, чтобы в последующих вызовах xxx() использовать эту память повторно

Чтобы указать в главной функции на возврат значения NULL, is_null устанавливается в 1:

*is_null = 1;

Чтобы указать в главной функции на возврат ошибки, в 1 устанавливается параметр error:

*error = 1;

Если xxx() устанавливает для какой-либо строки *error в 1, то значение функции будет NULL для этой и всех последующих строк, обрабатываемых командой, в которой вызывается XXX() (для последующих строк xxx() даже не будет вызываться). Примечание: в версиях MySQL до 3.22.10 было необходимо устанавливать как *error так и *is_null:

*error = 1;

*is_null = 1;

Компиляция и установка определяемых пользователем функций

Файлы, реализующие UDFы, должны компилироваться и устанавливаться на машине, где работает сервер. Эта процедура описана ниже для файла примеров UDFudf_example.cc, входящего в поставку исходного кода MySQL. Данный файл содержит следующие функции:

metaphon() возвращает metaphon-строку для строкового аргумента. Эта строка в общем напоминает soundex-строку, но более приспособлена для английского языка.

myfunc_double() возвращает отношение суммы ASCII-значений символов своих аргументов к суммарной длине аргументов.

myfunc_int() возвращает суммарную длину своих аргументов.

sequence([const int]) возвращает последовательность, начиная с заданного номера, либо с 1, если номер не задан.

lookup() возвращает IP-адрес для имени удаленного компьютера.

reverse_lookup() возвращает имя удаленного компьютера для IP-адреса. Функция может вызываться для строки "xxx.xxx.xxx.xxx" либо для четырех чисел.

Динамически загружаемый файл должен компилироваться как разделяемый объектный файл с помощью команды следующего вида:

shell> gcc -shared -o udf_example.so myfunc.cc

Корректные опции компилятора для своей системы можно легко получить, запустив следующую команду в каталоге sql дерева исходных текстов MySQL:

shell> make udf_example.o

Следует выполнить команду компиляции, подобную приведенной выше make, с той разницей, что надо удалить опцию -c ближе к концу строки и добавить -oudf_example.so в конце строки (в некоторых системах, возможно, -c придется оставить в команде).

После компиляции разделяемого объектного файла, содержащего UDFы, следует установить его и дать о нем знать MySQL. В результате компиляции разделяемого объектного модуля из udf_example.cc получается файл с именем наподобие udf_example.so (точное имя может на разных платформах может быть различным). Скопируйте этот файл в какой-нибудь просматриваемый ld каталог, вроде /usr/lib. Во многих системах можно устанавливать переменную окружения LD_LIBRARY илиLD_LIBRARY_PATH для указания каталога, в котором размещены файлы UDF-функций. В руководстве по dlopen указывается, какую переменную следует использовать в данной системе. Необходимо сделать соответствующие установки в скриптах запуска mysql.server или safe_mysqld и перезапустить mysqld.

После установки библиотеки следует уведомить mysqld о новых функциях следующими командами:

mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME "udf_example.so";

mysql> CREATE FUNCTION myfunc_double RETURNS REAL SONAME "udf_example.so";

mysql> CREATE FUNCTION myfunc_int RETURNS INTEGER SONAME "udf_example.so";

mysql> CREATE FUNCTION lookup RETURNS STRING SONAME "udf_example.so";

mysql> CREATE FUNCTION reverse_lookup

-> RETURNS STRING SONAME "udf_example.so";

mysql> CREATE AGGREGATE FUNCTION avgcost

-> RETURNS REAL SONAME "udf_example.so";

Функции могут быть удалены с помощью DROP FUNCTION:

mysql> DROP FUNCTION metaphon;

mysql> DROP FUNCTION myfunc_double;

mysql> DROP FUNCTION myfunc_int;

mysql> DROP FUNCTION lookup;

mysql> DROP FUNCTION reverse_lookup;

mysql> DROP FUNCTION avgcost;

Команды CREATE FUNCTION и DROP FUNCTION обновляют системную таблицу func в базе данных mysql. В таблицу записываются имя функции, ее тип и имя разделяемой библиотеки. Для создания и удаления функций необходимо обладать привилегиями INSERT и DELETE для базы данных mysql.

Недопустимо использовать CREATE FUNCTION для добавления функции, которая уже была создана. Если необходимо переустановить функцию, ее следует удалить с помощью DROP FUNCTION и затем переустановить посредством CREATE FUNCTION. Эти действия приходится выполнять, например, когда компилируется новая версия данной функции, и надо, чтобы mysqld получил новую версию. Иначе сервер будет продолжать пользоваться старой версией.

Активные функции подгружаются при каждом запуске сервера, за исключением случая, когда mysqld запускается с опцией --skip-grant-tables. Тогда инициализация UDF пропускается и UDFы недоступны (активная функция - это функция, которая была загружена посредством CREATE FUNCTION и не удалена с помощью DROP FUNCTION).

Добавление новых родных функции

В этом разделе приведена процедура добавления новой ``родной'' функции. Следует учитывать, что в бинарную поставку ``родные'' функции добавить невозможно, поскольку эта процедура требует изменения исходного кода MySQL. Поэтому необходимо собственноручно компилировать MySQL из поставки исходного текста. Кроме того, при переходе на другую версию MySQL (например, при выпуске новой версии) все изменения придется повторить для этой новой версии.

Чтобы добавить новую ``родную'' функцию MySQL, необходимо выполнить следующие действия:

Добавьте в lex.h одну строку, определяющую имя новой функции в массиве sql_functions[].

Если прототип функции простой (вообще без аргументов или принимает один, два или три аргумента), то в lex.h вторым аргументом в массиве sql_functions[]следует указать SYM(FUNC_ARG#) (где # количество аргументов) и добавить в item_create.cc функцию, создающую объект функции. В качестве примеров можно рассмотреть ABS и create_funcs_abs(). Если прототип функции сложный (например, принимает переменное число аргументов), то следует добавить две строки вsql_yacc.yy. Одна строка служит для указания препроцессору, какой символ должен определить yacc (строку следует добавить в начало файла). Затем определяются параметры функции и правило разбора simple_expr пополняется "элементом" с этими параметрами. Чтобы получить представление о том, как это делается, в качестве примера просмотрите все вхождения ATAN в sql_yacc.yy.

В item_func.h объявляется класс, наследуемый от Item_num_func или Item_str_func, в зависимости от того, какое значение возвращает функция - числовое или строковое.

В item_func.cc добавьте одно из следующих объявлений, в зависимости от того, какая функция определяется - числовая или строковая:

double Item_func_newname::val()

longlong Item_func_newname::val_int()

String *Item_func_newname::Str(String *str)

Если объект наследуется от любого стандартного элемента (подобного Item_num_func), то, возможно, потребуется определить только одну из перечисленных выше функций и возложить на родительский объект заботу об остальных функциях. Например, класс Item_str_func определяет функцию val(), выполняющую atof() над значением, возвращенным::str().

Возможно, понадобится также определить следующую функцию объекта:

void Item_func_newname::fix_length_and_dec()

Эта функция должна как минимум вычислять max_length на основе переданных аргументов. max_length является максимальным количеством символов, которое может возвращать функция. Эта функция также должна устанавливать maybe_null = 0, если невозможно, чтобы главная функция возвратила значение NULL. Узнать, может ли какой-либо аргумент функции возвращать NULL, функция может путем проверки поля/переменной maybe_null аргумента. В качестве типичного примера того, как это делается, можно рассмотреть Item_func_mod::fix_length_and_dec.

Все функции должны поддерживать многопоточность (другими словами, непозволительно использовать какие-либо глобальные или статические переменные в функции без их защиты примитивами взаимного исключения).

Если желательно возвращать NULL, из::val(),::val_int() или::str(), то необходимо устанавливать null_value в 1 и возвращать 0.

Для функции объекта::str() существуют следующие дополнительные аспекты:

Аргумент String *str обеспечивает строковый буфер, который может быть использован для размещения результата (дополнительную информацию о типе String можно найти в файле sql_string.h).

Функция::str() должна возвращать строку, содержащую результат, или (char*) 0, если результат NULL.

На сегодняшний день при написании всех строковых функций принято избегать какого бы то ни было распределения памяти, за исключением случаев, когда это абсолютно необходимо!