SQL 解説書

CREATE FUNCTION (外部表)

このステートメントは、 ユーザー定義の外部表関数をアプリケーション・サーバーに登録する場合に使用されます。

表関数 は、SELECT の FROM 文節で使用することができ、 行を一度に 1 行戻すことによって、SELECT に表を戻します。

呼び出し

このステートメントは、アプリケーション・プログラムに組み込むか、 または動的 SQL ステートメントを使用して発行することができます。 このステートメントは、動的に準備可能な実行可能ステートメントです。 しかし、バインド・オプション DYNAMICRULES BIND を適用する場合、 ステートメントを動的に準備することはできません (SQLSTATE 42509)。

許可

このステートメントの許可 ID には、以下の特権が少なくとも 1 つ含まれている必要があります。

非分離の関数を作成するには、ステートメントの許可 ID の特権に 以下の特権の少なくとも 1 つが含まれている必要があります。

分離関数を作成する場合には、さらに別の権限や特権は必要ありません。

許可 ID の権限が不十分で、操作を実行できない場合には、 エラー (SQLSTATE 42502) になります。

構文

>>-CREATE FUNCTION--function-name------------------------------->
 
>----(--+--------------------------------------------------------+---)->
        |  .-,------------------------------------------------.  |
        |  V                                                  |  |
        '----+----------------+--data-type1--+-------------+--+--'
             '-parameter-name-'              '-AS LOCATOR--'
 
>----*---------------------------------------------------------->
 
                       .-,------------------------------------------.
                       V                                            |
>----RETURNS TABLE--(-----column-name--data-type2--+-------------+--+---)->
                                                   '-AS LOCATOR--'
 
>----*----+--------------------------+--*----------------------->
          '-SPECIFIC--specific-name--'
 
>----EXTERNAL--+-----------------------+---*-------------------->
               '-NAME--+-'string'---+--'
                       '-identifier-'
 
                         (1)
>----LANGUAGE--+-C----+---------*------------------------------->
               +-JAVA-+
               '-OLE--'
 
>----PARAMETER STYLE--+-DB2SQL-----+---*------------------------>
                      '-DB2GENERAL-'
 
      .-NOT DETERMINISTIC--.       .-FENCED-----.
>-----+--------------------+--*----+------------+--*------------>
      |               (2)  |       '-NOT FENCED-'
      '-DETERMINISTIC------'
 
      .-RETURNS NULL ON NULL INPUT--.
>-----+-----------------------------+--*--NO SQL--*------------->
      |                      (3)    |
      '-CALLED ON NULL INPUT--------'
 
      .-EXTERNAL ACTION----.       .-NO SCRATCHPAD----------.
>-----+--------------------+--*----+------------------------+--->
      '-NO EXTERNAL ACTION-'       |             .-100----. |
                                   '-SCRATCHPAD--+--------+-'
                                                 '-length-'
 
          .-NO FINAL CALL--.
>----*----+----------------+--*---DISALLOW PARALLEL---*--------->
          '-FINAL CALL-----'
 
      .-NO DBINFO--.
>-----+------------+--*----+-----------------------+--*--------->
      '-DBINFO-----'       '-CARDINALITY--integer--'
 
>-----+------------------------------+-------------------------><
      '-TRANSFORM GROUP--group-name--'
 

注:

  1. LANGUAGE OLE DB 外部表関数の作成の詳細は、CREATE FUNCTION (OLE DB 外部表) を参照してください。 LANGUAGE SQL 表関数の作成の詳細は、CREATE FUNCTION (SQL スカラー、表、または行) を参照してください。

  2. DETERMINISTIC の代わりに NOT VARIANT を、 また NOT DETERMINISTIC の代わりに VARIANT を指定することができます。

  3. CALLED ON NULL INPUT の代わりに NULL CALL を、 また RETURNS NULL ON NULL INPUT の代わりに NOT NULL CALL を指定できます。

説明

