アプリケーション開発の手引き


DB2 と UDF 間のインターフェース

この項では、DB2 と UDF の間のインターフェースについて特定の詳細情報と、インターフェースを管理できるようにする sqludf.h インクルード・ファイルについて説明します。このインクルード・ファイルは C および C++ で作成された UDF にのみ適用されます。 Java による UDF のコーディングについては、Java UDF のコーディングを参照してください。

DB2 から UDF に渡される引き数

関数への DML 参照で指定される SQL 引き数に加えて、 DB2 は追加の引き数を外部 UDF に渡します。 C と C++ の場合、これらの引き数はすべて 『UDF への引き数の受け渡し』に示されている順序で渡されます。 Java UDF は、 SQL 引き数SQL 結果 引き数の 2 つの引き数のみを取りますが、他の方式を呼び出してそれ以外の情報にアクセスすることもできます。 Java UDF では、以降に説明する結果の SQL 状態 および診断メッセージ の引き数についても、同じ制限が課されます。 Java による UDF のコーディングについては、Java UDF のコーディングを参照してください。

引き数を UDF へ渡す構文
 
                              .--------------.
                              V              |
>>-+----------------------+-----SQL-result---+------------------>
   |  .----------------.  |
   |  V                |  |
   '----SQL-argument---+--'
 
                                     .------------------.
                                     V                  |
>-----+--------------------------+-----SQL-result-ind---+------->
      |  .--------------------.  |
      |  V                    |  |
      '----SQL-argument-ind---+--'
 
>----SQL-state---function-name---specific-name------------------>
 
>----diagnostic-message---+------------+---+-----------+-------->
                          '-scratchpad-'   '-call-type-'
 
>----+--------+------------------------------------------------><
     '-dbinfo-'
 

注:外部関数に渡される上記の各引き数は値へのポインターであり、実際の値ではありません。

以下に各引き数について説明します。

SQL 引き数 (SQL-argument)
この引き数は、UDF を呼び出す前に DB2 により設定されます。この値は n 回繰り返されます。 n は関数参照で指定された引き数の数です。これらの各引き数の値は、関数呼び出しで指定された式から取得されます。その値は、CREATE FUNCTION ステートメント中で該当するパラメーター定義のデータ・タイプで表されます。これらのデータ・タイプが C 言語構成にマップする方法については、 SQL データ・タイプの UDF への受け渡し方法で説明します。

DB2 は、データ・タイプとサーバーのプラットフォームに応じて、 SQL-argument が表すデータの位置を調整します。

SQL 結果 (SQL-result)
この引き数は、DB2 に戻る前に UDF により設定されます。スカラー関数の場合、SQL 結果は 1 つだけあります。表関数の場合、CREATE FUNCTION ステートメントの RETURNS TABLE 文節で定義される関数の各列ごとに、 1 つの SQL 結果があります。それぞれの SQL 結果は、RETURNS TABLE 文節で定義される列の位置に対応します。つまり、最初の SQL 結果引き数は、RETURNS TABLE 文節で定義される最初の列に対応します。 2 番目以降の SQL 結果についても同様です。

スカラー関数と表関数のどちらの場合でも、 DB2 はバッファーを割り振り、そのアドレスを UDF に渡します。 UDF はそれぞれの結果の値をバッファーに入れます。 DB2 は、データ・タイプで示される値を含むのに十分なバッファーを割り振ります。スカラー関数の場合、このデータ・タイプは、CAST FROM 文節があればそこで定義され、 CAST FROM 文節がなければ、RETURNS 文節で定義されます。表関数の場合、データ・タイプは、 RETURNS TABLE(...) 文節で定義されます。これらのデータ・タイプが C 言語構成にどのようにマップされるかについては、 SQL データ・タイプの UDF への受け渡し方法を参照してください。

表関数の場合、DB2 は、定義されているすべての列を DB2 に戻さなくてもよいように、パフォーマンス最適化を定義します。この機能を利用するように UDF を作成する場合、UDF は、表関数を参照しているステートメントが必要とする列のみを戻します。

たとえば、100 個の結果列が定義されている表関数の CREATE FUNCTION ステートメントを考えてみましょう。この関数を参照するステートメントに関係するものが、これらの結果列のうちの 2 つだけであるならば、この最適化により、UDF は各行にこれらの 2 つの列だけを戻し、他の 98 列には時間を費やしません。この最適化の詳細については、後で説明する DB 情報 引き数を参照してください。

