パラメーター・スタイル SQL

SQL パラメーター・スタイルは、業界標準の SQL に準拠しています。このパラメーター・スタイルは、スカラー UDF (ユーザー定義関数) または表 UDF で使用できます。

パラメーターは外部プログラムに、以下のように (指定された順序で) 渡されます。


>>-+------------------+--SQL-result--+----------------------+--->
   | .--------------. |              | .------------------. |   
   | V              | |              | V                  | |   
   '---SQL-argument-+-'              '---SQL-argument-ind-+-'   

>--SQL-result-ind--SQL-state--function-name--specific-name------>

>--diagnostic-message--+------------+--+-----------+------------>
                       '-scratchpad-'  '-call-type-'   

>--+--------+--------------------------------------------------><
   '-dbinfo-'

SQL-argument

この引数は、UDF を呼び出す前に、DB2® によって設定されます。この値は n 回繰り返されます。ここで n は、関数参照で指定された引数の数です。これらの引数の各値は、関数呼び出しで指定された式からとられます。これは、CREATE FUNCTION ステートメントの定義されたパラメーターのデータ・タイプの中で表されます。注: これらのパラメーターは入力としてのみ扱われます。UDF によって行われたパラメーター値の変更は、 DB2 によって無視されます。

SQL-result

この引数は、DB2 に戻る前に、UDF によって設定されます。データベースは、戻り値用の記憶域を提供します。パラメーターはアドレスで渡されるので、アドレスは、戻り値が入る記憶域のアドレスになります。データベースは、CREATE FUNCTION ステートメントで定義された戻り値に必要とされるだけの記憶域を提供します。 CREATE FUNCTION ステートメントで CAST FROM 文節が使用されている場合は、DB2 は、UDF が CAST FROM 文節で定義された値を戻すと想定し、CAST FROM 文節が使用されていない場合は、 DB2 は、UDF が RETURNS 文節で定義された値を戻すと想定します。

SQL-argument-ind

この引数は、UDF を呼び出す前に、DB2 によって設定されます。これは、対応する SQL-argument がヌルかどうかを判断するために、UDF によって使用されます。前に述べたように、n 番目の SQL-argument-ind は、n 番目の SQL-argument に対応します。各標識は、2 バイトの符号付き整数として定義されます。次の値のいずれかに設定されます。

0: 引数が存在し、ヌルではない。
-1: 引数がヌルである。

関数が RETURNS NULL ON NULL INPUT を使用して定義されている場合は、UDF はヌル値かどうかをチェックする必要はありません。ただし、関数が CALLS ON NULL INPUT を使用して定義されている場合は、どの引数も NULL にできるため、UDF ではヌルの入力があるかどうかをチェックする必要があります。注: これらのパラメーターは入力としてのみ扱われます。UDF によって行われたパラメーター値の変更は、 DB2 によって無視されます。

SQL-result-ind

この引数は、DB2 に戻る前に、UDF によって設定されます。データベースは、戻り値用の記憶域を提供します。この引数は、2 バイトの符号付き整数として定義されます。負の値に設定された場合、データベースは関数の結果をヌルとして解釈します。ゼロまたは正の値に設定された場合、データベースは SQL-result に戻された値を使用します。データベースは、戻り値標識用の記憶域を提供します。パラメーターはアドレスで渡されるので、アドレスは、標識の値が入る記憶域のアドレスになります。

SQL-state

この引数は、SQLSTATE を表す CHAR(5) の値です。

このパラメーターは、'00000' に設定されたデータベースから渡され、関数の結果状態として関数によって設定されます。通常、SQLSTATE は関数によって設定されませんが、以下のように、データベースにエラーまたは警告を送るのに使用することができます。

01Hxx: 関数コードが警告状態を検出しました。これは SQL 警告になります。ここで xx は、可能な文字ストリングのいずれかです。
38xxx: 関数コードがエラー状態を検出しました。これは SQL エラーになります。ここで xxx は、可能ないくつかのストリングのいずれかです。

function-name

この引数は、UDF を呼び出す前に、DB2 によって設定されます。引数は、関数の名前が入っている VARCHAR(139) 値です。関数コードがこの関数のために呼び出されます。

渡される関数名の形式は、以下のようになります。

     <schema-name>.<function-name>

関数コードが複数の UDF 定義で使用され、どの定義が呼び出されるかをそのコードによって識別するときに、このパラメーターが役立ちます。注: このパラメーターは入力としてのみ扱われます。UDF によって行われたパラメーター値の変更は、DB2 によって無視されます。

specific-name

この引数は、UDF を呼び出す前に、DB2 によって設定されます。引数は、関数の特定の名前が入っている VARCHAR(128) 値です。関数コードがこの関数のために呼び出されます。

function-name と同様に、関数コードが複数の UDF 定義で使用され、どの定義が呼び出されるかをそのコードによって識別するときに、このパラメーターが役立ちます。注: このパラメーターは入力としてのみ扱われます。UDF によって行われたパラメーター値の変更は、DB2 によって無視されます。