function-name
定義する関数の名前を指定します。 これは、関数を指定する修飾または非修飾の名前です。 function-name (関数名) の非修飾形式は SQL 識別子です (最大長 18)。 動的 SQL ステートメントでは、CURRENT SCHEMA 特殊レジスターは、 修飾子のないオブジェクト名の修飾子として使用されます。 静的 SQL ステートメントでは、 QUALIFIER プリコンパイル / バインド・オプションにより、 修飾子のないオブジェクト名の修飾子が暗黙指定されます。 修飾形式は、schema-name の後にピリオドと SQL 識別子が続きます。 最初のパラメーターが構造タイプの場合、修飾名は、 最初のパラメーターのデータ・タイプと同じであってはなりません。

暗黙または明示の修飾子を含む名前、 およびパラメーターの数と各パラメーターのデータ・タイプ (データ・タイプの長さ、 精度、または位取りの各属性には関係なく) は、 カタログに記述されている関数を指定するものであってはなりません (SQLSTATE 42723)。 非修飾名とパラメーターの数およびデータ・タイプとの組み合わせは、 そのスキーマ内では当然固有ですが、複数のスキーマ間で固有である必要はありません。

2 つの部分からなる名前を指定する場合、 "SYS" で始まる schema-name (スキーマ名) は使用できません (SQLSTATE 42939)。

述部のキーワードとして使用される多くの名前は、システム使用として予約されており、 function-name として使用することはできません (SQLSTATE 42939)。 それに含まれる名前は、 SOME、 ANY、 ALL、 NOT、 AND、 OR、 BETWEEN、 NULL、 LIKE、 EXISTS、 IN、 UNIQUE、 OVERLAPS、 SIMILAR、 MATCH、 および 基本述部に記載されている比較演算子です。

関数のシグニチャーに何らかの差異があれば、同じ名前を複数の関数に使用することができます。 禁止されてはいませんが、外部ユーザー定義関数の名前として、 組み込み関数と同じ名前を指定すべきではありません。

parameter-name
この関数の他のパラメーターすべての名前と異なる、 パラメーターの任意選択名を指定します。

(data-type1,...)
関数の入力パラメーターの数を指定するとともに、 各パラメーターのデータ・タイプを指定します。 このリストには、 関数が受け取ることを予期している各パラメーターごとに 1 つの項目を指定する必要があります。 パラメーターの数は 90 を超えることはできません。 この限界を超えると、エラー (SQLSTATE 54023) になります。

パラメーターのない関数も登録可能です。 この場合、指定するデータ・タイプがない場合でも、括弧はコーディングする必要があります。 たとえば、

  CREATE FUNCTION WOOFER() ...

その対応するすべてのパラメーターのタイプがまったく同じである場合でも、 1 つのスキーマ中に名前が同じ 2 つの関数があってはなりません。 このタイプの比較では長さ、精度、および位取りは考慮されません。 したがって、CHAR(8) と CHAR(35)、また DECIMAL(11,2) と DECIMAL (4,3) は、 それぞれ同じタイプとみなされます。 さらに、DECIMAL と NUMERIC などのように、 この目的で複数のタイプが同じタイプとして扱われることがあります。 シグニチャーが重複していると、SQL エラー (SQLSTATE 42723) になります。

たとえば、次のステートメントの場合、

  CREATE FUNCTION PART (INT, CHAR(15)) ...
  CREATE FUNCTION PART (INTEGER, CHAR(40)) ...
 
  CREATE FUNCTION ANGLE (DECIMAL(12,2)) ...
  CREATE FUNCTION ANGLE (DEC(10,7)) ...

2 番目と 4 番目のステートメントは、 重複する関数とみなされ、エラーになります。

data-type1
パラメーターのデータ・タイプを指定します。
  • CREATE TABLE ステートメントの data-type 定義に指定が可能で、 関数の作成に使用されている言語において対応するものがある SQL データ・タイプ指定と省略形を指定できます。 ユーザー定義関数に関する SQL データ・タイプとホスト言語データ・タイプの対応については、 アプリケーション開発の手引き の言語別の項を参照してください。
  • DECIMAL (および NUMERIC) は、LANGUAGE C と OLE では無効です (SQLSTATE 42815)。 DECIMAL の使用に代わる手法については、アプリケーション開発の手引き を参照してください。
  • REF(type-name) は、パラメーターのデータ・タイプとして指定できます。 ただし、パラメーターに効力範囲を指定してはなりません (SQLSTATE 42997)。
  • 適切な変形関数が、関連する変形グループに存在する場合には、 構造タイプを指定できます。