戻される各値については (つまり、スカラー関数の場合は単一の値、また一般に、表関数の場合は複数の値について)、UDF コードが、結果のデータ・タイプと長さに必要なバイト数よりも多くのバイトを戻さないようにしてください。 DB2 は、UDF 本体が結果バッファーの上限より数バイト多く書き込んだかどうかを判別しようとし、 SQLCODE -450 (SQLSTATE 39501) を戻します。ただし、DB2 により検出されない、UDF による大幅な上書きは、予期しない結果や異常終了になる可能性があります。

DB2 は、データ・タイプとサーバーのプラットフォームに応じて、 SQL-result が表すデータの位置を調整します。

SQL 引き数標識 (SQL-argument-ind)
この引き数は、UDF を呼び出す前に DB2 により設定されます。 UDF は、この引き数を使用して SQL 引き数 がヌルかどうかを判別します。 n 番目の SQL 引き数標識 は、 n 番目の SQL 引き数標識 (上述) に対応します。この引き数には以下の値のうちの 1 つが入ります。

0
ヌル以外の引き数があります。

-1
ヌルの引き数があります。

関数を NOT NULL CALL で定義すると、UDF 本体はヌル値に対する検査を行う必要がありません。ただし、NULL CALL で定義されると引き数はヌルとなる可能性があるため、 UDF はその検査を行う必要があります。

標識は SMALLINT 値の形式をとります。これは、SQL データ・タイプの UDF への受け渡し方法で説明するように UDF で定義することができます。 DB2 は、データ・タイプとサーバーのプラットフォームに応じて、 SQL-argument-ind が表すデータの位置を調整します。

SQL 結果標識 (SQL-result-ind)
この引き数は、DB2 に戻る前に UDF により設定されます。また、この引き数は各 SQL 結果 引き数について 1 つ存在しています。

UDF は、この引き数を使用して特定の結果値がヌルかどうかを示します。

0 または正の整数
結果はヌル値ではありません。
負の整数
結果はヌル値です。詳細については、負の SQL 結果標識値の解釈を参照してください。

負の SQL 結果標識値の解釈

以下の場合に、DB2 は関数結果をヌル (-2) として扱います。

これは、関数を NOT NULL CALL オプションで定義した場合にも当てはまります。

関数を NOT NULL CALL で定義した場合でも、UDF 本体は結果の標識を設定しなければなりません。たとえば、分母がゼロである場合、除算関数は結果をヌルに設定することができます。

標識は SMALLINT 値の形式をとります。これは、SQL データ・タイプの UDF への受け渡し方法で説明するように UDF で定義することができます。

RESULT 列リストを用いた表関数最適化が UDF により使用されている場合、必要な列に対応する標識のみを設定する必要があります。

DB2 は、データ・タイプとサーバーのプラットフォームに応じて、 SQL-result-ind が表すデータの位置を調整します。

SQL 状態 (SQL-state)
この引き数は、DB2 に戻る前に UDF により設定されます。これは CHAR(5) 値の形式をとります。 UDF では、SQL データ・タイプの UDF への受け渡し方法で説明するように CHAR(5) で引き数を定義し、 UDF がその引き数を使って警告またはエラー条件を知らせることができるようにしてください。この引き数には、関数の呼び出し時に '00000' の値が入ります。 UDF には以下の値を設定できます。

00000
この関数コードは警告状態やエラー状態を検出しません。

01Hxx
この関数コードは警告状態を検出しました。その結果、SQL 警告の SQLCODE +462 (SQLSTATE 01Hxx ) が戻されます。ここで、'xx' は任意のストリングです。

02000
表関数への FETCH 呼び出しの場合にのみ有効です。表にこれ以上行がないことを意味します。

38502
UDF 本体が SQL 呼び出しを行おうとして、エラーの SQLCODE -487 (SQLSTATE 38502) を受け取った場合の特殊な値。 UDF では SQL を使用できないため、これと同じエラーを DB2 を介して戻すようにします。

その他の 38xxx
この関数コードはエラー状態を検出しました。その結果、SQL エラーの SQLCODE -443 (SQLSTATE 38xxx) が戻されます。ここで、'xxx' は任意のストリングです。 380xx 〜 384xx は、 SQL92 国際標準のドラフト拡張用に予約されているため、使用しないでください。また、385xx は、 IBM によって予約されているため、使用しないでください。

その他の値はエラー状態として扱われ、その結果 SQLCODE -463 (SQLSTATE 39001) が発生します。

関数名 (function-name)
この引き数は、UDF を呼び出す前に DB2 により設定されます。これは、DB2 から UDF コードに渡される、修飾された関数名です。この変数は VARCHAR(27) 値の形式をとります。 UDF では、必ず VARCHAR(27) で引き数を定義してください。詳細については、SQL データ・タイプの UDF への受け渡し方法を参照してください。

