Firebird РУКОВОДСТВО РАЗРАБОТЧИКА БАЗ ДАННЫХ

Библиотека в этом контексте является совместно используемым объектом, который обычно имеет расширение dll на платформе Windows, расширение so для UNIX и Solaris и расширение si на HP-UX. Она может содержать одну или более точек входа для функций, определенных пользователем.

! ! !

СОВЕТ. Каталог Firebird /examples содержит некоторые старые примеры make- файлов (makefile.be и makefile.msc для систем Windows, makefile для UNIX), которые создают библиотеку ib_udf function из ib_udf.c.

. ! .

Процесс создания UDF состоит из четырех шагов:

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

2. Скомпилируйте функцию и свяжите с динамически связываемой библиотекой (DLL) или с библиотекой совместно используемых объектов (SO) в соответствии с платформой.

3. Поместите библиотеку и любые требуемые символические ссылки в подходящее место на диске на серверной машине так, чтобы сервер мог получить к ней доступ в каталог по умолчанию /UDF или в альтернативный каталог, который вы сконфигурировали для библиотек внешних функций.

4. Используйте DECLARE EXTERNAL FUNCTION для объявления каждой индивидуальной UDF для каждой базы данных, в которой вам нужно ее использовать.

! ! !

ПРИМЕЧАНИЕ. Очень хорошей практикой является создание скрипта, содержащего объявления ваших UDF и некоторых комментариев, объясняющих использование.

. ! .

Написание модуля функции

На языке С UDF пишутся как любые стандартные функции. UDF может получать до десяти входных параметров и должна возвращать одно и только одно значение данных в качестве результата.

Исходный код модуля может определять одну или более функций. Если вы включите заголовочный файл Firebird ibase.h в ваш каталог Firebird /include при компиляции, ваш модуль С или C++ сможет использовать имеющиеся в нем определения типов (typedef). Возможности трансляции существуют и для других языков, включая Delphi. Например, исходный пакет для FreeUDFLib [143] от Gregory Deatz включает ibase.pas.

143

Общая библиотека UDF доступна на нескольких сайтах, включая http://www.ibphoenix.com.

Задание параметров

Параметры, не являющиеся BLOB или массивами, передаются функциям UDF либо по ссылке [144] с использованием типов данных включающего языка, допускающих преобразование в соответствующие типы данных Firebird, либо через дескриптор, используя предварительно определенную структуру, которая описывает тип данных Firebird во включающем языке. Может быть принято до десяти параметров, соответствующих любому типу данных Firebird за исключением массива или элемента массива. Если UDF возвращает BLOB, то количество входных параметров ограничивается девятью.

144

В терминах C++ "по указателю".

В качестве примера передачи параметров по ссылке можно рассмотреть объявление функции в языке С FN_ABSO, которая принимает один параметр, имеющий в С тип double. Когда вызывается FN_ABS, ей должен передаваться параметр, имеющий в SQL тип данных DOUBLE PRECISION.

Передача параметров через дескриптор появилась в Firebird 1.0, что позволяет передавать родные типы данных Firebird. Для некоторых внешних функций это упрощает обработку параметров NOLL и дает возможность перекрывать объявления. Структуру дескриптора параметра можно найти в ibase.h:

typedef struct paramdsc {

unsigned char dsc_dtype;

signed char dsc_scale;

ISC_OSHORT dsc_length;

short dsc_sub_type;

ISC_USHORT dsc_flags;

unsigned char *dsc_address;

} PARAMDSC;

Самое важное поле в структуре, конечно, dsc_dtype, потому что оно ответственно за трансляцию родных типов данных Firebird в типы данных включающего языка.

! ! !

СОВЕТ. Claudio Valderrama С., который выполнил реализацию передачи через дескриптор, представил детальное описание этого процесса в статье "Using descriptors with UDFs" (Использование дескрипторов в UDF) на http:// www.cvalde.net/document/using_descriptors_with_udfs.htm.

. ! .

Параметры BLOB

Функции UDF, которые принимают параметры BLOB, требуют для обработки специальной структуры данных, BLOB передается по ссылке в управляющей структуре BLOB, описанной в разд. "Написание функций BLOB".

Спецификация возвращаемого значения

К типам данных возвращаемых значений применяются те же самые ограничения, что и к входным параметрам: типы данных включающего языка должны соответствовать типам данных Firebird. Например, объявление в С для функции FN_ABSO возвращает значение типа double, который корреспондирует с типом данных DOUBLE PRECISION в Firebird.

По умолчанию возвращаемые значения передаются по ссылке. Числовые значения могут также возвращаться по значению, хотя это и не очень хороший метод, и он не рекомендован. Для возврата числового параметра по значению включите необязательное ключевое слово BY VALUE после возвращаемого значения при объявлении UDF в базе данных.

Символьные типы данных

В UDF необходимо использовать типы данных включающего языка как для входных, так и для выходных значений. Firebird должен иметь возможность выполнить трансляцию между объявленным типом и типом данных SQL. В случае строк входной строкой UDF является тип CSTRING С заданной максимальной длиной в байтах, CSTRING используется для трансляции входных типов CHAR и VARCHAR В строку языка С, завершающуюся нулем, для обработки и для возвращения строки языка С переменной длины, завершающуюся нулем, для автоматического преобразования в Firebird в типы CHAR или VARCHAR. В случае других включающих языков убедитесь, что ваша функция возвращает строки, завершающиеся нулем.

При объявлении UDF, которая возвращает строку языка С, CHAR или VARCHAR, В объявление должно быть добавлено ключевое слово FREE_IT для освобождения памяти, используемой для возвращаемого значения, если она была выделена с помощью функции ib_util_malloc.

Соглашения о вызовах

Соглашение о вызовах определяет, как вызывается функция и как передаются параметры. Функция, получающая вызов, должна быть совместима с соглашением о вызове CDECL, используемым в Firebird. В функциях на языке С при использовании соглашения о вызове CDECL в объявление функции должно быть добавлено зарезервированное слово cdeci. В языке Pascal используйте cdeci.

Вот пример на языке С, где задается CDECL:

ISC_TIMESTAMP* cdeci addmonth(ISC_TIMESTAMP *preTime)

{

// здесь тело функции

}

Вопросы поточной обработки

В реализации Суперсервера в Firebird сервер выполняется как один многопоточный процесс. Это означает, что вам нужно проявлять некоторую осторожность при использовании способов выделения и освобождения памяти при кодировании UDF, а также при объявлении UDF. При использовании памяти в одном процессе в многопоточной архитектуре необходимо рассмотреть некоторые вопросы.