AS LOCATOR
LOB タイプまたは LOB タイプに基づく特殊タイプの場合、 AS LOCATOR 文節を追加することができます。 これは、実際の値の代わりに LOB ロケーターを UDF に渡すことを指定します。 これにより、UDF に渡すバイト数を大幅に減らすことができ、 パフォーマンスも向上します (特に、UDF にとって実際に必要になる値が数バイトだけである場合)。 UDF での LOB ロケーターの使用については、アプリケーション開発の手引き で説明されています。

次の例は、パラメーター定義の AS LOCATOR 文節の使用法を示しています。

   CREATE FUNCTION foo ( CLOB(10M) AS LOCATOR, IMAGE AS LOCATOR)
                   ...

ここで、IMAGE は LOB タイプの 1 つに基づく特殊タイプであると想定します。

また、引き数のプロモーション目的には、AS LOCATOR 文節の効果はないことに注意してください。 この例では、タイプはそれぞれ CLOB と IMAGE であると見なされるので、 関数に CHAR 引き数または VARCHAR 引き数が最初の引き数として渡されます。 同様に、関数シグニチャーに対して AS LOCATOR の効果はありません。 関数シグニチャーは、(a) "関数解決" と呼ばれるプロセスによって DML で参照された場合、 (b) COMMENT ON や DROP などの DDL ステートメントで参照された場合に 関数をマッチングする際に使用されます。 実際に、この文節はシグニチャーの指定のない COMMENT ON や DROP で使用しても、 しなくても構いません。

LOB 以外のタイプ、または LOB に基づく特殊タイプに対して AS LOCATOR を指定すると、 エラー (SQLSTATE 42601) が発生します。

関数が FENCED の場合、AS LOCATOR 文節は指定できません (SQLSTATE 42613)。

RETURNS TABLE
関数の出力が表であることを指定します。 このキーワードに続く括弧は、表の列の名前とタイプのリストを区切るもので、 他の指定 (たとえば、制約) のない単純な CREATE TABLE ステートメントの形式と類似しています。 255 列以内が許可されます (SQLSTATE 54011)。

column-name
この列の名前を指定します。 名前を修飾することはできず、表の複数の列に対して同じ名前を使用することはできません。

data-type2
列のデータ・タイプを指定します。特定の言語において、構造タイプ以外であれば、 UDF 作成のパラメーターとしてサポートされるどのようなデータ・タイプでも構いません (SQLSTATE 42997)。

AS LOCATOR
data-type2 が LOB タイプまたは LOB タイプに基づく特殊タイプの場合、 このオプションを使用すると、 関数は結果表でインスタンス化される LOB 値のロケーターを戻します。

この文節で使用できる有効なタイプについては、 *** ページで説明されています。

SPECIFIC specific-name
定義する関数のインスタンスに対する固有名を指定します。 この特定名は、この関数をソース関数として使用する場合、 この関数を除去する場合、またはこの関数にコメントを付ける場合に使用することができます。 これは、関数の呼び出しには使用できません。 specific-name (特定名) の非修飾形式は SQL 識別子です (最大長 18)。 修飾形式は、schema-name の後にピリオドと SQL 識別子が続きます。 暗黙または明示の修飾子も含め、その名前が、 アプリケーション・サーバーに存在する別の関数インスタンスを指定するものであってはなりません。 そうでない場合、エラー (SQLSTATE 42710) になります。

specific-name は、既存の関数名 と同じであっても構いません。

修飾子を指定しない場合、function-name に使用された修飾子が使用されます。 修飾子を指定する場合は、 function-name の明示修飾子または暗黙修飾子と同じでなければなりません。 そうでない場合、エラー (SQLSTATE 42882) になります。

