CALL ステートメント
CALL ステートメントは、プロシージャーまたは外部プロシージャーを呼び出します。
呼び出し
このステートメントは、アプリケーション・プログラムに組み込んだり、動的 SQL ステートメントを使用して発行したりすることができます。 このステートメントは、動的に作成できる実行可能ステートメントです。
コマンド行プロセッサーを使用して呼び出した場合、プロシージャーの引数を指定するための付加的なルールがあります。
詳しくは、 コマンド行 SQL ステートメントおよび XQuery ステートメントの使用を参照してください。
許可
ステートメントの許可 ID によって保持されている特権には、少なくとも以下のいずれかの権限が含まれていなければなりません。
- プロシージャーでの EXECUTE 特権
- プロシージャーが含まれるスキーマに対する EXECUTEIN 特権
- プロシージャーが含まれるスキーマに対する DATAACCESS 権限
- DATAACCESS 権限
実行の許可を与えられていないステートメントの許可 ID を持つ一致するプロシージャーが存在する場合、エラーが出されます (SQLSTATE 42501)。
構文
説明
- procedure-name
- 呼び出されるプロシージャーを指定します。 これは、カタログに記載されているプロシージャーか、CALL ステートメントを含むコンパウンド SQL (コンパイル済み) ステートメントのスコープ内で宣言されているプロシージャーでなければなりません。 呼び出す特定のプロシージャーは、プロシージャー解決を使用して選択します。 (詳しくは、このステートメントの「
注
」セクションを参照してください。) argument - parameter-name
- 引数が割り当てられるパラメーターの名前。 引数が、名前によってパラメーターに割り当てられる場合、それ以降の引数もすべて名前によって割り当てられる必要があります (SQLSTATE 4274K)。
名前付き引数は、一度限り (暗黙的または明示的に) 指定される必要があります (SQLSTATE 4274K)。
カタログが作成されていないプロシージャーの呼び出しでは、名前付き引数はサポートされていません (SQLSTATE 4274K)。
- expression または DEFAULT または NULL。
- 指定される expression、DEFAULT キーワードまたは NULL キーワードのどちらかは、CALL の引数です。 CALL ステートメントの n 番目の名前の付けられていない引数は、プロシージャーの CREATE PROCEDURE ステートメントで定義されている n 番目のパラメーターに対応します。
名前付き引数は、指定される順番とは無関係に、同じ名前を持つパラメーターと対応します。
DEFAULT キーワードが指定される場合、CREATE PROCEDURE ステートメントで定義されているデフォルトが存在する場合それが使用され、存在しない場合はデフォルトとして NULL 値が使用されます。
NULL キーワードが指定される場合、パラメーター値として NULL 値が渡されます。
CALL の各引数は、 以下のようなプロシージャー定義における対応するパラメーターと互換性がなければなりません。- IN パラメーター
- 引数は、パラメーターに割り当て可能でなければなりません。
- ストリング引数の割り当てには、ストレージ割り当て規則を使用します。
- OUT パラメーター
- 引数は、単一の変数またはパラメーター・マーカーでなければなりません (SQLSTATE 42886)。
- 引数は、パラメーターに割り当て可能でなければなりません。
- ストリング引数の割り当てには、検索割り当て規則を使用します。
- INOUT パラメーター
- 引数は、単一の変数またはパラメーター・マーカーでなければなりません (SQLSTATE 42886)。
- 引数は、パラメーターに割り当て可能でなければなりません。
- ストリング引数の割り当てには、呼び出しについてはストレージ割り当て規則、 および戻りに関しては検索割り当て規則を使用します。
- IN パラメーター
- 引数が割り当てられるパラメーターの名前。 引数が、名前によってパラメーターに割り当てられる場合、それ以降の引数もすべて名前によって割り当てられる必要があります (SQLSTATE 4274K)。
注
- パラメーターの割り当て: CALL ステートメントの実行時には、CALL ステートメントの引数のそれぞれの値が、プロシージャーの対応するパラメーターに割り当てられます (ストレージ割り当てを使用して)。 デフォルト値を持つように定義されているパラメーター値は、プロシージャーを呼び出すときの引数リストから除外することが可能です。
CALL ステートメントが実行される場合、ホスト言語の呼び出し規則に応じて、制御がプロシージャーに渡されます。 プロシージャーの実行が完了すると、プロシージャーの各パラメーターの値が、OUT または INOUT として定義された CALL ステートメントの対応する引数に割り当てられます (ストレージ割り当てを使用して)。 プロシージャーによってエラーが戻される場合、OUT 引数は未定義で、INOUT 引数は未変更です。 割り当て規則についての詳細は、『
割り当てと比較
』を参照してください。CALL ステートメントが SQL プロシージャーの中にあり、他の SQL プロシージャーを呼び出していれば、XML パラメーターの割り当ては参照によって行われます。 XML 引数が参照渡しであれば、入力ノード・ツリーがある場合は、XML 引数から、文書の順序、オリジナル・ノード ID、およびすべての親プロパティーなどを含むすべてのプロパティーを保持したまま、直接使用されます。
- プロシージャー・シグニチャー: プロシージャーは、そのスキーマ、プロシージャー名、およびパラメーター数によって識別されます。 これはプロシージャー・シグニチャーと呼ばれ、データベース内でユニークである必要があります。 プロシージャーごとにパラメーターの数が違っていれば、 1 つのスキーマに同じ名前のプロシージャーが複数存在しても構いません。
- SQL パス: プロシージャーは、修飾名 (スキーマおよびプロシージャー名) を参照して呼び出すことができます。修飾名の後に、括弧に囲まれた引数のオプションのリストが続きます。 また、スキーマ名を指定せずにプロシージャーを呼び出すことも可能であり、 その場合は、同じ数のパラメーターを持つ異なるスキーマのプロシージャーが選択可能になります。 このような場合、プロシージャー解決に役立つ SQL パスが使用されます。 SQL パスとは、同じ名前、 同じパラメーター数を持つプロシージャーを識別するために探索されるスキーマのリストです。 静的 CALL ステートメントに対する SQL パスは、 FUNCPATH BIND オプションを使って指定されます。 動的 CALL ステートメントの場合、 SQL パスは CURRENT PATH 特殊レジスターの値です。
- プロシージャー解決: 特定のプロシージャーの呼び出しに対して、データベース・マネージャーは、同じ名前を持つ呼び出し可能なプロシージャーの中から、どれを実行すべきかを判別する必要があります。プロシージャーがコンパウンド SQL (コンパイル済み) ステートメントの中から呼び出され、以下のいずれかの条件が存在するとき、ローカル・スコープ・プロシージャー解決が使用されます。
- 呼び出されたプロシージャーと同じ名前のプロシージャーが、同じコンパウンド SQL (コンパイル済み) ステートメントで宣言されている。
- 呼び出されたプロシージャーと同じ名前のプロシージャーが、そのプロシージャーを呼び出したコンパウンド SQL (コンパイル済み) ステートメントが内部でネストしているコンパウンド SQL (コンパイル済み) ステートメントで宣言されている。
- プロシージャー呼び出しの引数の数を A とします。
- P は、プロシージャー・シグニチャー内のパラメーターの数です。
- デフォルトを持たないパラメーターの数を N とします。
プロシージャー呼び出しの解決に対する候補プロシージャーは、以下の基準で選択されます。- 各候補プロシージャーは、一致する名前と適用可能なパラメーター数を持つ。 適用可能なパラメーター数は、条件 N ≤ A ≤ Pを満たしています。
- 各候補プロシージャーには、CALL ステートメントに含まれる名前付き引数ごとに、名前が一致して定位置 (つまり名前なし) 引数にまだ合致していないパラメーターが存在する。
- 候補プロシージャーのパラメーターのうち、対応引数が CALL ステートメントで位置でも名前でも指定されていない各パラメーターは、デフォルトを使用して定義される。
- 1 つ以上のスキーマの集合に含まれる各候補プロシージャーは、関数を呼び出しているステートメントの許可 ID に関連付けられた EXECUTE 特権を持つ。
- スキーマに含まれる各候補プロシージャーは、関数を呼び出しているステートメントの許可 ID に関連付けられたスキーマに対する EXECUTEIN 特権または DATAACCESS 権限を持つ。
- プロシージャー名が修飾されていない場合、プロシージャー解決は以下の手順を使用して行われます。
- プロシージャーがコンパウンド SQL (コンパイル済み) ステートメントの中から呼び出され、ネストしたスコープ内に同じ名前の宣言済みプロシージャーが存在する場合、CALL ステートメントが内部でネストしている一連のコンパウンド SQL (コンパイル済み) ステートメントを検索して候補プロシージャーを探します。 候補プロシージャーが見つからない場合、エラーが返されます (SQLSTATE 42884)。 1 つの候補プロシージャーが見つかると、解決が完了します。 複数の候補プロシージャーが存在する場合、パラメーターの数が最少の候補プロシージャーが判別され、パラメーター数がより多い候補プロシージャーは除去されます。
- プロシージャーがモジュール・オブジェクト内部から呼び出されると、候補となるプロシージャーがそのモジュール内で検索されます。 1 つ以上の候補となるプロシージャーがコンテキスト・モジュールで見つかると、SQL パス内のスキーマからの候補プロシージャーにこれらの候補プロシージャーが組み込まれます (次の項目を参照してください)。
- SQL パス内のスキーマを持つすべてのスキーマ・プロシージャーから候補プロシージャーを検索します。 SQL パスのスキーマで 1 つ以上の候補プロシージャーが見つかると、コンテキスト・モジュールからの候補プロシージャーにこれらの候補プロシージャーが組み込まれます (前の項目を参照してください)。 1 つの候補プロシージャーが残ると、解決が完了します。 複数の候補プロシージャーがある場合、コンテキスト・モジュールのプロシージャーが引き続き候補であればそれを選択し、そうでなければ、SQL パス内で最初に出現するスキーマを持つプロシージャーを選択します。 依然として複数の候補プロシージャーが存在する場合、パラメーターの数が最少の候補プロシージャーが判別され、パラメーター数がより多い候補プロシージャーは除去されます。
ステップ 3 の後で候補となるプロシージャーが残らなかった場合は、エラー (SQLSTATE 42884) になります。
- プロシージャー名が修飾されている場合、プロシージャー解決は以下の手順を使用して行われます。
- プロシージャーがコンパウンド SQL (コンパイル済み) ステートメントの中から呼び出され、CALL ステートメントが内部でネストしている一連のコンパウンド SQL (コンパイル済み) ステートメントの構成要素であるそのコンパウンド SQL (コンパイル済み) ステートメントのラベルと修飾子が一致し、かつ名前が同じである宣言済みプロシージャーが存在する場合、ラベルが一致するそのコンパウンド SQL (コンパイル済み) ステートメントを検索して候補プロシージャーを探します。 候補プロシージャーが見つからない場合、エラーが返されます (SQLSTATE 42884)。 1 つの候補プロシージャーが見つかると、解決が完了します。 複数の候補プロシージャーが存在する場合、パラメーターの数が最少の候補プロシージャーが判別され、パラメーター数がより多い候補プロシージャーは除去されます。
- プロシージャーがモジュール内から呼び出され、修飾子がプロシージャーを呼び出したモジュールの名前と一致する場合、候補プロシージャーをそのモジュール内で検索します。 修飾子が単一の ID である場合、モジュール名を突き合わせる際にモジュールのスキーマ名は無視されます。 修飾子が 2 つの部分から成る ID の場合、突き合わせを考慮する際にスキーマによって修飾されたモジュール名と比較されます。 単一の候補プロシージャーが存在すれば、解決が完了します。 複数の候補プロシージャーが存在する場合、パラメーターの数が最少の候補プロシージャーが選択されます。 修飾子が一致しないか、または候補プロシージャーがない場合、次の手順に進みます。
- 修飾子をスキーマ名と見なして、そのスキーマ内で候補プロシージャーを検索します。 単一の候補プロシージャーが存在すれば、解決が完了します。 複数の候補プロシージャーが存在する場合、パラメーターの数が最少の候補プロシージャーが選択され、解決は完了します。 スキーマが存在しないか、権限のある候補プロシージャーがない場合、最初の手順で修飾子がモジュールの名前と一致すると、エラーが戻ります。 そうでなければ、次の手順に進みます。
- モジュールにおける EXECUTE 特権を考慮しないで、修飾子をモジュール名と見なします。
- モジュール名がスキーマ名で修飾されている場合、このモジュール内のパブリッシュされたプロシージャーで候補プロシージャーを検索します。
- モジュール名がスキーマ名で修飾されていない場合、モジュールのスキーマは、一致するモジュール名を持つ SQL パスの最初のスキーマです。 見つかった場合、このモジュール内のパブリッシュされたプロシージャーで候補プロシージャーを検索します。
- SQL パスを使用してもモジュールが見つからない場合、プロシージャー修飾子の名前に一致するモジュールのパブリック別名を調べます。 見つかった場合、このモジュール内のパブリッシュされたプロシージャーで候補プロシージャーを検索します。
一致するモジュールが見つからない場合、または一致するモジュールに候補プロシージャーが存在しない場合、プロシージャーが見つかりませんでしたというエラー (SQLSTATE 42884) になります。 複数の候補プロシージャーが存在する場合、パラメーターの数が最少の候補プロシージャーが選択されます。 解決が完了するのは、CALL ステートメントの許可 ID に、モジュールに対する EXECUTE 特権、または残りの候補プロシージャーのモジュールを含むスキーマに対する EXECUTEIN 特権 がある場合です。それ以外の場合は、許可エラーが戻されます (SQLSTATE 42501)。
- SQL プロシージャーからの DB2_RETURN_STATUS の検索: SQL プロシージャーが RETURN ステートメントを状況値とともに正常に発行すると、この値が SQLCA の最初の SQLERRD フィールドに戻されます。 SQL プロシージャーで CALL ステートメントが発行される場合、 GET DIAGNOSTICS ステートメントを使用して DB2_RETURN_STATUS 値を検索します。 SQLSTATE がエラーを示す場合は、値は -1 になります。 エラーが出ないで、RETURN ステートメントがプロシージャーで指定されなかった場合には、 値は 0 になります。
- プロシージャーから結果セットを戻す: 呼び出し側プログラムが CLI、JDBC、または SQLJ を使用して作成されている場合、または呼び出し側が SQL プロシージャーの場合には、結果セットを呼び出し側に直接戻すことができます。 プロシージャーは、結果セットにカーソルを宣言して、その結果セットでカーソルをオープンし、
プロシージャー終了時にカーソルをオープンしたままにすることによって、結果セットを戻すよう指定します。プロシージャーの終了時に、
- オープンされたままのカーソルすべてについて、結果セットは呼び出し側に戻されるか、 (WITH RETURN TO CLIENT カーソルの場合) クライアントに直接戻されます。
- 未読の行だけが戻されます。 例えば、カーソルの結果セットに 500 行が含まれていて、 そのうち 150 行がプロシージャーの終了時にプロシージャーによって読み取られた場合、 第 151 行から第 500 行までが呼び出し側またはアプリケーションに戻されます (該当する場合)。
- パフォーマンスを改善する: すべての引数の値は、アプリケーションからプロシージャーへ渡されます。 この操作のパフォーマンスを向上させるには、 OUT パラメーターに対応し、数バイト以上の長さを持つホスト変数を、 CALL ステートメントを実行する前に NULL 値に設定しなければなりません。
- CALL ステートメントのネスト: プロシージャーは、アプリケーション・プログラムだけでなくルーチンからも呼び出すことができます。 プロシージャーをルーチンから呼び出す場合、その呼び出しはネストされるものと見なされます。プロシージャーが照会結果セットを戻す場合には、その結果セットは以下のように戻されます。
- RETURN TO CALLER 結果セットは、直前のネスト・レベルにあるプログラムでのみ可視です。
- RETURN TO CLIENT 結果セットは、 そのプロシージャーがネストされた一連のプロシージャーから呼び出された場合に限り可視になります。 呼び出しチェーンのどこかで関数やメソッドが実行されると、結果セットは不可視になります。 結果セットが可視の場合、 最初のプロシージャーが呼び出されたクライアント・アプリケーションでのみ可視になります。
以下の例について考慮します。Client program: EXEC SQL CALL PROCA; PROCA: EXEC SQL CALL PROCB; PROCB: EXEC SQL DECLARE B1 CURSOR WITH RETURN TO CLIENT ...; EXEC SQL DECLARE B2 CURSOR WITH RETURN TO CALLER ...; EXEC SQL DECLARE B3 CURSOR FOR SELECT UDFA FROM T1; UDFA: EXEC SQL CALL PROCC; PROCC: EXEC SQL DECLARE C1 CURSOR WITH RETURN TO CLIENT ...; EXEC SQL DECLARE C2 CURSOR WITH RETURN TO CALLER ...;プロシージャー PROCB から:- カーソル B1 はクライアント・アプリケーションでは可視ですが、プロシージャー PROCA では不可視です。
- カーソル B2 は PROCA では可視ですが、クライアントには不可視です。
プロシージャー PROCC から:- カーソル C1 は UDFA でもクライアント・アプリケーションでも不可視です。 (UDFA はクライアントと PROCC との間の呼び出しチェーンで現れ、 結果セットはクライアントに戻されないからです。)
- カーソル C2 は UDFA では可視ですが、上位のプロシージャーでは不可視です。
- トリガー、コンパウンド・ステートメント、関数、またはメソッド内のネストされたプロシージャー: トリガー、コンパウンド・ステートメント、関数、またはメソッドの中で、プロシージャーが呼び出されるときは、次のとおりです。
- プロシージャーは COMMIT または ROLLBACK ステートメントを発行してはなりません。
- プロシージャーから戻される結果セットにはアクセスできません。
- プロシージャーが READS SQL DATA または MODIFIES SQL DATA として定義されている場合、
プロシージャーを呼び出したステートメントによって変更されている表には、
プロシージャー内のどのステートメントからもアクセスできません (SQLSTATE 57053)。 また、プロシージャーが MODIFIES SQL DATA として定義されている場合は、
プロシージャーを呼び出したステートメントによって読み取りまたは変更されている表には、
プロシージャー内のどのステートメントからもアクセスできません (SQLSTATE 57053)。関数またはメソッドの中でプロシージャーが呼び出されるときは、次のとおりです。
- プロシージャーは、呼び出された関数またはメソッドと同じ表アクセスに関する制約事項を持ちます。
- 関数またはメソッドが呼び出される前に定義されたセーブポイントは、プロシージャーでは不可視です。 またプロシージャー内で定義されたセーブポイントは関数またはメソッド以外では不可視になります。
- プロシージャーから戻される RETURN TO CLIENT 結果セットに、 クライアントからアクセスすることはできません。
- Db2® for IBM® i および Db2 for z/OS®: Db2 for IBM i および Db2 for z/OS からの CALL ステートメントのコンパイルは、CALL_RESOLUTION DEFERRED が指定されているかのように暗黙的に動作します。 CALL_RESOLUTION DEFERRED を指定して CALL ステートメントをコンパイルする際には、すべての引数はホスト変数によって提供しなければならず、式は許可されません。
- 代替構文: CALL_RESOLUTION DEFERRED オプションを使用してアプリケーションを事前にコンパイルすると、アプリケーションに組み込める旧書式の CALL ステートメントがあります。 このオプションは SQL プロシージャーおよびフェデレーテッド・プロシージャーには使用できません。
例
- 例 1: Java™ プロシージャーは、以下のステートメントを使用してデータベースに定義されます。
CREATE PROCEDURE PARTS_ON_HAND (IN PARTNUM INTEGER, OUT COST DECIMAL(7,2), OUT QUANTITY INTEGER) EXTERNAL NAME 'parts!onhand' LANGUAGE JAVA PARAMETER STYLE DB2GENERAL;Java アプリケーションは、以下のコード・フラグメントを使用してこのプロシージャーを呼び出します。... CallableStatement stpCall; String sql = "CALL PARTS_ON_HAND (?, ?, ?)"; stpCall = con.prepareCall(sql); /*con is the connection */ stpCall.setInt(1, hvPartnum); stpCall.setBigDecimal(2, hvCost); stpCall.setInt(3, hvQuantity); stpCall.registerOutParameter(2, Types.DECIMAL, 2); stpCall.registerOutParameter(3, Types.INTEGER); stpCall.execute(); hvCost = stpCall.getBigDecimal(2); hvQuantity = stpCall.getInt(3); ...このアプリケーション・コード・フラグメントは、クラス
partsの Java メソッドonhandを呼び出します。これは、CALL ステートメントで指定されたプロシージャー名がデータベース内にあり、外部名がparts!onhandであるためです。 - 例 2: 4 つの異なるスキーマに 6 個の FOO プロシージャーがあり、以下のように登録されているとします (必須キーワードの一部は省略されています)。
CREATE PROCEDURE AUGUSTUS.FOO (INT) SPECIFIC FOO_1 ... CREATE PROCEDURE AUGUSTUS.FOO (DOUBLE, DECIMAL(15, 3)) SPECIFIC FOO_2 ... CREATE PROCEDURE JULIUS.FOO (INT) SPECIFIC FOO_3 ... CREATE PROCEDURE JULIUS.FOO (INT, INT, INT) SPECIFIC FOO_4 ... CREATE PROCEDURE CAESAR.FOO (INT, INT) SPECIFIC FOO_5 ... CREATE PROCEDURE NERO.FOO (INT,INT) SPECIFIC FOO_6 ...以下のようにプロシージャーが参照されるとします (I1 および I2 は INTEGER 値です)。CALL FOO(I1, I2)この参照を行うアプリケーションの SQL パスが次のようになっているとします。"JULIUS", "AUGUSTUS", "CAESAR"アルゴリズムに従っていきます。
スキーマ "NERO" が SQL パスに含まれていないため、特定の名前 FOO_6 のあるプロシージャーは候補から除かれます。 パラメーターの数が違うため、FOO_1、FOO_3、および FOO_4 は候補から除かれます。 残った候補は順番に考慮され、SQL パスにより判別します。 引数およびパラメーターのタイプは無視されることに注意してください。 FOO_5 のパラメーターは CALL の引数と正確に一致しますが、 SQL パスで "CAESAR" の前に "AUGUSTUS" が現れるため FOO_2 が選ばれます。
- 例 3: 以下のプロシージャーが存在するものと想定します。
CREATE PROCEDURE update_order( IN IN_POID BIGINT, IN IN_CUSTID BIGINT DEFAULT GLOBAL_CUST_ID, IN NEW_STATUS VARCHAR(10) DEFAULT NULL, IN NEW_ORDERDATE DATE DEFAULT NULL, IN NEW_COMMENTS VARCHAR(1000)DEFAULT NULL)...また、グローバル変数GLOBAL_CUST_IDが 1002 という値に設定されているものとします。 カスタマー 1002 の注文 5000 の状況を「出荷済み」に変更するためにプロシージャーを呼び出します。 残りの引数をデフォルトの NULL 値にしておくことで、その他の注文データは現状のままとすることができます。CALL update_order (5000, NEW_STATUS => 'Shipped')1001 という ID を持つカスタマーから連絡があり、購買注文 5002 の品物を受け取って満足していると示されます。 注文を更新します。CALL update_order (5002, IN_CUSTID => 1001, NEW_STATUS => 'Received', NEW_COMMENTS => 'Customer satisfied with the order.') - 例 4: 次の例は、p1 という名前のプロシージャーが 2 つある場合のプロシージャー解決を示しています。
候補選択の過程で引数名が考慮に入れられます。 したがって、2 番目のバージョンの p1 のみが候補と見なされます。 さらに、これは正常に呼び出されます。このバージョンの p1 の i1 はデフォルトを指定して定義されているので、p1 の呼び出しで i2 のみを指定しても有効だからです。CREATE PROCEDURE p1(i1 INT)... CREATE PROCEDURE p1(i1 INT DEFAULT 0, i2 INT DEFAULT 0)... CALL p1(i2=>1) - 例 5: 次の例は、p1 という名前のプロシージャーが 2 つある場合の別のプロシージャー解決を示しています。
対応する引数の位置も名前も CALL ステートメントで指定されていないプロシージャー・パラメーターの基準の 1 つは、そのパラメーターがデフォルト値を使用して定義されているということです。 したがって、最初のバージョンの p1 は候補と見なされません。CREATE PROCEDURE p1(i1 INT, i2 INT DEFAULT 0)... CREATE PROCEDURE p1(i1 INT DEFAULT 0, i2 INT DEFAULT 0, i3 INT DEFAULT 0)... CALL p1(i2=>1)