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

Функции, описанные в Создание пользовательских функций, расширены на этой странице. Они объявляются следующим образом:

Простые функции

x()

Если x() возвращает целое число, она объявляется следующим образом:

long long x(UDF_INIT *initid, UDF_ARGS *args,
              char *is_null, char *error);

Если x() возвращает строку (функции DECIMAL также возвращают строковые значения), она объявляется следующим образом:

char *x(UDF_INIT *initid, UDF_ARGS *args,
          char *result, unsigned long *length,
          char *is_null, char *error);

Если x() возвращает вещественное число, она объявляется следующим образом:

double x(UDF_INIT *initid, UDF_ARGS *args,
              char *is_null, char *error);

x_init()

my_bool x_init(UDF_INIT *initid, UDF_ARGS *args, char *message);

x_deinit()

void x_deinit(UDF_INIT *initid);

Описание

initid — параметр, передаваемый во все три функции, указывающий на структуру UDF_INIT, используемую для передачи информации между функциями. Члены её структуры:

• my_bool maybe_null
  • maybe_null должен быть установлен в 1, если x_init может вернуть значение NULL, по умолчанию 1, если какие-либо аргументы объявлены как maybe_null.
• unsigned int decimals
  • Количество знаков после запятой. По умолчанию, если явное количество знаков после запятой передано в аргументы основной функции, используется максимальное количество знаков. Например, если функции переданы 9.5, 9.55 и 9.555, по умолчанию будет три знака (исходя из 9.555, максимальное). Если явное количество знаков не указано, по умолчанию устанавливается 31, или на один больше максимального для типов DOUBLE, FLOAT и DECIMAL. Это значение по умолчанию может быть изменено в функции, чтобы соответствовать фактическому расчету.
• unsigned int max_length
  • Максимальная длина результата. Для целых чисел по умолчанию 21. Для строк — длина самого длинного аргумента. Для вещественных чисел — по умолчанию 13 плюс количество знаков после запятой, указанное в initid->decimals. Длина включает знаки и десятичную точку. Также может быть установлено в 65 КБ или 16 МБ для возвращения BLOB. Память не выделяется, но это используется для определения типа данных, который следует использовать, если данные нужно временно сохранить.
• char *ptr
  • Указатель, используемый по мере необходимости функцией. Обычно initid->ptr используется для передачи выделенной памяти, при этом x_init() выделяет память и присваивает её этому указателю, x() использует её, а x_deinit() её освобождает.
• my_bool const_item
  • Должен быть установлен в 1 в x_init(), если x() всегда возвращает одно и то же значение, в противном случае 0.

Функции агрегирования

x_clear()

x_clear() — обязательная функция для функций агрегирования, и она объявляется следующим образом:

void x_clear(UDF_INIT *initid, char *is_null, char *error);

Она вызывается, когда результаты сводки должны быть сброшены, то есть в начале каждой новой группы. Но также для сброса значений, когда не было совпадающих строк.

is_null устанавливается в CHAR(0) перед вызовом x_clear().

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

x_reset()

x_reset() объявляется следующим образом:

void x_reset(UDF_INIT *initid, UDF_ARGS *args,
               char *is_null, char *error);

Она вызывается при обнаружении первой строки в новой группе. Должна сбросить переменные сводки, а затем использовать UDF_ARGS в качестве первого значения во внутренней переменной сводки группы. Функция не требуется, если интерфейс UDF использует x_clear().

x_add()

x_add() объявляется следующим образом:

void x_add(UDF_INIT *initid, UDF_ARGS *args,
             char *is_null, char *error);

Она вызывается для всех строк, принадлежащих одной группе, и должна использоваться для добавления значения в UDF_ARGS к внутренней переменной сводки.

x_remove()

x_remove() была добавлена в MariaDB 10.4 и объявляется следующим образом (аналогично x_add()):

void x_remove(UDF_INIT* initid, UDF_ARGS* args,
               char* is_null, char *error );

Она добавляет более эффективную поддержку функций агрегирования UDF, как функции окон. x_remove() должна "вычитать" строку (обратить x_add()). В MariaDB 10.4 функции агрегирования UDF будут работать как функции окон без x_remove(), но это будет не так эффективно.

Если x_remove() поддерживается (определена), она определяется автоматически.