specific-name の指定がない場合、 固有の名前がデータベース・マネージャーによって生成されます。 生成される固有の名前は、 SQL の後に文字のタイム・スタンプが続く名前です (SQLyymmddhhmmssxxx)。

EXTERNAL
この文節は、外部プログラミング言語で作成され、 文書化されたリンケージの規則とインターフェースに準拠している新しい関数を登録するのに、 CREATE FUNCTION ステートメントが使用されていることを示します。

NAME 文節を指定しない場合、"NAME function-name" が想定されます。

NAME 'string'
この文節は、定義する関数を実現するためのユーザー作成コードを指定します。

'string' オプションは、最大 254 文字のストリング定数です。 ストリングに使用される形式は、指定した LANGUAGE によって異なります。

  • LANGUAGE C の場合

    指定する string (ストリング) は、 作成しているユーザー定義関数を実行するためにデータベース・マネージャーが呼び出すライブラリー名と、 そのライブラリー中の関数名です。 ライブラリー (およびそのライブラリー中の関数) は、 CREATE FUNCTION ステートメントの実行時に存在している必要はありません。 ただし、関数が SQL ステートメントで使用される時点では、 そのライブラリーとそのライブラリー内の関数が存在していなければならず、 しかもデータベース・サーバーのマシンからアクセス可能でなければなりません。

    >>-'--+-library_id-------+---+-------------+---'---------------><
          '-absolute_path_id-'   '-!--func_id--'
     
    

    単一引用符内に、余分なブランクを使用することはできません。

    library_id
    関数を含むライブラリー名を指定します。 データベース・マネージャーは、.../sqllib/function ディレクトリー (UNIX 系システム)、 または ...\instance_name\ 関数ディレクトリー (DB2INSTPROF レジストリー変数で指定した OS/2、Windows 32 ビット オペレーティング・システム) のライブラリーを探します。 ここで、データベース・マネージャーの実行に使用される制御 sqllib ディレクトリーは、 データベース・マネージャーが位置指定します。 たとえば、UNIX 系システムの制御 sqllib ディレクトリーは、 /u/$DB2INSTANCE/sqllib です。

    UNIX 系システムの library_id が 'myfunc' で、 データベース・マネージャーが /u/production から実行されている場合、 ライブラリー /u/production/sqllib/function/myfunc から関数を探索します。

    OS/2 および Windows 32 ビット オペレーティング・システム の場合、library_id が関数ディレクトリーにないと、 データベース・マネージャーは LIBPATH または PATH を探します。

    OS/2 では、library_id に 9 文字以上を指定しないようにします。

    absolute_path_id
    関数の全パス名を指定します。

    たとえば、UNIX 系システムで '/u/jchui/mylib/myfunc' を指定すると、 データベース・マネージャーは /u/jchui/mylib の中から myfunc 関数を探します。

    OS/2 および Windows 32 ビット オペレーティング・システム の場合、 'd:\mylib\myfunc' を指定すると、 データベース・マネージャーは d:\mylib ディレクトリーから myfunc.dll ファイルをロードします。

    OS/2 では、この指定の最後の部分 (すなわち dll の名前) は、9 文字以上にしないでください。

    ! func_id
    呼び出される関数の入り口点名を指定します。 ! は、ライブラリー ID と関数 ID との間の区切り文字です。 ! func_id を省略すると、 データベース・マネージャーはライブラリーのリンク時に確立されたデフォルトの入り口点を使用します。

    たとえば、UNIX 系システムで 'mymod!func8' と指定すると、 データベース・マネージャーはライブラリー $inst_home_dir/sqllib/function/mymod を調べて、 そのライブラリー内の入り口点 func8 を使用します。

    OS/2、および Windows 32 ビット オペレーティング・システム の場合 'mymod!func8' を指定すると、 データベース・マネージャーは mymod.dll ファイルをロードして、 そのダイナミック・リンク・ライブラリー (DLL) の func8() 関数を呼び出します。

    ストリングの形式が正しくない場合には、エラー (SQLSTATE 42878) になります。

    いずれの場合も、すべての外部関数の本体は、 データベースのすべての区分で使用可能なディレクトリーにある必要があります。

  • LANGUAGE JAVA の場合

    指定する string には、 作成中のユーザー定義関数を実行するためにデータベース・マネージャーが呼び出す、 任意指定の jar ファイル、クラス識別子、およびメソッド識別子が含まれています。 クラス識別子とメソッド識別子は、 CREATE FUNCTION ステートメントの実行時には存在している必要はありません。 jar_id を指定する場合、識別子は、 CREATE FUNCTION ステートメントの実行時に存在していなければなりません。 ただし、関数を SQL ステートメントで使用する時点で、 メソッド識別子は存在しなければならず、 データベース・サーバーのマシンからアクセス可能でなければなりません。

    >>-'----+------------+--class_id---+-.-+--method_id--'---------><
            '-jar_name :-'             '-!-'
     
    

    単一引用符内に、余分なブランクを使用することはできません。

    jar_name
    jar の集合をデータベースへインストールしたときに、 その jar の集合に付けられた jar 識別子を指定します。 これは、単純識別子またはスキーマ修飾識別子のいずれかにすることができます。 たとえば、'myJar' や 'mySchema.myJar' のようになります。

    class_id
    Java オブジェクトのクラス識別子を指定します。 クラスがパッケージの一部である場合、クラス識別子の部分に 完全なパッケージ接頭部 (例: 'myPacks.UserFuncs') が含まれている必要があります。 Java 仮想マシンは、ディレクトリー '.../myPacks/UserFuncs/' の中のクラスを探します。 OS/2 および Windows 32 ビット オペレーティング・システム では、 Java 仮想マシンはディレクトリー '...\myPacks\UserFuncs\' を探索します。

    method_id
    呼び出す Java オブジェクトのメソッド名を指定します。
  • LANGUAGE OLE の場合

    指定する string は、 作成中のユーザー定義関数を実行するためにデータベース・マネージャーが呼び出す、 OLE のプログラム識別子 (progid) またはクラス識別子 (clsid)、およびメソッド識別子です。 プログラム識別子またはクラス識別子、およびメソッド識別子は、 CREATE FUNCTION ステートメントの実行時に存在している必要はありません。 ただし、関数を SQL ステートメントで使用する時点で、 メソッド識別子は存在していなければならず、 データベース・サーバーのマシンからアクセス可能でなければなりません。 そうでない場合、エラー (SQLSTATE 42724) になります。

    >>-'--+-progid-+---!--method_id--'-----------------------------><
          '-clsid--'
     
    

    単一引用符内に、余分なブランクを使用することはできません。

    progid
    OLE オブジェクトのプログラム識別子を指定します。

    progid は、データベース・マネージャーには解釈されず、 実行時に OLE API に転送されるだけです。 指定する OLE オブジェクトは、作成可能である必要があり、 実行時バインディング (ディスパッチに基づくバインディングとも呼ばれる) を サポートしている必要があります。

    clsid
    作成する OLE オブジェクトのクラス識別子を指定します。 OLE オブジェクトが progid を指定して登録されていない場合に、 progid を指定する代わりに使用することができます。 clsid の形式は次のとおりです。

    {nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}

    ここで 'n' は英数字です。 clsid は、データベース・マネージャーには解釈されず、 実行時に OLE API に転送されるだけです。

    method_id
    呼び出す OLE オブジェクトのメソッド名を指定します。

