SQL 解説書

CREATE FUNCTION (外部スカラー)

このステートメントは、 ユーザー定義の外部スカラー関数をアプリケーション・サーバーに登録する場合に使用されます。 スカラー関数 は、呼び出されるたびに 1 つの値を戻し、 SQL 式が使用可能な個所であれば一般に使用することができます。

呼び出し

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

許可

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

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

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

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

構文

>>-CREATE FUNCTION--function-name------------------------------->
 
>----(--+----------------------------------------------------------+---)->
        |  .-,--------------------------------------------------.  |
        |  V                                                    |  |
        '----+-----------------+---data-type1--+-------------+--+--'
             '-parameter-name--'               '-AS LOCATOR--'
 
>----*---------------------------------------------------------->
 
>----RETURNS--+-data-type2--+-------------+------------------------+>
              |             '-AS LOCATOR--'                        |
              '-data-type3--CAST FROM--data-type4--+-------------+-'
                                                   '-AS LOCATOR--'
 
>----*----+--------------------------+--*----------------------->
          '-SPECIFIC--specific-name--'
 
>-----EXTERNAL--+----------------------+---*-------------------->
                '-NAME--+-'string'---+-'
                        '-identifier-'
 
                         (1)
>----LANGUAGE--+-C----+---------*------------------------------->
               +-JAVA-+
               '-OLE--'
 
>----PARAMETER STYLE--+-DB2SQL-----+--*------------------------->
                      +-DB2GENERAL-+
                      '-JAVA-------'
 
      .-NOT DETERMINISTIC--.       .-FENCED-----.
>-----+--------------------+--*----+------------+--------------->
      |               (2)  |       '-NOT FENCED-'
      '-DETERMINISTIC------'
 
      .-RETURNS NULL ON NULL INPUT--.  (3)
>-----+-----------------------------+---------*---NO SQL--*----->
      '-CALLED ON NULL INPUT--------'
 
      .-EXTERNAL ACTION----.       .-NO SCRATCHPAD----------.
>-----+--------------------+--*----+------------------------+--->
      '-NO EXTERNAL ACTION-'       |             .-100----. |
                                   '-SCRATCHPAD--+--------+-'
                                                 '-length-'
 
          .-NO FINAL CALL--.       .-ALLOW PARALLEL----.
>----*----+----------------+--*----+-------------------+--*----->
          '-FINAL CALL-----'       '-DISALLOW PARALLEL-'
 
      .-NO DBINFO--.
>-----+------------+--*----+------------------------------+--*-->
      '-DBINFO-----'       '-TRANSFORM GROUP--group-name--'
 
>-----+-------------------------------------------------+------><
      '-PREDICATES--(--| predicate-specification |--)---'
 
predicate-specification
 
|---WHEN--+- =  -+---+-constant------------------------+-------->
          +- <> -+   '-EXPRESSION AS--expression-name--'
          +- <  -+
          +- >  -+
          +- <= -+
          '- >= -'
 
>-----+-| data-filter |--+-------------------------+-+----------|
      |                  '-| index-exploitation |--' |
      '-| index-exploitation |--+------------------+-'
                                '-| data-filter |--'
 
data-filter
 
|---FILTER USING--+-function-invocation-+-----------------------|
                  '-case-expression-----'
 
index-exploitation
 
|---SEARCH BY--+--------+---INDEX EXTENSION--index-extension-name-->
               '-EXACT--'
 
     .--------------------------.
     V                          |
>-------| exploitation-rule |---+-------------------------------|
 
exploitation-rule
 
|---WHEN KEY--(--parameter-name1--)----------------------------->
 
                                 .-,------------------.
                                 V                    |
>----USE--search-method-name--(-----parameter-name2---+---)-----|
 

注:

  1. 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 として使用することはできません。 それに含まれる名前は、 SOME、 ANY、 ALL、 NOT、 AND、 OR、 BETWEEN、 NULL、 LIKE、 EXISTS、 IN、 UNIQUE、 OVERLAPS、 SIMILAR、 MATCH、 および 基本述部に記載されている比較演算子です。 この規則に違反すると、エラーになります (SQLSTATE 42939)。

