* Функции UDF должны выделять память с использованием функции ib_utii_ maiioc из библиотеки ib_util, а не с помощью статических массивов.
* Выделенная динамически память не освобождается автоматически, пока процесс не завершится. Вы должны использовать зарезервированное слово FREE IT при объявлении UDF в базе данных (DECLARE EXTERNAL FUNCTION).
* Статические переменные не сохраняются в потоке. Пользователи, выполняющие параллельно одну и ту же UDF, будут конкурировать, если они обратятся к одному пространству статической памяти. Неразумно использовать статические переменные, если вы не можете гарантировать, что только один пользователь в каждый конкретный момент времени будет обращаться к этой функции.
Если вы не можете исключить возвращаемый указатель на статические данные, вы не должны использовать FREE_IT.
Функция ib utii maiioc находится в вашем каталоге Firebird /lib, в совместно используемой библиотеке ib util.so в POSIX, ib_util.dll в Windows и ib utii.sl в HP-UX. Прототип функции для С и Pascal содержится в каталоге /include в файлах ib util.h и ib util.pas соответственно.
При не поточном использовании Классического сервера вы можете возвращать глобальный указатель. В следующем примере функции FN LOWERO массив должен быть глобальным, чтобы исключить выход за пределы контекста:
char buffer[256];
char *fn_lower(char *ups) {
return (buffer); }
При распределении памяти под возвращаемые значения для обеспечения потокобезопасности и переносимости следует использовать функцию ib_ut.ii_maiioc(). Вместе с ней нужно применять также ключевое слово FREE_IT В предложении RETURNS при объявлении функции, которая возвращает динамически создаваемые объекты.
В следующем примере сервер Firebird освободит буфер, если UDF была определена с зарезервированным словом FREE IT. Обратите внимание, что этот пример использует функцию Firebird ib_utii_maiioc() для выделения памяти:
char *fn_lower(char *ups) {
char *buffer = (char *) ib util_malloc(256);
return (buffer); }
Вот ее объявление:
DECLARE EXTERNAL FUNCTION lowercase VARCHAR (25 6)
RETURNS CSTRING(256) FREE_IT
ENTRY POINT 'fn lower' MODULE_NAME 'ib_udf';
! ! !
ПРИМЕЧАНИЕ. Память должна освобождаться той же библиотекой времени выполнения, которая выделяла эту память.
. ! .
Когда модуль UDF готов, компилируйте его обычным образом в объектный или библиотечный формат.
Включите ibase.h или его эквивалент, если вы используете в нем объявления типов.
Если сборка выполняется статически, свяжите модуль с клиентской библиотекой Firebird, если вы обращаетесь к какой-либо функции библиотеки Firebird. Для Microsoft Visual C/C++ библиотеки fbclient ms.lib и ib_util_ms.lib могут быть найдены в каталоге Firebird /lib.
Для включения UDF в существующий модуль внешней функции добавьте файл, содержащий объектный код новой UDF, и перекомпилируйте как обычно. Некоторые платформы позволяют добавлять объектные файлы непосредственно в существующие библиотеки. Относительно подробностей посмотрите документацию по компилятору и редактору связей для конкретной платформы.
Для удаления функции следуйте инструкциям редактора связей по удалению объектов из библиотеки. Удаление функции из библиотеки не удаляет ее объявления из базы данных - используйте для этого DROP EXTERNAL FUNCTION.
Функции BLOB отличаются от других внешних функций, потому что им передаются указатели па управляющие структуры BLOB, а не на фактические данные. Функция не может открывать и закрывать BLOB, а вместо этого вызывает функции API для выполнения доступа к BLOB.
Управляющая структура BLOB является структурой языка С, определенной в функциональном модуле в виде typedef. Программисты должны описать такую управляющую структуру на языке С, т. е. должны написать следующее:
typedef struct blob {
short (*blob_get_segment)();
isc_blob_handle blob_handle;
long number_segments;
long max_seglen;
long total_size;
void (*blob_put_segment)();
} *Blob;
Табл. 36.1 описывает поля в управляющей структуре BLOB.
Таблица 36.1. Поля в управляющей структуре BLOB[145]
Поле |
Описание |
blob get segment |
NULL, если внешняя функция не принимает BLOB в качестве входного аргумента. Иначе это поле является указателем на функцию, которая вызывается для чтения сегмента BLOB. Данная функция получает четыре аргумента: дескриптор BLOB, адрес буфера для сегмента BLOB, размер буфера и адрес переменной для хранения размера сегмента BLOB |
blob handle |
Требуемое поле. Это дескриптор BLOB, который уникально идентифицирует BLOB, передаваемый функции или возвращаемый функцией |
number segments |
NULL, если внешняя функция не принимает BLOB в качестве входного аргумента. В противном случае задает общее количество сегментов в BLOB |
max seglen |
NULL, если внешняя функция не принимает BLOB в качестве входного аргумента. В противном случае задает в байтах размер наибольшего передаваемого сегмента |
total size |
NULL, если внешняя функция не принимает BLOB в качестве входного аргумента. В противном случае задает в байтах фактический размер всего BLOB как единого целого |
blob_put segment |
NULL, если внешняя функция не принимает BLOB в качестве входного аргумента. В противном случае содержит указатель на функцию, которая вызывается для записи сегмента в BLOB. Эта функция принимает три аргумента: дескриптор BLOB, адрес буфера, содержащего данные для записи в BLOB, и размер в байтах записываемых данных |
Функция BLOB объявляется в базе данных с использованием DECLARE EXTERNAL FUNCTION с тем отличием, что тип ее объявления помещается перед ключевым словом RETURNS в качестве последнего аргумента в списке параметров вместо возвращаемого значения. Для аргумента RETURNS используйте ключевое слово PARAMETER и порядковый номер последнего параметра. Например, следующий оператор объявляет функцию BLOB, biob_pius_biob в модуле внешних функций с именем MyExtLib:
DECLARE EXTERNAL FUNCTION blob_plus_blob
Blob,
Blob,
Blob
RETURNS PARAMETER 3
ENTRY_POINT 'blob_concat' MODULE_NAME 'MyExtLib';
Учебник по написанию внешних функций доступен на сайте сообщества Firebird. Множество толковых статей можно найти в базах знаний и через поисковые машины.
Фильтры BLOB
В главе 12 мы коснулись специального типа внешних функций, которые могут быть использованы в Firebird для преобразования данных BLOB между двумя форматами, способными представлять совместимые данные. Фильтры BLOB являются определенными пользователем служебными подпрограммами на стороне сервера - фактически, специализированными UDF - способными получать данные BLOB В одном формате, преобразовывать их и возвращать в виде BLOB другого формата. Один раз скомпилированный и объявленный в базе данных, фильтр BLOB может быть использован в обычных операторах DML в клиентских приложениях, хранимых процедурах, триггерах и в isql.
145
Определена в ibase.h как blobcallback (структурный тип) и BLOBCALLBACK (указатель на структурный тип). Это объявление дает полное определение для функций чтения/записи указателей, которые упрощают использование их в современных компиляторах. См. также примечания перед объявлением в ibase.h.