渡される関数名の形式は以下のとおりです。

     <schema-name>.<function-name>

各部分はピリオドで区切られます。以下に例を 2 つ示します。

 
     PABLO.BLOOP       WILLIE.FINDSTRING

この形式を使うと、複数の外部関数に同じ UDF 本体を使用してもその呼び出し時にはそれらの関数を区別することができます。
注:オブジェクト名およびスキーマ名にはピリオドを付けることができますが、付けない方がよいでしょう。たとえば、関数 rotate がスキーマ obj.op の中にあり、戻される関数名が obj.op.rotate の場合、スキーマ名が obj なのか obj.op なのかがはっきりしません。

特定名 (specific-name)
この引き数は、UDF を呼び出す前に DB2 により設定されます。これは、DB2 から UDF コードに渡される関数の特定の名前です。この変数は VARCHAR(18) 値の形式をとります。 UDF では、必ず VARCHAR(18) で引き数を定義してください。詳細については、SQL データ・タイプの UDF への受け渡し方法を参照してください。以下に例を 2 つ示します。
 
     willie_find_feb99       SQL9904281052440430

この例の最初の値は、ユーザーが CREATE FUNCTION ステートメントで定義します。 2 番目の値は、ユーザーが値を指定しなかった場合に DB2 によって現行タイム・スタンプから生成される値です。

関数名 引き数の場合と同じように、この値を渡すのは、UDF を呼び出している特定の関数を明確に区別するためです。

診断メッセージ (diagnostic-message)
この引き数は、DB2 に戻る前に UDF により設定されます。 UDF は、この引き数を用いて DB2 メッセージにメッセージ・テキストを挿入します。これは VARCHAR(70) 値の形式をとります。 UDF では、必ず VARCHAR(70) で引き数を定義してください。詳細については、SQL データ・タイプの UDF への受け渡し方法を参照してください。

上述した SQL-state 引き数を用いて UDF がエラーまたは警告のいずれかを戻す場合、ここには記述情報を組み込むことができます。 DB2 はこの情報をトークンとしてメッセージ内に組み込みます。

DB2 は、UDF を呼び出す前に最初の文字をヌルに設定します。 DB2 は、戻り時にそのストリングを C の NULL 終了ストリングとして扱います。このストリングは、エラー状態のトークンとして SQLCA 内に組み込まれます。このストリングの少なくとも最初の一部は、 SQLCA または DB2 CLP メッセージに表示されます。ただし、表示される実際の文字数は、その他のトークンの長さにより決まります。これは、DB2 がトークンを切り捨てて、 SQLCA によって指定された合計トークン長の制限に合わせることがあるからです。 X'FF' という文字は、SQLCA のトークンを区切るために使用するので、テキスト内には使用しないでください。

UDF コードは、そのコードに渡される VARCHAR(70) バッファーに入らないほど多くのテキストを戻すべきではありません。 DB2 は、UDF 本体がこのバッファーの上限を超えて定義されたかどうかを、文字 SQLCODE -450 (SQLSTATE 39501) により判別しようとします。ただし、UDF が上書きされると、予測不可能な結果や異常終了を引き起こして DB2 により検出されない場合があります。

DB2 では、UDF から DB2 に戻されるメッセージ・トークンがデータベースと同じコード・ページにあることを前提とします。使用している UDF がこの場合に当てはまるかどうかを確認してください。 7 ビットの不変の ASCII サブセットを使うと、 UDF はメッセージ・トークンを任意のコード・ページに戻します。

スクラッチパッド (scratchpad)
この引き数は、UDF を呼び出す前に DB2 により設定されます。これは、UDF に対する CREATE FUNCTION ステートメントに SCRATCHPAD キーワードを指定した場合にのみ存在します。この引き数は、以下の要素を持ち、任意の LOB データ・タイプの値を渡すために使われる構造とまったく同じ構造です。

スクラッチパッドは、CLOB か BLOB と同じタイプを使って UDF にマップすることができます。これは、渡される引き数が同じ構造であるためです。詳細については、SQL データ・タイプの UDF への受け渡し方法を参照してください。

UDF コードがスクラッチパッド・バッファーの外側で変更を行わないことを確認してください。 DB2 は、UDF 本体がこのバッファーの上限を超えて定義されたかどうかを、文字 SQLCODE -450 (SQLSTATE 39501) により判別しようとしますが、 UDF が大幅に上書きされると予測不可能な結果や異常終了を引き起こし、その結果 DB2 がエラーを出さないこともあります。