一般に、関数のシグニチャーに何らかの差異がある場合には、 同じ名前を複数の関数に使用することができます。

禁止されてはいませんが、意図的に指定変更を行う場合を除き、 外部ユーザー定義関数の名前として、組み込み関数と同じ名前を指定するのは避けるべきです。 異なる意味を持つ関数に組み込みのスカラー関数または列関数と同じ名前 (たとえば、 LENGTH、VALUE、MAX など) を与えることは、たとえその引き数が一致していたとしても、 動的 SQL ステートメントの過程で、 あるいは静的 SQL アプリケーションの再バインド時に問題が生じます。 すなわち、アプリケーションが失敗することがあり、また、さらに悪いケースとして、 外見上は正常に実行されていても、結果が異なる場合があります。

parameter-name
後続の関数定義で使用できるパラメーターを指定します。 パラメーター名は、 述部指定の index-exploitation 文節にある関数のパラメーターを参照するのに必要です。

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

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
これは必須の文節であり、関数の出力を指定します。

data-type2
出力のデータ・タイプを指定します。

この場合、上記の関数パラメーター data-type1 で説明した 外部関数のパラメーターと同じ考慮事項が適用されます。

AS LOCATOR
LOB タイプまたは LOB タイプに基づく特殊タイプの場合、 AS LOCATOR 文節を追加することができます。 これは、実際の値の代わりに LOB ロケーターが UDF から渡されることを示します。

data-type3 CAST FROM data-type4
出力のデータ・タイプを指定します。

この形式の RETURNS 文節は、 関数コードから戻されたデータ・タイプとは異なるデータ・タイプを、 呼び出しステートメントに戻すのに使用されます。 たとえば、次の例で、

   CREATE FUNCTION GET_HIRE_DATE(CHAR(6))
           RETURNS DATE CAST FROM CHAR(10)
                   ...

CHAR(10) の値が関数コードからデータベース・マネージャーに戻され、 データベース・マネージャーは、その値を DATE に変換して、 変換された値を呼び出し側ステートメントに渡します。 data-type4 は、 data-type3 パラメーターにキャスト可能でなければなりません。 キャスト可能でない場合、 エラー (SQLSTATE 42880) になります (キャスト可能の定義については、 データ・タイプ間のキャストを参照してください)。

data-type3 の長さ、精度または位取りは、 data-type4 から推断することができるので、 data-type3 に指定されるパラメーター化タイプの長さ、精度、 または位取りを指定する必要はありません (指定は可能です)。 代わりに、空の括弧を使用できます (たとえば、VARCHAR() など)。 パラメーター値が異なるデータ・タイプ (REAL または DOUBLE) を示しているため、 FLOAT() を使用することはできません (SQLSTATE 42601)。

特殊タイプおよび構造タイプは、 data-type4 に指定するタイプとしては無効です (SQLSTATE 42815)。

キャスト操作は、変換エラーになる可能性がある実行時検査の対象にもなります。

AS LOCATOR
data-type4 の指定が、 LOB タイプまたは LOB タイプに基づく特殊タイプの場合、 AS LOCATOR 文節を追加することができます。 これは、実際の値の代わりに LOB ロケーターが UDF から戻されることを示します。 UDF での 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 ステートメントで使用される時点では、 そのライブラリーとそのライブラリー中の該当の関数は存在していなければならず、 データベース・サーバーのマシンからアクセス可能でなければなりません。 そうでない場合、エラー (SQLSTATE 42724) になります。

    >>-'--+-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 ステートメントで使用する時点で、 メソッド識別子は存在していなければならず、 データベース・サーバーのマシンからアクセス可能でなければなりません。 そうでない場合、エラー (SQLSTATE 42724) になります。

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

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

    jar_id
    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 ビット オペレーティング・システム 版) で保管されたユーザー定義関数に対してのみサポートされます。

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

DB2SQL
C 言語の呼び出しとリンクの規則、 または OLE 自動化オブジェクトによって公開されたメソッドに準拠する規則を、 この外部関数との間でパラメーターを渡し、値を戻す場合の規則として指定します。 これは、LANGUAGE C または LANGUAGE OLE を使用する場合に指定する必要があります。

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

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

