34. Функции, определенные пользователем (UDF)

Функции, определенные пользователем (User Defined Functions, UDF), — это программы, написанные на любом языке программирования, и хранящиеся в библиотеках dll (для Linux — so). Они существенно расширяют возможности SQL по обработке данных.

Примечание

Поддержка внешних UDF функций (реализованных в динамических библиотеках и определенных в базе данных с помощью функций оператора DECLARE EXTERNAL FUNCTION) в РЕД Базе Данных 5 устарела.

34.1. Объявление в базе данных UDF

Для того чтобы функция стала доступной в операторах SQL, необходимо выполнить оператор DECLARE EXTERNAL FUNCTION, который объявляет существующую функцию, определенную пользователем. Его синтаксис:

Листинг 34.1 Синтаксис оператора DECLARE EXTERNAL FUNCTION

DECLARE EXTERNAL FUNCTION <имя UDF>
    [<тип данных> [{BY DESCRIPTOR} | NULL] | CSTRING (<целое>) [NULL]
    [, <тип данных> [{BY DESCRIPTOR} | NULL] | CSTRING (<целое>) [NULL] ...]]
RETURNS {
      <тип данных> [BY VALUE | BY DESCRIPTOR]
    | CSTRING (<целое>)
    | PARAMETER <номер> }
[FREE_IT]
ENTRY_POINT '<имя точки входа>'
MODULE_NAME '<имя модуля>';

Объявить внешнюю функцию может пользователь с административными привилегиями и пользователь с привилегией CREATE FUNCTION. Пользователь, объявивший внешнюю функцию, становится её владельцем.

Имя UDF — то имя, которое будет использоваться при обращении к функции в операторах SQL. Это имя может отличаться от имени точки входа.

После имени функции перечисляются входные параметры, передаваемые функции. Параметры разделяются запятыми. Для каждого параметра указывается либо тип данных SQL, либо ключевое слово CSTRING. Это ключевое слово означает, что параметр является строкой символов, которая заканчивается нулевым значением. В скобках за этим словом задается максимальное число символов, которое может присутствовать в строке, включая завершающее нулевое значение.

По умолчанию входные параметры передаются по ссылке. При передаче NULL значения по ссылке оно преобразовывается в эквивалент нуля, например, число 0 или пустую строку. Если после указанного параметра указано ключевое слово NULL, то при передаче значение NULL оно попадёт в функцию в виде нулевого указателя.

Обязательное предложение RETURNS описывает возвращаемый функцией выходной параметр. Функция UDF всегда возвращает ровно одно значение. Можно указать тип данных SQL, строку, завершающуюся нулевым значением (CSTRING) или ключевое слово PARAMETER, за которым следует число. Ключевое слово PARAMETER используется, когда возвращается значение типа BLOB. Номер задает порядковый номер входного возвращаемого параметра.

Функция может получать произвольное количество входных параметров или ни одного. Каждая функция возвращает одно значение указанного типа. При обращении к функции, определенной пользователем, необходимо после имени функции в скобках указать передаваемые функции параметры. Если функция не получает входных параметров, то обязательно нужно записать круглые скобки.

Ключевое слово BY VALUE означает, что результат возвращается по значению, а не по ссылке (по умолчанию значение возвращается по ссылке).

Ключевое слово BY DESCRIPTOR задает передачу параметров по дескриптору.

Ключевое слово FREE_IT означает, что память, выделенная для хранения возвращаемого значения, должна быть освобождена после завершения выполнения функции. Применяется только в том случае, если эта память в UDF выделялась динамически.

Предложение ENTRY_POINT указывает имя точки входа для функции в модуле.

Предложение MODULE_NAME задает имя модуля, в котором находится описываемая функция. В ссылке на модуль может отсутствовать полный путь и расширение файла. По умолчанию динамические библиотеки пользовательских функций должны располагаться в папке UDF корневого каталога сервера. Параметр UDFAccess в файле firebird.conf позволяет изменить ограничения доступа к библиотекам внешних функций.

34.2. Изменение точки входа или имени модуля для UDF

Оператор ALTER EXTERNAL FUNCTION позволяет изменить в функции UDF имя точки входа и/или имя модуля. Его синтаксис:

Листинг 34.2 Синтаксис оператора ALTER EXTERNAL FUNCTION

ALTER EXTERNAL FUNCTION <имя UDF>
[ENTRY_POINT '<имя точки входа>']
[MODULE_NAME '<имя модуля>'];

Имя UDF — имя существующей функции.

Предложение ENTRY_POINT указывает новое имя точки входа для функции в модуле.

Предложение MODULE_NAME задает новое имя модуля, в котором находится описываемая функция.

Изменить внешнюю функцию может администратор, владелец функции (ее создатель) или пользователь с привилегией ALTER ANY FUNCTION.

34.3. Удаление объявления UDF из базы данных

Оператор DROP EXTERNAL FUNCTION удаляет объявление функции определённой пользователем из базы данных. Если есть зависимости от внешней функции, то удаления не произойдёт и будет выдана соответствующая ошибка.

Листинг 34.3 Синтаксис оператора DROP EXTERNAL FUNCTION

DROP EXTERNAL FUNCTION <имя UDF>;

Удалить внешнюю функцию может администратор, владелец функции (ее создатель) или пользователь с привилегией DROP ANY FUNCTION.