スクラッチパッドを使用するスカラー UDF が副照会で参照される場合、 DB2 は副照会の呼び出しの合間にスクラッチパッドをリフレッシュすることに決めることがあります。 UDF で FINAL CALL が指定されている場合、このリフレッシュは、最終呼び出し が行われた後に起こります。

DB2 は、データ・フィールドの位置がどのデータ・タイプの記憶域でも合うよう、スクラッチパッドを初期化します。その結果、スクラッチパッド構造の一部または全体 (長さフィールドを含む) が正しく位置合わせされない場合があります。スクラッチパッドの宣言およびそれへのアクセスに関する詳細については、 32 ビット・プラットフォームおよび 64 ビット・プラットフォームでのスクラッチパッドの作成を参照してください。

呼び出しタイプ (call-type)
この引き数は、もし存在するなら、UDF を呼び出す前に DB2 により設定されます。スカラー関数の場合、この引き数は CREATE FUNCTION ステートメントに FINAL CALL を指定する場合にのみ存在しますが、表関数の場合には常に存在します。これは、スクラッチパッド 引き数の後に指定します。 スクラッチパッド 引き数がないときは 診断メッセージ 引き数の後に指定します。この引き数は INTEGER 値の形式をとります。 UDF の引き数定義が、INTEGER に適していることを確認してください。詳細については、SQL データ・タイプの UDF への受け渡し方法を参照してください。

現在使用可能なすべての値が以下にリストされていますが、 "A ならば AA を実行、さもなければ B ならば BB を実行、さもなければ必ず C なので CC を実行 (if A do AA, else if B do BB, else it must be C so do CC)" といったタイプの論理ではなく、予期されるすべての値を明示的にテストする切り替えまたは CASE ステートメントを UDF に含める必要があります。これは、将来付加的な呼び出しタイプを追加できるようにするため、および明示的に条件 C をテストしない場合には、新しい条件が追加されると問題が発生するからです。

注:

  1. すべての呼び出しタイプで、 UDF が SQL 状態診断メッセージ の戻り値を設定するのが適切な場合もあります。この情報は、それぞれの呼び出しタイプの後に続く記述の中では繰り返されません。すべての呼び出しで、DB2 は、これらの引き数について前に説明したように、指示されたアクションを取ります。

  2. インクルード・ファイル sqludf.h は、UDF で使用するためのものであり、 UDF インクルード・ファイル: sqludf.h で説明されています。記号を含むこのファイルは以下の呼び出しタイプの値を定義し、それらは定数として読み取られます。

スカラー関数の場合、 呼び出しタイプ (call-type) には次のものが含まれます。

-1
これは、このステートメントに対する UDF への FIRST 呼び出しです。スクラッチパッド (存在する場合) は、 UDF が呼び出されるときに 2 進数のゼロに設定されます。すべての引き数値が渡され、UDF は 1 回の初期化処理に必要なことを行います。加えて、スカラー UDF に対する FIRST 呼び出しは、応答を作成して戻すことが期待されているため、NORMAL 呼び出しに似ています。

SCRATCHPAD が指定されていても FINAL CALL が指定されていない場合、 UDF は最初の呼び出しを識別するためにこの呼び出しタイプ引き数を使用しないことに注意してください。その代わり、スクラッチパッドのすべてゼロの状態に依存する必要があります。

0
これは NORMAL 呼び出し です。すべての SQL 入力値が渡され、UDF が結果を作成して戻すことが期待されています。 UDF が SQL 状態 および診断メッセージ 情報を戻す可能性もあります。

1
これは FINAL 呼び出し です。すなわち、 SQL 引き数 の値も SQL 引き数標識 の値も渡されず、これらの値が予測不可能な結果となるかどうかを調べます。スクラッチパッドも渡される場合は、この値は前の呼び出し時のままです。 UDF はこの時点でリソースを解放することになります。

リソースの解放

スカラー UDF は、たとえばメモリーのような、必要なリソースを解放することになります。 SCRATCHPAD も指定され、リソースを追跡するために使用される場合は、 FINAL CALL が UDF に指定されている場合には、FINAL 呼び出しがリソースを解放するのが自然です。 FINAL CALL が指定されていない場合には、獲得されたいずれかのリソースをその同じ呼び出し時に解放する必要があります。

表関数の場合、 呼び出しタイプ (call-type) には次のものがあります。

-2
これは、UDF に対して FINAL CALL キーワードが指定された場合にだけ生じる、 FIRST 呼び出し です。この呼び出しの前に、スクラッチパッドは 2 進ゼロに設定されます。引き数値が表関数に渡され、メモリーの獲得または他の 1 回限りのリソース初期化の実行が選択されます。これは OPEN 呼び出しではなく、この呼び出しの後に OPEN 呼び出しが続くことに注意してください。 FIRST 呼び出し時には、DB2 がデータを無視するため、表関数は DB2 にデータを戻しません。

