Хелен Борри - Firebird РУКОВОДСТВО РАЗРАБОТЧИКА БАЗ ДАННЫХ

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

! ! !

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

. ! .

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

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

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

В качестве примера передачи параметров по ссылке можно рассмотреть объявление функции в языке С 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.

. ! .

Функции 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.