JAVA
関数は、Java 言語および SQLJ ルーチンの仕様に準拠する、 パラメーターの受け渡し規則を使用します。 これは、LANGUAGE JAVA が使用され、 パラメーターまたは戻りタイプに構造タイプがない場合にのみ指定できます (SQLSTATE 429B8)。 PARAMETER STYLE JAVA 関数は、 FINAL CALL、SCRATCHPAD または DBINFO 文節をサポートしていません。

パラメーターの受け渡しの詳細については、アプリケーション開発の手引き を参照してください。

DETERMINISTIC または NOT DETERMINISTIC
この文節は任意指定で、 特定の引き数の値に対して関数が常に同じ結果を戻すか (DETERMINISTIC)、 それとも状態値に依存して関数の結果が影響を受けるか (NOT DETERMINISTIC) を指定します。 つまり DETERMINISTIC を伴う関数は、 同じ入力を指定して連続して呼び出した場合に常に同じ結果を戻します。 NOT DETERMINISTIC を指定すると、 同じ入力によって常に同じ結果が生じる利点に基づく最適化ができなくなります。 乱数を生成する関数は、NOT DETERMINISTIC 関数の例です。 入力の平方根を求める関数は、DETERMINISTIC 関数の例です。

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

関数が FENCED として登録されると、データベース・マネージャーは、 その内部資源 (データ・バッファーなど) を隔離して、 その関数からアクセスされないようにします。 多くの関数は、FENCED または NOT FENCED のどちらかで実行するように選択することができます。 一般に、FENCED として実行される関数は、 NOT FENCED として実行されるものと同じようには実行されません。

警告:適切にコード化、検討、および検査されていない関数に NOT FENCED を使用すると、 DB2 の保全性に危険を招く場合があります。 DB2 では、発生する可能性のある一般的な不注意による障害の多くに対して、 いくつかの予防措置がとられていますが、 NOT FENCED ユーザー定義関数が使用される場合には、完全な保全性を確保できません。

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

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

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

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

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

RETURNS NULL ON NULL INPUT が指定されており、 実行時に関数の引き数のいずれかがヌル値の場合、 このユーザー定義関数は呼び出されず、結果はヌル値になります。

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

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

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

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

SCRATCHPAD は、PARAMETER STYLE JAVA 関数ではサポートされていません。

NO FINAL CALL または FINAL CALL
この文節は任意選択であり、 外部関数に対する最終呼び出しが行われるか否かを指定します。 このような最終呼び出しの目的は、外部関数が、 獲得したシステム資源すべてを解放できるようにすることです。 外部関数がメモリーなどのシステム資源を獲得し、 それをスクラッチパッドに固定するような状況では、 これを SCRATCHPAD キーワードと共に使用すると便利です。 FINAL CALL を指定した場合、実行時点で以下が行われます。

FINAL CALL は、PARAMETER STYLE JAVA 関数ではサポートされていません。

ALLOW PARALLEL または DISALLOW PARALLEL
この文節は任意選択で、関数への 1 つの参照に対して、 関数の呼び出しを並列化できるか否かを指定します。 一般には、ほとんどのスカラー関数は並列化可能ですが、 並列化できない関数 (1 つのスクラッチパッドのコピーに依存する関数など) もあります。 スカラー関数に対して ALLOW PARALLEL または DISALLOW PARALLEL を指定すると、 DB2 はその指定を受け入れます。 関数にどちらのキーワードが当てはまるかを判別するには、 以下の点について検討する必要があります。

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

構文図は、デフォルト値が ALLOW PARALLEL であることを示しています。 しかし、ステートメントで以下のオプションの少なくとも 1 つが指定されている場合は、 デフォルトは DISALLOW PARALLEL です。

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

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

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

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

変形関数は、FROM SQL および TO SQL の両方とも、 指定された場合も暗黙的に指定されている場合でも、 構造タイプと組み込みタイプ属性との変形を適切に実行する SQL 関数でなければなりません。