-1
これは、OPEN 呼び出し です。 NO FINAL CALL が指定される場合には、スクラッチパッドは初期化されますが、指定されない場合には、初期化する必要はありません。すべての SQL 引き数値は、OPEN 時の表関数に渡されます。 OPEN 呼び出し時には、表関数は DB2 にデータを戻しません。

0
これは FETCH 呼び出しで、通常 DB2 では、表関数が戻り値のセットから成る行か、 SQLSTATE 値 '02000' によって指定された表の終わりの条件を戻します。スクラッチパッドが UDF に渡される場合、入力時のスクラッチパッドは前の呼び出しのままです。

1
これは、表関数への CLOSE 呼び出しです。これは、OPEN 呼び出しと同じように、外部 CLOSE 処理 (たとえば、ソース・ファイルのクローズ) と、リソースの解放 (特に NO FINAL CALL ケース) を実行するために使用することができます。

結合や副照会が含まれている場合、 OPEN/FETCH.../CLOSE 呼び出しはステートメントの実行内で繰り返すことができますが、 FIRST 呼び出しと FINAL 呼び出しはそれぞれ 1 回ずつしか実行できません。 FIRST 呼び出しと FINAL 呼び出しが現れるのは、表関数に対して FINAL CALL が指定される場合だけです。

2
これは FINAL 呼び出しで、表関数に対して FINAL CALL が指定された場合にだけ現れます。これは FIRST 呼び出しのように、ステートメントの実行につき 1 回だけ現れます。この呼び出しの目的は、リソースの解放にあります。

リソースの解放

獲得したリソースを解放する UDF を作成します。表関数の場合、CLOSE 呼び出しと FINAL 呼び出しの 2 つで通常この解放を行うことができます。 CLOSE 呼び出しは、OPEN 呼び出しと対になり、ステートメントの実行内で複数回実行することができます。 FINAL 呼び出しが行われるのは、UDF に FINAL CALL が指定される場合だけで、ステートメントにつき 1 回です。

UDF のすべての OPEN/FETCH/CLOSE の組に 1 つのリソースを適用できる場合、 FIRST 呼び出し時にこのリソースを獲得し、FINAL 呼び出し時にそれを解放する UDF を作成します。スクラッチパッドが通常このリソースを追跡します。表関数では、FINAL CALL が指定される場合、スクラッチパッドが初期化されるのは FIRST 呼び出しの前だけです。 FINAL CALL が指定されていない場合には、各 OPEN 呼び出しの前に再初期化されます。

リソースがそれぞれの OPEN/FETCH/CLOSE の組に対して固有である場合には、 CLOSE 呼び出し時にリソースを解放する UDF を作成します。 (表関数が副照会または結合関数中にある場合、 DB2 最適化プログラムがステートメントの実行を編成する方法に応じて、 OPEN/FETCH/CLOSE の組が複数回指定される可能性が高いことに注意してください。)