NAME identifier
この文節は、定義している関数を実装するユーザー作成コードの名前を指定します。 指定する identifier は SQL 識別子です。 SQL 識別子は、ストリングの library-id として使用されます。 区切られた識別子でない場合、識別子は大文字に変換されます。 識別子がスキーマ名で修飾されている場合、スキーマ名の部分は無視されます。 この形式の NAME は、LANGUAGE C でのみ使用可能です。

LANGUAGE
この文節は必須で、 ユーザー定義関数の本体が準拠している言語インターフェース規則を指定するのに使用します。

C
これは、データベース・マネージャーが、 ユーザー定義関数を C の関数であるかのように呼び出すことを意味します。 ユーザー定義関数は、 標準 ANSI C プロトタイプで定義されている C 言語の 呼び出しおよびリンケージの規則に準拠していなければなりません。

JAVA
データベース・マネージャーは、 Java クラスのメソッドとしてユーザー定義関数を呼び出します。

OLE
データベース・マネージャーは、 OLE 自動化オブジェクトによって公開されたメソッドとして、ユーザー定義関数を呼び出します。 ユーザー定義関数は、OLE Automation Programmer's Reference に説明されている、 OLE 自動化データ・タイプと呼び出しメカニズムに準拠している必要があります。

LANGUAGE OLE は、 DB2 (Windows 32 ビット オペレーティング・システム 版) で保管されたユーザー定義関数に対してのみサポートされます。

