DECLARE EXTERNAL FUNCTION

FrontPageへ

• リファレンスガイドへ
  
  • Firebird SQLリファレンスへ
    
    

Firebird SQLリファレンス:DECLARE EXTERNAL FUNCTION, DECLARE FILTER, DROP EXTERNAL FUNCTION, DROP FILTER

DECLARE EXTERNAL FUNCTION

　事前に用意されたユーザー定義関数(UDF)をデータベースで宣言します。 SQL,DSQL,isql で使用できます。

構文

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

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

※　UDFの返す値として動的に確保されたメモリに対する参照を返す場合は、必ず FREE_ITキーワードの指定を行い、そのメモリを解放するように指示しなければ なりません。

詳細の説明

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

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

　モジュール名(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

　設定ファイルのファイル名はバージョン及び環境によって異なります。具体的には、 以下のようになっています。

• 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:

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:

用例

　すべて 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';

  
  

• LOWERS() という UDF を宣言します。このUDFでは、値を返すためにメモリの確保を 行っていますので、FREE_ITを指定しています。

  DECLARE EXTERNAL FUNCTION LOWERS VARCHAR(256)
    RETURNS CSTRING(256) FREE_IT
    ENTRY POINT 'fn_lower' MODULE_NAME 'udflib.dll';

  
  

参照

　DROP EXTERNAL FUNCTION

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

DECLARE FILTER

　BLOBフィルタをデータベースで宣言します。 SQL,DSQL,isql で使用できます。

構文

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

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

詳細の説明

　DECLARE FILTER により、事前に用意したBLOBフィルタに関する次のような情報を データベースに明示します。それは、(ライブラリの)存在場所、名前、 入出力サブタイプなどです。
　BLOBフィルタとは、ユーザが記述できるプログラムで、異なるサブタイプのBLOB 間での変換を行うものです。

　INPUT_TYPE と OUTPUT_TYPE の両者の指定により、BLOBフィルターの動作を決定 します。データベースにおいて宣言されたすべてのBLOBフィルター間では、両者で 指定する整数の組合わせは一意であるべきです。テキストを取り扱うために、 データベースエンジンには"1"の値が組み込まれています。ユーザーがサブタイプを 定義する場合には、これらの規定の値と衝突しないようにしなければなりません。

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

重要　NetWareサーバでは DECLARE FILTER は使用できません。

用例

　isqlで、BLOBフィルタを宣言します。

DECLARE FILTER DESC_FILTER
  INPUT_TYPE 1
  OUTPUT_TYPE -4
  ENTRY_POINT 'desc_filter'
  MODULE_NAME 'FILTERLIB';

参照

　DROP FILTER

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

DROP EXTERNAL FUNCTION

　データベースから、ユーザー定義関数(UDF)の定義を削除します。 SQL,DSQL,isql で使用できます。

構文

DROP EXTERNAL FUNCTION name;

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

詳細の説明

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

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

※※※※※ 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.

用例

　isqlで、UDF定義を削除します。

DROP EXTERNAL FUNCTION TOPS;

参照

　DECLARE EXTERNAL FUNCTION

DROP FILTER

　データベースから、BLOBフィルタの定義を削除します。 SQL,DSQL,isql で使用できます。

構文

DROP FILTER name;

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

詳細の説明

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

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

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

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

用例

　isqlで、BLOBフィルタの削除を行います。

DROP FILTER DESC_FILTER;

参照

　DECLARE FILTER