dbinfo (DB 情報)
この引き数は、UDF を呼び出す前に DB2 により設定されます。これは、UDF に対する CREATE FUNCTION ステートメントに DBINFO キーワードを指定した場合にのみ存在します。この引き数は、ヘッダー・ファイル sqludf.h で定義された sqludf_dbinfo 構造で、このヘッダー・ファイルについては、UDF インクルード・ファイル: sqludf.h で説明しています。この構造内で名前と識別子を含む変数は、 DB2 のこのリリースで指定可能な最長の値より長いことがありますが、将来のリリースと互換性を持つようにこのように定義されています。それぞれの名前および識別子変数を補完する長さ変数を使用して、実際に使用される変数の一部を読み取るか抽出することができます。 dbinfo 構造には以下の要素が含まれます。
  1. データベース名の長さ (dbnamelen)

    次に挙げるデータベース名 の長さ。このフィールドは無符号短整数です。

  2. データベース名 (dbname)

    現在接続されているデータベースの名前。このフィールドは、128 文字の長識別子です。上述のデータベース名の長さ フィールドは、このフィールドの実際の長さを示します。ヌル終了符や埋め込みは含まれません。

  3. アプリケーション許可 ID の長さ (authidlen)

    次に挙げるアプリケーション許可 ID の長さ。このフィールドは無符号短整数です。

  4. アプリケーション許可 ID (authid)

    アプリケーション実行時許可 ID。このフィールドは、128 文字の長識別子です。ヌル終了符や埋め込みは含まれません。上述のアプリケーション許可 ID の長さ フィールドは、このフィールドの実際の長さを示します。

  5. データベース・コード・ページ (codepg)

    2 つの 48 バイト長の構造が合併したもので、1 つは DB2 ユニバーサル・データベースが使用し、もう 1 つは将来の使用のために予約されています。 DB2 ユニバーサル・データベースが使用する構造には、以下のフィールドがあります。

    1. SBCS。 1 バイトのコード・ページで、無符号長整数です。
    2. DBCS。 2 バイトのコード・ページで、無符号長整数です。
    3. COMP。複合コード・ページで、無符号長整数です。
  6. スキーマ名の長さ (tbschemalen)

    次に挙げるスキーマ名 の長さ。表名が渡されない場合は 0 (ゼロ) が入ります。このフィールドは無符号短整数です。

  7. スキーマ名 (tbschema)

    後に挙げる表名 のスキーマ。このフィールドは、128 文字の長識別子です。ヌル終了符や埋め込みは含まれません。上述のスキーマ名の長さ フィールドは、このフィールドの実際の長さを示します。

  8. 表名の長さ (tbnamelen)

    後に挙げる表名 の長さ。表名が渡されない場合は 0 (ゼロ) が入ります。このフィールドは無符号短整数です。

  9. 表名 (tbname)

    更新中または挿入中の表の名前です。このフィールドが設定されるのは、 UDF 参照が UPDATE ステートメントで SET 文節の右側にあるか、 INSERT ステートメントの VALUES リスト内の項目になっている場合だけです。このフィールドは、128 文字の長識別子です。ヌル終了符や埋め込みは含まれません。上述の表名の長さ フィールドは、このフィールドの実際の長さを示します。 スキーマ名 とこのフィールドが合わさって、完全修飾表名になります。

  10. 列名の長さ (colnamelen)

    次に挙げる列名 の長さ。列名が渡されない場合は 0 (ゼロ) が入ります。このフィールドは無符号短整数です。

  11. 列名 (colname)

    表名の場合とまったく同じ条件の下では、このフィールドには更新中または挿入中の列の名前が入ります。それ以外の場合は、予想できません。このフィールドは、128 文字の長識別子です。ヌル終了符や埋め込みは含まれません。上述の列名の長さ フィールドは、このフィールドの実際の長さを示します。

  12. バージョン / リリース番号 (ver_rel)

    8 文字のフィールドで、製品およびそのバージョン、リリース、修正レベルを、 pppvvrrm の書式で識別します。この書式は次のとおりです。

    • ppp は、次のように製品を識別します。
      DSN
      DB2 (MVS/ESA 版) または (OS/390 版)
      ARI
      SQL/DS
      QSQ
      DB2 ユニバーサル・データベース (AS/400 版)
      SQL
      DB2 ユニバーサル・データベース
    • vv は、2 桁のバージョン識別子です。
    • rr は、2 桁のリリース識別子です。
    • m は、1 桁の修正レベル識別子です。
  13. プラットフォーム (platform)

    アプリケーション・サーバーのオペレーティング・プラットフォームは、以下のとおりです。

    SQLUDF_PLATFORM_AIX
    AIX
    SQLUDF_PLATFORM_HP
    HP-UX
    SQLUDF_PLATFORM_MVS
    OS/390
    SQLUDF_PLATFORM_NT
    Windows NT
    SQLUDF_PLATFORM_OS2
    OS/2
    SQLUDF_PLATFORM_SUN
    Solaris 実行環境版
    SQLUDF_PLATFORM_WINDOWS
    Windows 95 および Windows 98
    SQLUDF_PLATFORM_UNKNOWN
    不明なプラットフォーム

    上記のリストに含まれていないその他のプラットフォームについては、 sqludf.h ファイルの内容を参照してください。

  14. 表関数列リストの項目数 (numtfcol)

    後に挙げる表関数列リスト フィールドで指定された表関数列リストにある非ゼロ項目の数。

  15. 予約済みのフィールド (resd1)

    このフィールドは将来の利用のためのものです。 24 文字の長さに定義されています。

  16. 表関数列リスト (tfcolumn)

    これが表関数である場合、このフィールドは、DB2 が動的に割り振った短整数の配列へのポインターです。これがスカラー関数である場合、このポインターはヌルです。

    このフィールドは表関数にのみ使用されます。最初の n 個の項目 (n は、 表関数列リストの項目の数 (number of table function column list) フィールドで指定される)、 numtfcol のみが関係します。 n は 0 のこともありますが、いずれにしても、CREATE FUNCTION ステートメントの RETURNS TABLE(...) 文節内の関数に定義される結果列の数以下になります。これらの値は、このステートメントが表関数から取得する必要のある列の序数に対応します。値が '1' の場合は最初に定義された結果列を表し、 '2' の場合は 2 番目に定義された結果列を表し、 3 番目以降も同様です。値は任意の順序にすることができます。 n はゼロのこともあります。 SELECT COUNT(*) FROM TABLE(TF(...)) AS QQ に類似したステートメント (ただし実際の列値は照会には必要ない) の場合、変数 numtfcol がゼロになることがあるからです。

    この配列は、最適化の機会を表します。 UDF は、表関数のすべての結果列のすべての値を戻す必要はなく、特定の文脈で必要なものだけを戻します。戻されるのは、配列で (番号によって) 識別される列です。この最適化は、パフォーマンスを向上させるために UDF 論理を複雑にする場合があるので、 UDF では、定義されたすべての列を戻すように選択することができます。

  17. 固有のアプリケーション ID (appl_id)

    このフィールドは、ヌル文字で終了する C のストリングを指すポインターで、アプリケーションの DB2 への接続を一意的に識別します。このフィールドは、データベースに接続するたびに再生成されます。

    ストリングの最大長は 32 文字で、その形式は、クライアントと DB2 の間で設定された接続タイプによって決まります。通常は以下のような形式です。

            <x>.<y>.<ts>
    

    ここで、<x> と <y> は接続タイプに応じて変わりますが、 <ts> は YYMMDDHHMMSS という形式の 12 文字のタイム・スタンプで、固有性を確実にするために DB2 によって調整されることがあります。

          Example:  *LOCAL.db2inst.980707130144
    
  18. 予約済みのフィールド (resd2)

    このフィールドは将来の利用のためのものです。 20 文字の長さに定義されています。