PREDICATES
述部でこの関数が使用されるときに実行される、 フィルター処理や索引拡張の活用を定義します。 述部仕様では、検索条件の任意選択の SELECTIVITY 文節を指定できます。 PREDICATES 節が指定された場合、 関数は NO EXTERNAL ACTION を指定した DETERMINISTIC として定義しなければなりません (SQLSTATE 42613)。

WHEN comparison-operator
比較演算子 ("=", "<", ">", ">=", "<=", "<>") を使用した述部での、 関数の特定の使用を導入します。

constant
関数の RETURNS タイプに比較可能なデータ・タイプを使用して、 定数値を指定します (SQLSTATE 42818)。 述部が同じ比較演算子とこの定数でこの関数を使用する場合、 指定されたフィルターおよび索引の活用が最適化プログラムにより考慮されます。

EXPRESSION AS expression-name
式に名前を提供します。 述部が同じ比較演算子と式でこの関数を使用する場合、 指定されたフィルターおよび索引の活用が行われます。 この式には、式名が割り当てられ、検索関数の引き数として使用できるようになっています。 expression-name は、 作成されている関数のいずれかの parameter-name と同じにすることはできません (SQLSTATE 42711)。 式が指定される際に、その式のタイプが識別されます。

FILTER USING
結果表をさらにフィルター操作する際に使用する、 外部関数またはケース式の指定を許可します。

function-invocation
結果表の追加のフィルター操作の実行に使用できるフィルター関数を指定します。 これは定義された関数のバージョンであり (述部で使用)、 ユーザー定義述部で実行される行の数を減らし、行を限定するかどうかを判別します。 索引により生成される結果が、ユーザー定義述部に期待される結果に近い場合には、 フィルター関数を適用する効果はあまりありません。 これを指定しない場合は、データのフィルター操作は実行されません。

この関数は、任意の parameter-nameexpression-name、 または定数を引き数として使用でき (SQLSTATE 42703)、整数を戻します (SQLSTATE 428E4)。 戻り値 1 の場合は行が保持され、その他の場合は破棄されます。

この関数は、以下の要件を満たしていなければなりません。

  • LANGUAGE SQL で定義されていなければなりません (SQLSTATE 429B4)。
  • NOT DETERMINISTIC または EXTERNAL ACTION で定義していてはなりません (SQLSTATE 42845)。
  • 任意のパラメーターのデータ・タイプとして構造化データ・タイプがあってはなりません (SQLSTATE 428E3)。
  • 副照会が含まれていてはなりません (SQLSTATE 428E4)。

引き数が他の関数またはメソッドを呼び出す場合、 このネストされた関数またはメソッドにもこれらの 4 つの規則が課されます。 ただし、引き数が組み込みデータ・タイプに評価されるかぎり、 システム生成の observer メソッドをフィルター関数 (または、 引き数として使用される任意の関数またはメソッド) への引き数として使用することができます。

case-expression
結果表をさらにフィルター操作するためのケース式を指定します。 searched-when-clause および simple-when-clause では、 parameter-nameexpression-name、または定数を使用できます (SQLSTATE 42703)。 FILTER USING function-invocation に指定された規則を使って、 外部関数を結果式として使用することができます。 case-expression で参照される関数またはメソッドはすべて、 function-invocation にリストされている 4 つの規則に適合することも必要です。

副照会は、case-expression の中では使用できません (SQLSTATE 428E4)。

ケース式は整数を戻さなければなりません (SQLSTATE 428E4)。 結果式で戻り値が 1 の場合は行が保持され、その他の場合は破棄されます。

index-exploitation
索引を活用するために使用する索引拡張の検索メソッドによって、規則のセットを定義します。

SEARCH BY INDEX EXTENSION index-extension-name
索引拡張を指定します。 index-extension-name は、既存の索引拡張を指定しなければなりません。

EXACT
述部評価の見地から索引検索が厳密であることを指定します。 索引検索後、オリジナルのユーザー定義の述部関数も、 フィルターも適用する必要がないことを DB2 に指示するのに EXACT を使用します。 EXACT 述部は、索引検索が述部と同じ結果を戻す場合に便利です。

EXACT が指定されない場合には、索引検索後、オリジナルのユーザー定義述部が適用されます。 索引が類似した述部を提供するのにとどまると思われる場合には、 EXACT オプションは指定しないでください。

