Книга: Firebird РУКОВОДСТВО РАЗРАБОТЧИКА БАЗ ДАННЫХ

Внешние функции (UDF)

Внешние функции (UDF)

Внешние функции являются вспомогательными программами, написанными на языке программирования, таком как С, C++ или Pascal, и скомпилированными как совместно используемые двоичные библиотеки- DLL в Windows или совместно используемые объекты для других платформ, которые поддерживают динамическую загрузку. Как и стандартные встроенные функции SQL, внешние функции могут быть разработаны для выполнения преобразований или вычислений, реализация которых либо слишком сложна, либо вовсе невозможна средствами языка SQL.

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

Фрагмент "определенные пользователем" в названии функций означает, что вы можете писать свои собственные функции. Возможности создания пользовательских функций для вашего сервера Firebird ограничиваются лишь вашей изобретательностью и умением программировать на включающем языке. Допустимо включение статистических, строковых, математических функций, функций даты, подпрограмм форматирования данных и даже пользовательского процессора для выполнения регулярных выражений (regular expression, regexes).

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

Firebird поставляется с двумя предварительно встроенными библиотеками внешних функций. Библиотеки совместно используемых объектов размещаются по умолчанию в каталоге /UDF корневого каталога Firebird. Расширения файлов:

* dll - для Windows;

* so - для других поддерживаемых платформ.

Библиотека ib udf- библиотека полезных базовых функций- наследуется Firebird от своего предшественника InterBase. Она нужна для вызова некоторых утилит управления памятью, которые находятся в совместно используемом объекте с именем ib utii, размещенном в каталоге /bin. Эта библиотека передает параметры по значению или по ссылке в согласованном стиле InterBase. В некоторых подпрограммах исправлены ошибки для Firebird, так что не используйте версии, поставляемые с продуктами Borland.

Библиотеку fbudf создал Клавдио Валдеррама (Claudio Valderrama). Она передает параметры через дескрипторы Firebird, что является наиболее надежным способом гарантировать отсутствие внутренних ошибок в результате выделения памяти и преобразования типов.

Свободно доступными также являются некоторые библиотеки UDF, включая библиотеку FreeUDFLib, вначале написанную Грегори Диц (Gregory Deatz) для Borland Delphi. Библиотека FreeUDFLib содержит большое количество функций для строк, математических операций, типов данных BLOB и даты. Она поддерживалась, корректировалась и дополнялась разными людьми в течение многих лет. Будьте внимательны при получении версии этой библиотеки, которая правильно работает в диалекте 3 с типами данных даты и времени. Такая версия для Windows доступна на http://www.ibase.ru. Исходный код на С для версии POSIX доступен как FreeUDFLibC, однако на момент написания этой главы не было надежного бинарного кода, доступного для загрузки.

Коды внешних модулей являются по своей сути уязвимыми для злоумышленников и небрежных администраторов. Как-никак это просто файлы файловой системы.

В Firebird 1.0.x вы можете- и должны- явно сконфигурировать положение библиотек внешних функций на сервере, используя параметр externai_function_directory в файле конфигурации (isc config для серверов POSIX и ibconfig для Windows). Это следует сделать администратору базы данных для обеспечения того, что библиотеки не будут перезаписаны - случайно или неавторизованными посетителями.

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

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

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

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

Объявление функции для базы данных информирует эту базу данных относительно:

* имени, с которым функция будет использована в операторах SQL. В объявлении вы можете использовать свое собственное имя- см. следующие замечания по синтаксису;

* количества аргументов и их типов данных;

* типа данных возвращаемого значения;

* имени (ENTRY_POINT), С которым функция существует в библиотеке;

* имени библиотеки (MODULE_NAME), которая содержит функцию; Синтаксис декларации:

DECLARE EXTERNAL FUNCTION имя [тип-данных | CSTRING (целое)

[, тип-данных | CSTRING (целое) ...]]

RETURNS {тип-данных [BY VALUE] | CSTRING (целое)} [FREE_IT]

[RETURNS PARAMETER n]

ENTRY_POINT 'точка-входа'

MODULE_NAME 'имя -модуля';

Табл. 21.8 подробно описывает аргументы.

Таблица 21.8. Аргументы оператора DECLARE EXTERNAL FUNCTION