UDF 引き数の使用の要約

次に、上記の引き数について要約し、それらを DB2 と外部 UDF 間のインターフェースでどのように使用するのかを説明します。

スカラー関数の場合、引き数は次のとおりです。

表関数は論理的には参照元の SQL ステートメントに表を戻しますが、 DB2 と表関数の間の物理インターフェースは行単位です。表関数の場合、引き数は次のとおりです。

UDF、SQL 結果SQL 結果標識、および SQL 状態 の通常の値出力は、 DB2 から UDF に渡される引き数を使って DB2 に戻されることに注意してください。 UDF は、関数の意味では何も戻さないように定義されています (つまり、関数の戻りタイプは void です)。次の例の void 定義と return ステートメントを参照してください。

 
     #include ...
      void SQL_API_FN divid(
           ... arguments ... )
     { 
           ... UDF body ...
           return;
     }

上記の例で、SQL_API_FN は、サポートされるオペレーティング・システムごとに異なる関数の呼び出し規則を指定するマクロです。このマクロは、ストアード・プロシージャーや UDF を作成する場合に必要です。

UDF のプログラミング例については、UDF コードの例を参照してください。

SQL データ・タイプの UDF への受け渡し方法

この項では、UDF パラメーターと結果の両方に有効なタイプを識別し、対応する引き数を C や C++ 言語の UDF で定義する方法をそれぞれ指定します。 Java UDF の型定義については、Java でサポートされている SQL データ・タイプを参照してください。 sqludf.h インクルード・ファイルとそこで定義されるタイプを使用すると、さまざまなデータ・タイプおよびコンパイラーに当てはまる言語変数および構造を自動的に生成できます。たとえば、BIGINT では、SQLUDF_BIGINT データ・タイプを使用して、異なるコンパイラー間での 64 ビットの整数型の名前の違いを隠すことができます。このインクルード・ファイルについては、UDF インクルード・ファイル: sqludf.h で説明しています。

これは、引き数値の書式を管理する CREATE FUNCTION ステートメントで定義される各関数パラメーターのデータ・タイプです。引き数のデータ・タイプからのプロモーションは、この書式でデータを受け取る必要はありません。 DB2 は、引き数値に対してこのようなプロモーションを自動的に実行します。引き数のプロモーションについては、SQL 解説書 で説明されています。

関数結果の場合、書式を定義する CREATE FUNCTION ステートメントの CAST FROM 文節で指定されるデータ・タイプとなります。 CAST FROM 文節がない場合は、RETURNS 文節で指定されるデータ・タイプが書式を定義します。

以下の例での CAST FROM 文節は、UDF 本体が SMALLINT を戻し、 DB2 がその値を関数参照を行うステートメントに渡す前に INTEGER にキャストすることを意味します。

 
     ... RETURNS INTEGER CAST FROM SMALLINT ...