索引検索が使用されない場合には、フィルター関数とオリジナルの述部を適用する必要があります。

exploitation-rule
検索ターゲットおよび検索引き数を記述し、 さらにこれらを使用して索引拡張で定義した検索メソッドを介して索引検索を実行する方法を記述します。

WHEN KEY (parameter-name1)
検索ターゲットを定義します。 1 つのキーにつき 1 つしか、探索ターゲットを指定できません。 parameter-name1 値は、 定義された関数のパラメーター名を指定します (SQLSTATE 42703 または 428E8)。

データ・タイプ parameter-name1 は、 索引拡張で指定したソース・キーのデータ・タイプに適合しなければなりません (SQLSTATE 428EY)。 この適合は、組み込みおよび特殊データ・タイプで厳密に一致しなければならず、 構造タイプの同じタイプ階層内でなければなりません。

指定されたパラメーターの値が、 指定された索引拡張に基づく索引により網羅される列である場合、この文節は真となります。

USE search-method-name(parameter-name2,...)
検索引き数を定義します。 索引拡張で定義されている検索メソッドから、使用する検索メソッドを指定します。 search-method-name は、索引拡張で定義される検索メソッドと適合しなければなりません (SQLSTATE 42743)。 parameter-name2 値は、定義された関数のパラメーター名、 または EXPRESSION AS 文節の expression-name を指定します (SQLSTATE 42703)。 これは、検索ターゲットに指定したパラメーター名と異なっていなければなりません (SQLSTATE 428E9)。 パラメーターの数と各 parameter-name2 のデータ・タイプは、 索引拡張の検索メソッドに定義されるパラメーターに適合しなければなりません (SQLSTATE 42816)。 この適合は、組み込みおよび特殊データ・タイプで厳密に一致しなければならず、 構造タイプの同じタイプ階層内でなければなりません。

例 1: Pellow は、自身の PELLOW スキーマに CENTRE 関数を登録します。 デフォルト値のあるキーワードはデフォルト値を使い、 関数特定名はシステムに生成させることにします。

  CREATE FUNCTION CENTRE (INT,FLOAT)
      RETURNS FLOAT
      EXTERNAL NAME 'mod!middle'
      LANGUAGE C
      PARAMETER STYLE DB2SQL
      DETERMINISTIC
      NO SQL
      NO EXTERNAL ACTION

例 2: ここで、McBride (DBADM 権限を持つ) が PELLOW スキーマに別の CENTRE 関数を登録し、 関数にデータ定義言語でその後使用するための明示的な特定名を付け、 すべてのキーワード値を明示的に指定します。 また、この関数はスクラッチパッドを使用し、 おそらく後続の結果に影響するデータをスクラッチパッドに蓄積します。 DISALLOW PARALLEL が指定されているので、関数への参照は並列化されず、 したがって 1 つのスクラッチパッドを使用して一度限りの初期化と結果の保管が行われます。

  CREATE FUNCTION PELLOW.CENTRE (FLOAT, FLOAT, FLOAT)
      RETURNS DECIMAL(8,4) CAST FROM FLOAT
      SPECIFIC FOCUS92
      EXTERNAL NAME 'effects!focalpt'
      LANGUAGE C    PARAMETER STYLE DB2SQL
      DETERMINISTIC   FENCED   NOT NULL CALL   NO SQL   NO EXTERNAL ACTION
      SCRATCHPAD   NO FINAL CALL 
      DISALLOW PARALLEL

例 3: 次の例は、以下の式を計算する C 言語のユーザー定義関数です。

    output = 2 * input - 4

入力がヌル値の場合には (そしてその場合のみ)、ヌル値を戻します。 これは、CREATE FUNCTION ステートメントで NOT NULL CALL を指定して、 より簡単に (つまりヌル値検査を行わずに) 作成することができます。 ユーザー定義関数プログラムの他の例が、アプリケーション開発の手引き に示されています。 CREATE FUNCTION ステートメントは、次のとおりです。

    CREATE FUNCTION ntest1 (SMALLINT)
       RETURNS SMALLINT
       EXTERNAL NAME 'ntest1!nudft1'
       LANGUAGE C    PARAMETER STYLE DB2SQL
       DETERMINISTIC   NOT FENCED   NULL CALL
       NO SQL   NO EXTERNAL ACTION

