DECLARE EXTERNAL FUNCTIONのソース

[[FrontPage]]へ~
-[[リファレンスガイド]]へ~
--[[Firebird SQLリファレンス]]へ~
&br;
----
*Firebird SQLリファレンス:DECLARE EXTERNAL FUNCTION, DECLARE FILTER, DROP EXTERNAL FUNCTION, DROP FILTER [#w875ac1a]

#contents

----
&br;
&aname(declaer_external_function);
*DECLARE EXTERNAL FUNCTION [#h393f2d9]
　事前に用意されたユーザー定義関数(UDF)をデータベースで宣言します。
SQL,DSQL,isql で使用できます。~

**構文 [#c0b07989]

 DECLARE EXTERNAL FUNCTION name
   [datatype | CSTRING (int) [, datatype | CSTRING (int) …]]
   RETURNS {datatype [BY VALUE] | CSTRING (int)} [FREE_IT]
   ENTRY_POINT 'entryname'
   MODULE_NAME 'modulename';

&br;
※　DSQLで使用する場合、終端文字のセミコロンは不要です。
isql及びC/C++の埋め込みSQLでは行の終わりを示すために終端文字は必要です。
&br;
&br;
※　UDFの返す値として動的に確保されたメモリに対する参照を返す場合は、必ず
FREE_ITキーワードの指定を行い、そのメモリを解放するように指示しなければ
なりません。~
&br;
&br;


|引数|説明|h
|name|SQL文上で使用する、UDFの名前。後述のENTRY_POINTで指定する名前と異なっていても構いません。|
|datatype|入力引数または返り値のデータ型です。|
|~|・すべての入力パラメータは、参照渡しでUDFに渡されます。|
|~|・返り値は値渡しが可能です。|
|~|・配列要素は使用できません。|
|CSTRING (int)|UDF用の特殊なデータ型です。指定した長さ以下のNULL終端文字列(一般的なC言語での文字列)を表します。|
|RETURNS|関数の返り値に関する指定を行います。|
|BY VALUE|返り値の渡し方が、(参照渡しではなく)値渡しであることを指定します。|
|FREE_IT|UDFに関する処理が終了した後に、返り値のために確保されたメモリの解放を行います。|
|~|・UDFが動的にメモリを確保している場合にのみ使用します。|
|~|・より詳細な情報が知りたい場合は、Language Reference の Chapter 5 を参照して下さい。|
|'entryname'|UDFライブラリ内での関数名です。ソースコードでの名前を指定します。|
|'modulename'|UDFが含まれるライブラリを識別する名前です。ライブラリは、以下に示す条件の何れかにより指定する必要があります。|
|~|・構成ファイルで指定したディレクトリ(通常は"インストールディレクトリ/UDF")下の場合はパス指定は不要です。(訳注:Firebird1.5以降では、設定ファイルで複数ケースのディレクトリパスの指定が可能です。)|
|~|・指定ディレクトリ以外を指定する場合は、設定ファイルの指定に合致するそのシステムに適応した完全なパス名を指定する必要があります。Windowsサーバの場合には、ドライブの指定を含めることも出来ます。|
|~|・(訳注)設定ファイルに関しては、[[設定ファイル(aliases.conf/firebird.conf)のリファレンス]]を参照して下さい。|
|~|・これ以上の情報が欲しい場合は、Developer's Guide の UDF の章を参照して下さい。|
&br;

**詳細の説明 [#c46b44c7]
　DECLARE EXTERNAL FUNCTION により、データベースに対してUDFに関する次のような
情報を明示します。それは、(UDFライブラリの)存在場所、名前、いくつかの入力パラメータと
戻り値などです。~
　UDFを使用する場合、それが使用されるデータベースごとに宣言を
行う必要があります。~
　UDF自体の機能に変更が加えられても、エントリポイントやモジュール名が変更
されない限り、UDFを再度宣言しなおす必要はありません。(訳注:再宣言は不要でも
データベースの再起動は行う必要があるかもしれません。)~
&br;

　entryname は、UDFライブラリに格納された関数の実際の名前です。この名前と
データベースに格納され使用されるUDFの名前とを一致させる必要はありません。~
&br;

　モジュール名(modulename)の指定には、ファイルのディレクトリパスを含む必要
はありません。しかし、モジュール(UDFライブラリ)を設置する場所を設定ファイル
に正しく設定する必要があります。~
(訳注:''Firebird 1.5以上''では、使用は全く推奨されませんが、制限を解除する
ことが可能です。この場合にはパスを正しく指定する必要があります。詳しくは、
[[設定ファイル(aliases.conf/firebird.conf)のリファレンス]]を参照して下さい。)~
-''Firebird 1.0.x''の場合、設定ファイルによりパスを指定する場合は、次のように
設定します。
--Windows(ドライブの指定が必要)
 EXTERNAL_FUNCTION_DIRECTORY D:\Mylibraries
--UNIX/Linux/NetWare(ドライブ指定不要)
 EXTERNAL_FUNCTION_DIRECTORY /Mylibraries

-''Firebird 1.5以降''の場合は次のようして設定します。詳細は、
[[設定ファイル(aliases.conf/firebird.conf)のリファレンス]]を参照して下さい。
--Windows(ドライブの指定が必要)
 UdfAccess = Restrict D:\Mylibraries
--UNIX/Linux/NetWare(ドライブ指定不要)
 UdfAccess = Restrict /Mylibraries

&br;

　設定ファイルのファイル名はバージョン及び環境によって異なります。具体的には、
以下のようになっています。
-Firebird 1.0.x / IB6
--Windows : ibconfig
--UNIX系 : isc_config
--NetWare : isc_conf
-Firebird 1.5以降~
　firebird.conf

※※※※※ NetWareに関しては完全にレガシーサポートなので訳を割愛 ※※※※※~
FOR NETWARE SERVERS Beginning with InterBase 5.6, the UDF library is statically linked to NetWare servers so that the UDFs are available as external functions. To make them available to a database on a Netware server, follow htese steps:~
&br;
1. On a Windows client, connect to the database where you need the functions.~
2. Run the ib_udf.sql script that is located in the ib_install_dir/Examples/UDF directory (InterBase 6 and later) or Examples/API directory (InterBase 5.6) using ISQL with the -i switch: ~
&br;

**用例 [#a1bb9a59]
　すべて isql での例です。
-現在のデータベースで、TOPS()という UDF を宣言します。~
戻り値の型がCSTRING,CHAR,VARCHARデータ型の場合のみ動的確保を必要としますので、
この例のようにINTEGERを返す場合は FREE_IT は指定しません。
 DECLARE EXTERNAL FUNCTION TOPS
   CHAR(256), INTEGER, BLOB
   RETURNS INTEGER BY VALUE
   ENTRY_POINT 'te1' MODULE_NAME 'tm1.dll';
&br;

-LOWERS() という UDF を宣言します。このUDFでは、値を返すためにメモリの確保を
行っていますので、FREE_ITを指定しています。
 DECLARE EXTERNAL FUNCTION LOWERS VARCHAR(256)
   RETURNS CSTRING(256) FREE_IT
   ENTRY POINT 'fn_lower' MODULE_NAME 'udflib.dll';
&br;

**参照 [#m23d5a9b]
　[[DROP EXTERNAL FUNCTION>#drop_external_function]]~
&br;

　UDF自体を記述する方法に関しては、Developer's Guide の Working with UDFs を
参照して下さい。~
&br;


&br;
&br;
----
&br;
&br;
&aname(declare_filter);
*DECLARE FILTER [#z7bc415a]
　BLOBフィルタをデータベースで宣言します。
SQL,DSQL,isql で使用できます。~

**構文 [#e843878d]

 DECLARE FILTER filter
   INPUT_TYPE subtype OUTPUT_TYPE subtype
   ENTRY_POINT 'entryname' MODULE_NAME 'modulename';

&br;
※　DSQLで使用する場合、終端文字のセミコロンは不要です。
isql及びC/C++の埋め込みSQLでは行の終わりを示すために終端文字は必要です。
&br;
&br;

|引数|説明|h
|filter|フィルタの名前です。データベース内においてフィルタ中一意である必要があります。|
|INPUT_TYPE subtype|変換するデータのBLOBサブタイプを指定します。|
|OUTPUT_TYPE subtype|変換後のデータのBLOBサブタイプを指定します。|
|'entryname'|BLOBフィルタが格納されたリンクするライブラリ内での名前です。|
|'modulename'|BLOBフィルタが格納されたライブラリを識別する名前です。|
&br;

**詳細の説明 [#ce81a26f]
　DECLARE FILTER により、事前に用意したBLOBフィルタに関する次のような情報を
データベースに明示します。それは、(ライブラリの)存在場所、名前、
入出力サブタイプなどです。~
　BLOBフィルタとは、ユーザが記述できるプログラムで、異なるサブタイプのBLOB
間での変換を行うものです。~
&br;
　INPUT_TYPE と OUTPUT_TYPE の両者の指定により、BLOBフィルターの動作を決定
します。データベースにおいて宣言されたすべてのBLOBフィルター間では、両者で
指定する整数の組合わせは一意であるべきです。テキストを取り扱うために、
データベースエンジンには"1"の値が組み込まれています。ユーザーがサブタイプを
定義する場合には、これらの規定の値と衝突しないようにしなければなりません。~
&br;

　entryname は、ライブラリに格納されたBLOBフィルタの名前です。
アプリケーションがフィルタ機能を使用するとき、この名前を持ったフィルタ関数
が呼び出されます。~
&br;

''重要''　NetWareサーバでは DECLARE FILTER は使用できません。~
&br;


**用例 [#zbb204c6]
　isqlで、BLOBフィルタを宣言します。
 DECLARE FILTER DESC_FILTER
   INPUT_TYPE 1
   OUTPUT_TYPE -4
   ENTRY_POINT 'desc_filter'
   MODULE_NAME 'FILTERLIB';
&br;

**参照 [#p87b6bba]

　[[DROP FILTER>#drop_filter]]~
&br;

　BLOBフィルタを記述したい場合は、Embedded SQL Guide を参照して下さい。~
　これ以上の情報が欲しい場合は、[[キャラクタセット・データ型・権限]]の
データ型・BLOBサブタイプの補足や、Data Definition Guide の "Blob subtypes"
を参照して下さい。~
&br;


&br;
&br;
----
&br;
&br;
&aname(drop_external_function);
*DROP EXTERNAL FUNCTION [#zd2eb682]
　データベースから、ユーザー定義関数(UDF)の定義を削除します。
SQL,DSQL,isql で使用できます。~


**構文 [#u06aab15]

 DROP EXTERNAL FUNCTION name;

&br;
※　DSQLで使用する場合、終端文字のセミコロンは不要です。
isql及びC/C++の埋め込みSQLでは行の終わりを示すために終端文字は必要です。
&br;
&br;

|引数|説明|h
|name|定義の削除を行う、既存UDFの名前です。|
&br;

**詳細の説明 [#c76af6eb]
　DROP EXTERNAL FUNCTION により、UDFの定義をデータベースより削除します。
データベースからUDFの定義を削除しても、そのUDFが所属するUDFライブラリから
は削除されませんが、データベースからそのUDFにアクセスすることが出来なく
なります。UDFの定義が削除されると、それに依存しているアプリケーションすべて
においてランタイムエラーが発生するでしょう。~
&br;

　UDF定義の削除は、作成者、SYSDBAユーザーもしくはOSのルート権限を持った
ユーザーのみが実行できます。~
&br;

※※※※※ NetWareに関しては完全にレガシーサポートなので訳を割愛 ※※※※※~
''Important'' UDFs are not available for databases on NetWare servers. If a UDF is accidentally declared for a database on a NetWare server, DROP EXTERNAL FUNCTION should be used to remove the declaration.~
&br;

**用例 [#u83cc5c4]
　isqlで、UDF定義を削除します。
 DROP EXTERNAL FUNCTION TOPS;
&br;

**参照 [#y9f960f2]
　[[DECLARE EXTERNAL FUNCTION>#declaer_external_function]]~
&br;


&br;
&br;
----
&br;
&br;
&aname(drop_filter);
*DROP FILTER [#x904b6d9]
　データベースから、BLOBフィルタの定義を削除します。
SQL,DSQL,isql で使用できます。~


**構文 [#b854f507]

 DROP FILTER name;

&br;
※　DSQLで使用する場合、終端文字のセミコロンは不要です。
isql及びC/C++の埋め込みSQLでは行の終わりを示すために終端文字は必要です。
&br;
&br;

|引数|説明|h
|name|定義の削除を行う、既存のBLOBフィルタの名前です。|
&br;

**詳細の説明 [#ue1187a0]
　DROP FILTER により、BLOBフィルタの定義をデータベースより削除します。
データベースからBLOBフィルタの定義を削除しても、そのフィルタが所属する
フィルタライブラリからは削除されませんが、データベースからそのフィルタに
アクセスすることが出来なくなります。
フィルタの定義が削除されると、それに依存しているアプリケーションすべて
においてランタイムエラーが発生するでしょう。~
&br;

　何らかの処理でフィルタが使用中の場合、DROP FILTER は失敗しエラーを
返します。~
&br;

　BLOBフィルタ定義の削除は、作成者、SYSDBAユーザーもしくはOSのルート権限
を持ったユーザーのみが実行できます。~
&br;


''重要''　NetWareサーバでは BLOBフィルタ機能は使用できません。~
&br;

**用例 [#pfa36d30]
　isqlで、BLOBフィルタの削除を行います。~
 DROP FILTER DESC_FILTER;
&br;


**参照 [#cfc83c30]
　[[DECLARE FILTER>#declare_filter]]~
&br;