Шрифт:
Объявление функции для базы данных информирует эту базу данных относительно:
* имени, с которым функция будет использована в операторах 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
Аргумент | Описание |
имя | Имя UDF для использования в операторах SQL. Может отличаться от имени, указанного после ключевого слова ENTRY POINT. Если вы используете существующую библиотеку, то хорошо бы изменить предоставляемое имя - хотя бы для того, чтобы устранить путаницу при объявлении той же функции с другими именами в других базах данных |
тип-данных | Тип данных для входного или возвращаемого параметра. Если аргументы не передаются по дескриптору, это тип данных включающего языка. Все входные параметры передаются в UDF по ссылке или по дескриптору. Возвращаемые параметры могут передаваться по ссылке, по значению или по дескриптору. Тип данных не может быть массивом или элементом массива |
RETURNS | Спецификация возвращаемого значения функции |
BY VALUE | Указывает, что возвращаемое значение должно передаваться по значению, а не по ссылке |
CSTRING( целое) | Указывает, что UDF возвращает значение в виде строки с нулевым терминатором с максимальной длиной целое байтов |
FREE_IT | Освобождает память возвращаемого значения после завершения выполнения UDF. Используйте это, только если память в UDF выделяется динамически с использованием функции ib_util_malloc, определенной в библиотеке ib_util. Библиотека ib_util должна находиться в каталоге /bin, чтобы вариант FKEE_IT мог работать |
RETURNS PARAMETER n | Указывает, что функция возвращает n-й входной параметр. Это требуется для возвращения типов данных BLOB |
точка-входа | Заключенная в апострофы строка, задающая имя, под которым UDF присутствует в исходном коде и сохранена в библиотеке UDF |
имя-модуля | Заключенная в апострофы спецификация файла, идентифицирующая библиотеку, которая содержит UDF |
Большинство библиотек внешних функций поставляется вместе с их собственными скриптами 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 позволяет это сделать.