プログラム・コードは、次のとおりです。

 
#include "sqlsystm.h"
/* NUDFT1 IS A USER_DEFINED SCALAR FUNCTION */
/* udft1 accepts smallint input
   and produces smallint output
   implementing the rule:
     if (input is null)
        set output = null;
     else
        set output = 2 * input - 4;
*/
void SQL_API_FN nudft1
     (short *input,      /* ptr to input arg */
      short *output,     /* ptr to where result goes */
      short *input_ind,  /* ptr to input indicator var */
      short *output_ind, /* ptr to output indicator var */
      char sqlstate[6],  /* sqlstate, allows for null-term */
      char fname[28],    /* fully qual func name, nul-term */
      char finst[19],    /* func specific name,  null-term */
      char msgtext[71])  /* msg text buffer,     null-term */
{
   /* first test for null input */
   if (*input_ind == -1)
   {
      /* input is null, likewise output */
      *output_ind = -1;
   }
  else
   {
      /* input is not null.  set output to 2*input-4 */
      *output = 2 * (*input) - 4;
      /* and set out null indicator to zero */
      *output_ind = 0;
   }
 
   /* signal successful completion by leaving sqlstate as is */
   /* and exit */
   return;
}
/* end of UDF: NUDFT1 */

例 4: 次の例では、ストリングの中で最初に現れる母音の位置を戻す Java UDF を登録します。 UDF は Java で書かれており、分離して実行されるクラス javaUDFs の findvwl メソッドです。

  CREATE FUNCTION findv ( CLOB(100K) )
       RETURNS INTEGER
       FENCED 
       LANGUAGE JAVA 
       PARAMETER STYLE JAVA 
       EXTERNAL NAME 'javaUDFs.findvwl' 
       NO EXTERNAL ACTION
       CALLED ON NULL INPUT  
       DETERMINISTIC
       NO SQL

例 5: この例では、 タイプ SHAPE の 2 つのパラメーター g1 および g2 を入力として取るユーザー定義述部 WITHIN を概説します。

  
     CREATE FUNCTION within (g1 SHAPE, g2 SHAPE)
          RETURNS INTEGER
          LANGUAGE C
          PARAMETER STYLE DB2SQL
          NOT VARIANT
          NOT FENCED
          NO SQL
          NO EXTERNAL ACTION
          EXTERNAL NAME 'db2sefn!SDESpatilRelations'
          PREDICATES
          WHEN = 1
          FILTER USING mbrOverlap(g1..xmin, g1..ymin, g1..xmax, g1..max, 
                                        g2..xmin, g2..ymin, g2..xmax, g2..ymax)
          SEARCH BY INDEX EXTENSION gridIndex
          WHEN KEY(g1) USE withinExplRule(g2)
          WHEN KEY(g2) USE withinExplRule(g1)

WITHIN 関数の記述は、任意のユーザー定義の関数の記述に類似しているものの、 以下の追加により、この関数がユーザー定義の述部で使用できることを指定します。

例 6: この例では、 タイプ POINT の 2 つのパラメーター P1 および P2 を入力として取るユーザー定義述部 DISTANCE を概説します。

  
     CREATE FUNCTION distance (P1 POINT, P2 POINT)
          RETURNS INTEGER
          LANGUAGE C
          PARAMETER STYLE DB2SQL
          NOT VARIANT
          NOT FENCED
          NO SQL
          NO EXTERNAL ACTION
          EXTERNAL NAME 'db2sefn!SDEDistances'
          PREDICATES
          WHEN > EXPRESSION AS distExpr
          SEARCH BY INDEX EXTENSION gridIndex
          WHEN KEY(P1) USE distanceGrRule(P2, distExpr)
          WHEN KEY(P2) USE distanceGrRule(P1, distExpr)

DISTANCE 関数の記述は、任意のユーザー定義関数の記述に類似しているものの、 以下の追加により、この関数が述部で使用される場合に、 この述部がユーザー定義述部であることを指定します。


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