diagnostic-message

この引数は、UDF を呼び出す前に、DB2 によって設定されます。この引数は、SQLSTATE 警告またはエラーが UDF によって送られたときに、メッセージ・テキストを戻すのに UDF が使用する VARCHAR(70) 値です。

これは、UDF に入力があったときにデータベースによって初期設定され、記述情報が UDF によって設定されます。SQL-state パラメーターが UDF によって設定されていないかぎり、メッセージ・テキストは DB2 によって無視されます。

scratchpad

この引数は、UDF を呼び出す前に、DB2 によって設定されます。これは、UDF の CREATE FUNCTION ステートメントが SCRATCHPAD キーワードを指定したときにのみ存在します。この引数は、以下のエレメントをもつ構造になっています。

スクラッチパッドの長さが入っている INTEGER。
UDF への最初の呼び出しの前に、 DB2 によってすべて 2 進法の 0 に初期設定されたスクラッチパッド。

スクラッチパッドは、作業記憶域または永続記憶域として UDF によって使用されます。スクラッチパッドは、複数の UDF 呼び出しの間中、維持管理されるからです。

表関数の場合、CREATE FUNCTION で FINAL CALL が指定されていれば、スクラッチパッドは上記のように UDF に対する FIRST 呼び出しの前に初期設定されます。この呼び出しの後、スクラッチパッドの内容は全体として表関数の制御下になります。以降、DB2 はスクラッチパッドの内容を調べたり変更したりすることはありません。スクラッチパッドは、呼び出しのたびに関数に渡されます。関数は再入可能にすることができ、DB2 は関数の状態情報をスクラッチパッドに保存します。

表関数に NO FINAL CALL が指定されたかまたは省略値とされた場合、スクラッチパッドは前述のように OPEN 呼び出しのたびごとに初期設定され、OPEN 呼び出しと OPEN 呼び出しの間、スクラッチパッドの内容は完全に表関数の制御下になります。これは、結合または副照会で使用される表関数の場合、非常に重要になります。複数の OPEN 呼び出しをまたがってスクラッチパッドの内容を維持管理する必要があるときは、CREATE FUNCTION ステートメントで FINAL CALL を指定する必要があります。 FINAL CALL を指定すれば、通常の OPEN、FETCH、および CLOSE 呼び出しに加えて、スクラッチパッドの維持管理とリソースの解放のために、表関数が FIRST 呼び出しと FINAL 呼び出しも受け取ることになります。

call-type

この引数は、UDF を呼び出す前に、DB2 によって設定されます。スカラー関数の場合は、これは、UDF の CREATE FUNCTION ステートメントが FINAL CALL キーワードを指定したときにのみ存在しますが、表関数の場合は常に存在します。これは scratchpad 引数の後に続きます。スクラッチパッド引数が存在しない場合は、diagnostic-message 引数の後に続きます。この引数は、INTEGER 値の形式をとります。

スカラー関数の場合、次のようになります。

-1: このステートメントの UDF への 最初の呼び出し を示します。最初の呼び出しは、すべての SQL 引数値が渡されるという意味で 通常の呼び出し です。
0: 通常の呼び出し を示します。(通常の入力引数値のすべてが渡されます。)
1: 最終呼び出し を示します。 SQL-argument または SQL-argument-ind の値は渡されません。 UDF は、SQL-result、SQL-result-ind 引数、SQL-state、または diagnostic-message 引数を使用して応答を戻すことはありません。これらの引数は、UDF から戻るときにシステムに無視されます。

表関数の場合、次のようになります。

-2: このステートメントの UDF への 最初の呼び出し を示します。最初の呼び出しは、すべての SQL 引数値が渡されるという意味で 通常の呼び出し です。
-1: このステートメントの UDF への OPEN 呼び出し を示します。スクラッチパッドは、NO FINAL CALL が指定されている場合は初期設定されますが、それ以外の場合には必要ありません。すべての SQL 引数値が渡されます。
0: FETCH 呼び出し を示します。 DB2 は、表関数が、戻り値のセットを含む行か、または SQLSTATE 値 '02000' で示される「end-of-table (表の終わり)」条件か、いずれかを戻すことを予期しています。
1: CLOSE 呼び出し を示します。この呼び出しは OPEN 呼び出しと対応しており、外部 CLOSE 処理とリソース解放を実行するために使用できます。
2: 最終呼び出し を示します。 SQL-argument または SQL-argument-ind の値は渡されません。 UDF は、SQL-result、SQL-result-ind 引数、SQL-state、または diagnostic-message 引数を使用して応答を戻すことはありません。これらの引数は、UDF から戻るときにシステムに無視されます。

dbinfo

この引数は、UDF を呼び出す前に、DB2 によって設定されます。これは、UDF の CREATE FUNCTION ステートメントが DBINFO キーワードを指定したときにのみ存在します。この引数は、その定義が sqludf 組み込みに入っている構造です。