LANGUAGE OLE DB 外部表関数の作成の詳細は、CREATE FUNCTION (OLE DB 外部表) を参照してください。

PARAMETER STYLE
この文節は、関数にパラメーターを渡し、 関数から値を戻すのに用いる規則を指定するために使用します。

DB2SQL
C 言語の呼び出しとリンクの規則に準拠する外部関数との間で、 パラメーターを渡し、値を戻すために用いる規則を指定します。 これは、LANGUAGE C または LANGUAGE OLE を使用する場合に指定する必要があります。

DB2GENERAL
Java クラスのメソッドとして定義された外部関数との間で、 パラメーターを渡し、値を戻す場合に用いる規則を指定します。 これは、LANGUAGE JAVA を使用する場合にだけ指定する必要があります。

DB2GENERAL の同義語として値 DB2GENRL が使用可能です。

DETERMINISTIC または NOT DETERMINISTIC
この文節は任意指定で、 特定の引き数の値に対して関数が常に同じ結果を戻すか (DETERMINISTIC)、 それとも状態値に依存して関数の結果が影響を受けるか (NOT DETERMINISTIC) を指定します。 つまり DETERMINISTIC 関数は、 同じ入力を指定して連続して呼び出した場合に常に同じ表を戻します。 NOT DETERMINISTIC を指定すると、 同じ入力によって常に同じ結果が生じる利点に基づく最適化ができなくなります。 NOT DETERMINISTIC 表関数の例として、 ファイルなどのデータ・ソースからデータを検索する関数があります。

FENCED または NOT FENCED
この文節は、関数をデータベース・マネージャーの操作環境の プロセスまたはアドレス空間で実行しても "安全" か (NOT FENCED)、 そうでないか (FENCED) を指定します。

関数が FENCED として登録されると、データベース・マネージャーは、 その内部資源 (データ・バッファーなど) を隔離して、 その関数からアクセスされないようにします。 多くの関数は、FENCED または NOT FENCED のどちらかで実行するように選択することができます。 一般に、FENCED として実行される関数は、 NOT FENCED として実行されるものと同じようには実行されません。
警告:適切にコード化、検討、および検査されていない関数に NOT FENCED を使用すると、 DB2 の保全性に危険を招く場合があります。 DB2 では、発生する可能性のある一般的な不注意による障害の多くに対して、 いくつかの予防措置がとられていますが、 NOT FENCED ユーザー定義関数が使用される場合には、完全な保全性を確保できません。

FENCED を使用すればデータベースの保全性を大幅に確保できるものの、 適切にコード化、検討、および検査して FENCED UDF を使用しなければ、 DB2 に障害が発生することがあります。

ほとんどのユーザー定義関数は、FENCED または NOT FENCED のどちらでも実行できるはずです。 LANGUAGE OLE を指定した関数には、FENCED のみを指定できます (SQLSTATE 42613)。

FENCED から NOT FENCED に変更するには、 関数を削除して再作成し、関数を再登録する必要があります。 ユーザー定義関数を NOT FENCED として登録するには、SYSADM 権限、DBADM 権限、 または特殊権限 (CREATE_NOT_FENCED) が必要です。

関数が FENCED の場合、AS LOCATOR 文節は指定できません (SQLSTATE 42613)。

