Последовательность вызова UDF для простых функций
Главная функция должна быть определена, как это показано здесь. Обратите внимание на то, что тип возвращаемого значения и параметры варьируются в зависимости от того, как определена SQL-функция XXX() в команде CREATE FUNCTION - как возвращающая STRING, INTEGER или REAL:
Для STRING-функций:
char *xxx(UDF_INIT *initid, UDF_ARGS *args,
char *result, unsigned long *length,
char *is_null, char *error);
Для INTEGER-функций:
long long xxx(UDF_INIT *initid, UDF_ARGS *args,
char *is_null, char *error);
Для REAL-функций:
double xxx(UDF_INIT *initid, UDF_ARGS *args,
char *is_null, char *error);
Функции инициализации и деинициализации объявляются следующим образом:
my_bool xxx_init(UDF_INIT *initid, UDF_ARGS *args, char *message);
void xxx_deinit(UDF_INIT *initid);
Параметр initid передается всем трем функциям. Он указывает на структуру UDF_INIT, используемую для передачи информации между функциями. Поля структурыUDF_INIT перечислены ниже. Функция инициализации должна заполнять все поля, которые ей следует изменить (чтобы использовать для поля значение по умолчанию, его необходимо оставить в неизменном виде):
my_bool maybe_null
xxx_init() должна устанавливать maybe_null в 1, если xxx() может возвращать NULL. Значение по умолчанию будет 1, если хоть один аргумент объявлен какmaybe_null.
unsigned int decimals
Количество знаков после запятой. По умолчанию используется максимальное количество знаков для аргументов, переданных в основную функцию. (Например, если функции передаются 1,34, 1,345 и 1,3, то значением по умолчанию будет 3, поскольку 1,345 имеет 3 знака после запятой.
unsigned int max_length
Максимальная длина строкового результата. Значение по умолчанию зависит от типа результата функции. Для строковых функций по умолчанию используется размер наиболее длинного аргумента. Для целочисленных функций значение по умолчанию составляет 21 цифру. Для вещественных функций по умолчанию берется 13 плюс количество знаков после запятой, которое задается initid->decimals (для числовых функций длина включает знак и символ десятичной точки). Если требуется возвращать значение типа BLOB, то поле можно установить равным либо 65 Kб либо 16 Mб; эта память не распределяется, а применяется для определения того, какой использовать тип столбцов, если понадобится временно хранить данные.
char *ptr
Указатель, используемый функцией по своему усмотрению. Например, функции могут применять initid->ptr для передачи между функциями распределенной памяти. В xxx_init() память распределяется и назначается этому указателю:
initid->ptr = allocated_memory;
В xxx() и xxx_deinit() должны обращаться к initid->ptr для использования или освобождения памяти.
Последовательность вызова UDF для агрегатных функций
Ниже приведено описание функций, которые необходимо определить при создании агрегатной UDF-функции.
char *xxx_reset(UDF_INIT *initid, UDF_ARGS *args,
char *is_null, char *error);
Эта функция вызывается, когда MySQL находит первую строку в новой группе. В функции необходимо сбросить все внутренние переменные, в которых накапливаются значения, и затем установить переданный аргумент как первый аргумент в группе.
Во многих случаях это реализуется путем сброса всех переменных и последующего вызова xxx_add().
char *xxx_add(UDF_INIT *initid, UDF_ARGS *args,
char *is_null, char *error);
Эта функция вызывается для всех строк, принадлежащих к одной группе, за исключением первой. В функции к внутренней накопительной переменной следует добавить значение UDF_ARGS.
Функция xxx() должна быть объявлена точно так же, как это делается при определении простой UDF-функции
Вызов этой функции происходит, когда все строки в группе обработаны. Обычно функция не должна обращаться к переменной args, а возвращаемое значение должно базироваться на внутренних накопительных переменных.
Какая бы то ни было, обработка аргументов в xxx_reset() и xxx_add() должна проводиться точно так же, как для нормальных UDF-функций
Организация возврата значений в xxx() эквивалентна используемой для нормальной UDF
Аргументы-указатели is_null и error одинаковы для всех вызовов xxx_reset(), xxx_add() и xxx(). Их можно использовать для запоминания того, что произошла ошибка, или когда функция xxx() должна возвращать NULL. Заметьте, что сохранять строку в *error нельзя! Это всего лишь 1-байтовый флаг!
is_null сбрасывается для каждой группы (перед вызовом xxx_reset()). error не сбрасывается никогда.
Если is_null или error окажется установленным после xxx(), MySQL вернет NULL в качестве результата групповой функции.
Обработка аргументов
Параметр args указывает на структуру UDF_ARGS, содержащую перечисленные ниже поля:
unsigned int arg_count
Количество аргументов. Это значение следует проверять в функции инициализации, если необходимо, чтобы функция вызывалась с определенным количеством аргументов. Например:
if (args->arg_count != 2)
{
strcpy(message,"XXX() requires two arguments");
return 1;
}
enum Item_result *arg_type
Тип для каждого аргумента. Возможные значения типа: STRING_RESULT, INT_RESULT и REAL_RESULT. Чтобы контролировать принадлежность аргументов к нужному типу и возвращать ошибку, если это не так, следует проверить массив arg_type в функции инициализации. Например:
if (args->arg_type[0] != STRING_RESULT ||
args->arg_type[1] != INT_RESULT)
{
strcpy(message,"XXX() requires a string and an integer");
return 1;
}
В качестве альтернативы требованию, чтобы аргументы были определенного типа, можно использовать функцию инициализации для назначения элементам arg_type выбранных типов. В этом случае MySQL будет приводить аргументы к этим типам для каждого вызова xxx(). Например, чтобы указать на приведение первых двух аргументов к строковому и целочисленному типам, выполните в xxx_init():
args->arg_type[0] = STRING_RESULT;
args->arg_type[1] = INT_RESULT;
char **args
args->args передает в функцию инициализации информацию общего характера об аргументах, с которыми была вызвана функция. Для константного аргументаi args->args[i] указывает на значение аргумента (ниже приведены инструкции о том, как правильно получать доступ к значениям). Для неконстантого аргумента args->args[i] есть 0. Константный аргумент - это выражение, в котором используются только константы, вроде 3 или 4*7-2 или SIN(3.14). Неконстантный аргумент - это выражение, ссылающееся на значения, которые могут изменяться от строки к строке, такие как имена столбцов или обращения к функциям с неконстантными аргументами.
Для каждого вызова главной функции args->args содержит фактические аргументы, переданные для обрабатываемой в данный момент строки.
Функции могут ссылаться на аргумент i следующим образом:
Аргумент типа STRING_RESULT передается в виде указателя на строку плюс длина, чтобы обеспечить обработку двоичных данных или данных произвольной длины. Содержимое строки доступно посредством args->args[i], а длина строки представляет собой args->lengths[i]. Не следует исходить из предположения, что символ \0 отмечает конец строки.
Для аргумента типа INT_RESULT необходимо привести args->args[i] к значению типа long long:
long long int_val;
int_val = *((long long*) args->args[i]);
Для аргумента типа REAL_RESULT необходимо привести args->args[i] к значению типа double:
double real_val;
real_val = *((double*) args->args[i]);
unsigned long *lengths
Для функции инициализации массив lengths указывает максимальную длину строки для каждого аргумента. Изменять этот массив нельзя. При каждом вызове главной функции lengths содержит фактические длины всех строковых аргументов, переданных для обрабатываемой в текущий момент строки. Для типов аргументов INT_RESULT или REAL_RESULT lengths также содержит максимальную длину аргумента (как для функции инициализации).