この場合、UDF は以下に示すように SMALLINT を生成するように定義しなければなりません。 CAST FROM データ・タイプは RETURNS データ・タイプに対してキャスト可能 でなければならないため、任意に他のデータ・タイプを選ぶことはできません。データ・タイプ間のキャストについては、 SQL 解説書 で説明されています。

以下に、SQL タイプとその C 言語での表示を示します。 Java の SQL タイプ表記のリストについては、 Java でサポートされている SQL データ・タイプを参照してください。また、それぞれのタイプがパラメーターや結果として有効かどうかを説明します。さらに、そのタイプを C や C++ 言語の UDF で定義される引き数として表した例も示します。

タイプ udf_locator はヘッダー・ファイル sqludf.h で定義されています。このヘッダー・ファイルについては、UDF インクルード・ファイル: sqludf.h で説明されています。これらのロケーターの使用については、UDF のパラメーターや結果としての LOB ロケーターの使用で説明されています。

32 ビット・プラットフォームおよび 64 ビット・プラットフォームでのスクラッチパッドの作成

UDF を 32 ビット・プラットフォームと 64 ビット・プラットフォームの間で移送できるようにするには、 64 ビット値を含むスクラッチパッドを作成および使用する仕方を変えなければなりません。 1 つまたは複数の 64 ビット値 (64 ビット・ポインターや sqlint64 BIGINT 変数など) を含むスクラッチパッド構造では、明示的な長さ変数を宣言してはなりません。たとえば、以下の例を実行すると、構造宣言の中に明示的な長さ変数が含まれているため、 64 ビット・プラットフォームではデータ位置合わせ例外になる可能性があります。

  struct scratch1
  {
    sqlint32 length;
    char chars[4];
    sqlint64 bigint_var;
  };

上記の例において、32 ビット・プラットフォームと 64 ビット・プラットフォームの間での移送が可能になるようにスクラッチパッド構造を宣言するには、その構造に関連した明示的な長さ変数の宣言を取り除く必要があります。以下の例では、明示的な長さ変数を宣言せずにスクラッチパッド構造を宣言しています。

  struct scratch1
  {
    sqlint64 bigint_var;
    char chars[4];
  };

UDF 内で明示的な長さ変数を宣言していないスクラッチパッド構造にアクセスするには、以下のような形式でスクラッチパッドを参照します。

  struct scratchpad_data * data =
    (struct scratchpad_data*)scratch_pointer->data;

ここで、 scratch_pointer は UDF の sqludf_scratchpad ポインターを、 data はスクラッチパッドの内容を表しています。

UDF インクルード・ファイル: sqludf.h

このインクルード・ファイルには、 UDF を定義する際に役立つ構造、定義、および値が含まれます。このインクルード・ファイルは任意に使用できますが、UDF コードの例で示すサンプル UDF の例ではこのファイルを使用します。 UDF のコンパイル時には、このファイルがあるディレクトリーを参照する必要があります。そのディレクトリーは sqllib/include です。

sqludf.h インクルード・ファイルは自己記述性です。以下にその内容について簡単に要約します。

  1. 受け渡された引き数に対する構造定義。引き数の構造は次のとおりです。
  2. すべての SQL データ・タイプに対する C 言語型定義。 SQL 引き数に対応する UDF 引き数と、SQL データ・タイプを持つ結果を定義するために使用されます。データ・タイプは、SQLUDF_x および SQLUDF_x_FBD という名前で定義されます。この場合の x とは SQL のデータ・タイプ名であり、FBD は For Bit Data を表します。

    また、AS LOCATOR 付加を使用して定義される引き数や結果の C 言語タイプも含まれます。

  3. スクラッチパッド および呼び出しタイプ 引き数に対する C 言語型定義。 呼び出しタイプ 引き数の enum 型定義を使用します。
  4. 標準後書き 引き数を定義するマクロ。 スクラッチパッド呼び出しタイプ 引き数を含むものと含まないものがあります。これは、関数定義の中の SCRATCHPAD と FINAL CALL キーワードの有無と一致します。これらは、DB2 から UDF に渡される引き数で定義した SQL 状態 (SQL-state)関数名 (function-name)特定名 (specific-name)診断メッセージ (diagnostic-message)スクラッチパッド (scratchpad)、および呼び出しタイプ (call-type) という UDF 呼び出し引き数です。また、これらの構造の参照、およびさまざまな SQLSTATE 有効値に対する定義も含まれます。
  5. SQL 引き数がヌルであるかどうかをテストするマクロ。
  6. UDF に渡された LOB ロケーターによって LOB 値を操作するのに用いる、API の関数プロトタイプ。

次の項では、UDF の例を示して sqludf.h の包含と使用について説明します。


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