RETURNS NULL ON NULL INPUT または CALLED ON NULL INPUT
このオプション文節を使用すると、引き数のいずれかがヌル値の場合に、 外部関数を呼び出さないようにすることができます。 パラメーターがないものとしてユーザー定義関数を定義すると、 このヌル引き数条件が引き起こされることはなく、 この仕様のコーディング方法はそれほど重要ではなくなります。

RETURNS NULL ON NULL INPUT が指定されており、 表関数 OPEN が実行されるときに、関数の引き数のいずれかがヌル値の場合、 ユーザー定義関数は呼び出されません。 試行した表関数スキャンの結果は、空の表になります (行のない表)。

CALLED ON NULL INPUT が指定されると、 引き数がヌル値か否かに関係なくユーザー定義関数が呼び出されます。 これは、ヌル値を戻す場合も、通常の (ヌル値以外の) 値を戻す場合もあります。 ただし、ヌルの引き数値の有無のテストは UDF が行う必要があります。

値 NULL CALL は、上位互換またはファミリーの互換性のために、 CALLED ON NULL INPUT の同義語として使うことができます。 同様に、NOT NULL CALL は、RETURNS NULL ON NULL INPUT の同義語として使えます。

NO SQL
この文節は必須で、関数が SQL ステートメントを発行してはならないことを指定します。 関数が SQL ステートメントを発行すると、実行時にエラー (SQLSTATE 38502) になります。

NO EXTERNAL ACTION または EXTERNAL ACTION
この文節は任意指定であり、関数が、 データベース・マネージャーによって管理されていないオブジェクトの状態を変更する処置を行うか否かを指定します。 EXTERNAL ACTION を指定すると、 関数に外部の影響がないことを前提とした最適化ができなくなります。 (たとえば、メッセージの送信、警報音による通知、ファイルへのレコードの書き込みなど。)

NO SCRATCHPAD または SCRATCHPAD length
この文節は任意選択であり、 この外部関数に対してスクラッチパッドを用意するか否かを指定するのに使用することができます。 (ユーザー定義関数を再入可能にすることを強くお勧めします。再入可能にすると、 スクラッチパッドによってある呼び出しと次の呼び出しとの間に 関数が "状態を保管する" 手段が用意されます。)

SCRATCHPAD を指定すると、ユーザー定義関数の最初の呼び出し時に、 その外部関数によって使用されるスクラッチパッドにメモリーが割り振られます。 このスクラッチパッドには、次の特性があります。

SCRATCHPAD を指定すると、ユーザー定義関数を呼び出すたびに、 スクラッチパッドをアドレス指定する外部関数に追加の引き数が渡されます。

NO SCRATCHPAD を指定すると、 外部関数に対してスクラッチパッドは割り振られず、渡されません。

NO FINAL CALL または FINAL CALL
この文節は任意選択であり、 外部関数に対する最終呼び出し (および別個の最初の呼び出し) が行われるか否かを指定します。 この文節は、スクラッチパッドが再初期化される時期も制御します。 NO FINAL CALL が指定されている場合は、DB2 はオープン、 取り出しおよびクローズの 3 つのタイプの呼び出ししか行うことができません。 しかし、FINAL CALL が指定されている場合は、 オープン、取り出しおよびクローズに加えて、 表関数に対して最初の呼び出しと最終呼び出しを行うことができます。

外部表関数の場合、どのオプションが選択されたかにかかわらず、 呼び出しタイプ引き数は常に存在します。 この引き数とその値の詳細については、アプリケーション開発の手引き を参照してください。

エラー発生時の、これらの呼び出しの表 UDF 処理については、 アプリケーション開発の手引き に説明があります。

DISALLOW PARALLEL
この文節は、関数への単一の参照に対して、 関数の呼び出しを並列化できないことを指定します。 表関数は常に 1 つの区分で実行されます。

NO DBINFO または DBINFO
この文節は任意選択で、 DB2 において既知である特定の情報を追加の呼び出し時引き数として UDF に渡すか (DBINFO)、 または渡さないか (NO DBINFO) を指定します。 NO DBINFO がデフォルト値です。 DBINFO は、LANGUAGE OLE ではサポートされません (SQLSTATE 42613)。