Большинство библиотек внешних функций поставляется вместе с их собственными скриптами DDL, содержащими объявления для каждой функции и, обычно, некоторую краткую документацию. Существует соглашение именовать скрипт так же, как и библиотеку, но с использованием расширения файла SQL или sql. Однако не все общедоступные библиотеки придерживаются этого соглашения.

Скрипты ib udf.sql и fbudf.sql находятся в каталоге /UDF вашего каталога инсталляции сервера. Комплект FreeUDFLib содержит скрипт с именем extfuncs.sql. Вы можете свободно копировать и вставлять объявления для компоновки вашей собственной библиотеки из любимых объявлений.

Следующее объявление является примером из скрипта ib udf.sql:

DECLARE EXTERNAL FUNCTION ipad

CSTRING(80), INTEGER, CSTRING(1)

RETURNS CSTRING(80) FREE_IT

ENTRY_POINT 'IB_UDF_lpad' MODULE_NAME 'ib_udf';

Следующее объявление содержится в fbudf, оно передает аргументы по дескриптору в некоторые функции:

DECLARE EXTERNAL FUNCTION sright

VARCHAR(100) BY DESCRIPTOR, SMALLINT,

VARCHAR(100) RETURNS PARAMETER 3

ENTRY POINT 'right' MODULE_NAME 'fbudf';

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

Иногда вам может понадобиться объявить одну и ту же функцию для вашей базы данных более одного раза. Пока вы используете различные имена в EXTERNAL FUNCTION, вы можете объявлять функцию, имеющую те же ENTRY_POINT и MODULE_NAME, столько раз, сколько вам нужно.

! ! !

ВНИМАНИЕ! Никогда не изменяйте аргумент ENTRY_POINT. Аргумент MODULE_NAME не должен изменяться за исключением случая, когда необходимо использовать полный путь к библиотеке (см. разд. "Пути в объявлениях функций").

. ! .

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

Если вам нужен аргумент для строковой функции, имеющий размер больший, чем значение по умолчанию, объявите аргумент в соответствии с вашими требованиями, убедитесь, что входные и выходные данные согласованы друг с другом и ни один аргумент не превышает максимального для VARCHAR значения 32 765 байт - заметьте: байтов, а не символов.

В следующем примере функция, описанная в скрипте fbudf.sql как sright, объявляется с именем srirgt2000, а размер параметров изменяется до 200 байт:

DECLARE EXTERNAL FUNCTION sright200

VARCHAR(200) BY DESCRIPTOR, SMALLINT,

VARCHAR (200) RETURNS PARAMETER 3

ENTRY_POINT 'right' MODULE_NAME ' fbudf' ;

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

В версии 1.0.x нужно будет Сконфигурировать параметр external_function_directory в iscconfig/ibconfig для каждой платформы, на которой эти функции будут использоваться, поскольку эта версия не содержит "пути по умолчанию" для модулей функций. По умолчанию должен работать каталог /UDF, однако практика показывает, что это ненадежно без явно заданной конфигурации.

Для Firebird 1.5 и выше существуют другие режимы конфигурации (UDFAccess) для размещения библиотек функций (см. главу 36), включая RESTRICT, который позволяет задать для них один или более каталогов. Если вы используете RESTRICT, то в объявление нужно включить полный путь к модулю и расширение файла. В этом случае база данных не будет переносима на другую операционную систему, пока вы не удалите из базы данных функции и их зависимости.

Следующий пример показывает объявление функции с указанием полного пути:

DECLARE EXTERNAL FUNCTION lpad

CSTRING(80) , INTEGER, CSTRING(1)

RETURNS CSTRING(80) FREE_IT

ENTRY_POINT ' IB_UDF_lpad' MODULE_NAME '/opt/extlibs/ib_udf .so' ;

Приложение 1 содержит детальное описание с примерами внешних функций из библиотек ib_udf и fbudf из каталога /UDF каталога инсталляции Firebird, а также многие функции из FreeUDFLib.

Важность использования логики выражений для трансформации абстрактных данных в осмысленную информацию аналогична важности использования средств SQL по слиянию данных из множества таблиц в один набор связанных данных. В следующей главе мы рассмотрим существующие в DML способы выполнения таких многотабличных операций. Эта глава заканчивается специальной темой оптимизации запросов Firebird и использованием планов запросов (предложение PLAN) В запросах SELECT.

Оглавление книги