DBINFO を指定すると、以下の情報を含む構造が UDF に渡されます。

構造の詳細、および構造が UDF にどのようにして渡されるかについては、 アプリケーション開発の手引き を参照してください。

CARDINALITY integer
この文節はオプションで、 関数によって戻されると予想される行の数の見積もりを最適化のために指定します。 integer の値の有効範囲は、 0 〜 2 147 483 647 (両端の値を含む) です。

表関数に対して CARDINALITY 文節の指定がない場合、 DB2 はデフォルト値として有限の値を想定します (RUNSTATS ユーティリティーが 統計を収集していない表に対して想定される値と同じ)。

警告: 関数が事実上無限のカーディナリティーを持っている場合 (すなわち、 呼び出されるといつでも行を戻し、"end-of-table" 条件を戻さない)、 正しく機能するために "end-of-table" 条件を必要とする照会は無限に実行されるので、 照会を中断させる必要があります。 このような照会の例として、GROUP BY および ORDER BY を使用する照会があります。 このような UDF は書かないことをお勧めします。

TRANSFORM GROUP group-name
関数を呼び出す際のユーザー定義の構造タイプのトランスフォーメーションに使用する変形グループを指定します。 関数定義にパラメーター・データ・タイプとしてユーザー定義の構造タイプが含まれている場合、 変形が必要になります。 この節が指定されない場合には、デフォルトのグループ名 DB2_FUNCTION が使用されます。 指定した (またはデフォルトの) group-name が、 参照された構造タイプに定義されていない場合、エラーになります (SQLSTATE 42741)。 指定した group-name または構造タイプに必須の FROM SQL 変換関数が定義されていない場合には、 エラーになります (SQLSTATE 42744)。

例 1: 以下の例では、 テキスト管理システムにおいて既知の各文書の 1 つの文書識別列からなる行を戻す表関数を登録しています。 最初のパラメーターは指定された対象領域をマッチングし、 2 番目パラメーターには指定された文字列が入ります。

単一セッションのコンテキスト内では UDF は常に同じ表を戻すため、 UDF は DETERMINISTIC として定義されています。 DOCMATCH からの出力を定義する RETURNS 文節に注意してください。 それぞれの表関数に対して、FINAL CALL を指定する必要があります。 さらに、この表関数は並列して実行できないので、 DISALLOW PARALLEL キーワードが追加されています。 DOCMATCH の出力のサイズは大きく変動しますが、 DB2 最適化プログラムにとって有用な CARDINALITY 20 が 代表値として指定されています。

CREATE FUNCTION DOCMATCH (VARCHAR(30), VARCHAR(255))
    RETURNS TABLE (DOC_ID CHAR(16))
    EXTERNAL NAME '/common/docfuncs/rajiv/udfmatch'
          LANGUAGE C
          PARAMETER STYLE DB2SQL
          NO SQL
          DETERMINISTIC
          NO EXTERNAL ACTION
          NOT FENCED
    SCRATCHPAD
    FINAL CALL
    DISALLOW PARALLEL
    CARDINALITY 20

例 2: 以下の例では、 Microsoft Exchange のメッセージのメッセージ・ヘッダー情報と、 部分的なメッセージ・テキストの検索に使用する OLE 表関数を登録しています。 この表関数を実装するコードの例については、アプリケーション開発の手引き を参照してください。

CREATE FUNCTION MAIL()
    RETURNS TABLE (TIMERECIEVED DATE,
                   SUBJECT VARCHAR(15),
                   SIZE INTEGER,
                   TEXT VARCHAR(30))
    EXTERNAL NAME 'tfmail.header!list'
    LANGUAGE OLE
    PARAMETER STYLE DB2SQL
    NOT DETERMINISTIC
    FENCED
    CALLED ON NULL INPUT 
    SCRATCHPAD
    FINAL CALL
    NO SQL
    EXTERNAL ACTION
    DISALLOW PARALLEL


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]