DESCRIBE PROCEDURE
DESCRIBE PROCEDURE ステートメントは、プロシージャーが戻した結果セットについての情報を入手します。結果セットなどの情報は、記述子 に入れられます。
呼び出し
このステートメントは、アプリケーション・プログラム、SQL 関数、 SQL プロシージャー、またはトリガー内にのみ組み込むことができます。 これは実行可能ステートメントですが、動的に準備することはできません。Java™ および REXX では指定できません。
権限
権限は不要です。
構文
>>-DESCRIBE -+-+-+-PROCEDURE-+--procedure-name--+------------------------------+-+-+--> | | '-ROUTINE---' '-(--+--------------------+--)-' | | | | | .-,--------------. | | | | | | V | | | | | | '---parameter-type-+-' | | | '-SPECIFIC--+-PROCEDURE-+--specific-name--------------------------' | | '-ROUTINE---' | '-PROCEDURE--variable-------------------------------------------------' .-SQL-. .-LOCAL--. >--+-USING--+-----+--DESCRIPTOR--+--------+--SQL-descriptor-name-+->< | '-GLOBAL-' | '-INTO----descriptor-name-------------------------------------' parameter-type |----data-type--+------------+----------------------------------| '-AS LOCATOR-' data-type |--+-built-in-type------+---------------------------------------| '-distinct-type-name-'
説明
- procedure-name または specific-name または variable
- 1 つ以上の結果セットを戻したプロシージャーを識別します。DESCRIBE PROCEDURE ステートメントを実行する際のプロシージャー名は、リクエスターがすでに SQL CALL ステートメントを使用して呼び出したプロシージャーを示している必要があります。
- PROCEDURE または SPECIFIC PROCEDURE
- 記述するプロシージャーを指定します。このプロシージャー名 は、現行サーバーに存在しているプロシージャーを識別していなければなりません。
- PROCEDURE procedure-name
- プロシージャーを名前によって識別します。 プロシージャー名 は、ただ 1 つのプロシージャーを識別していなければなりません。 このプロシージャーには、パラメーターをいくつでも定義することができます。 指定されたスキーマまたは暗黙のスキーマの中に、 指定された名前のプロシージャーが複数ある場合、エラーが戻されます。
- PROCEDURE procedure-name (parameter-type, ...)
- プロシージャーを一意的に識別するプロシージャー・シグニチャーによって、プロシージャーを識別します。
procedure-name (parameter-type,...) では、指定されたプロシージャー・シグニチャーを持つプロシージャーを識別する必要があります。
指定されたパラメーターは、プロシージャーの作成時に指定された、
対応する位置にあるデータ・タイプと一致していなければなりません。
ラベルを付ける対象のプロシージャー・インスタンスを識別するには、データ・タイプの数とデータ・タイプの論理連結を使用します。データ・タイプの同義語は、一致として扱われます。
デフォルトがあるパラメーターは、このシグニチャーに含まれていなければなりません。
プロシージャー名 () を指定する場合、識別されるプロシージャー にパラメーターを使用することはできません。
- procedure-name
- プロシージャーの名前を識別します。
- (parameter-type, ...)
- プロシージャーのパラメーターを識別します。
非修飾の特殊タイプ名または配列タイプ名を指定する場合、データベース・マネージャーはその特殊タイプまたは配列タイプのスキーマ名を解決するための SQL パスを検索します。
長さ属性、精度属性、あるいは位取り属性があるデータ・タイプの場合、以下のいずれかを使用します。
- 空の括弧は、データベース・マネージャーがデータ・タイプの一致の判別に際して属性を無視することを示します。例えば、DEC() は、DEC(7,2) のデータ・タイプで定義されたプロシージャーのパラメーターに一致するものとみなされます。 ただし、FLOAT に空の括弧を指定することはできません。これは、そのパラメーター値が特定のデータ・タイプ (REAL または DOUBLE) を示しているからです。
- 長さ属性、精度属性、あるいは位取り属性に特定の値を指定する場合、その値は、 CREATE PROCEDURE ステートメントの中で暗黙的または明示的に指定された値と正確に一致している必要があります。 データ・タイプが FLOAT の場合、 突き合わせはデータ・タイプ (REAL または DOUBLE) に基づいて行われるので、 精度は指定された値に厳密に一致している必要はありません。
- 長さ属性、精度属性、または位取り属性が明示的に指定されておらず、空の括弧も指定されていない場合、該当のデータ・タイプのデフォルト属性が暗黙指定されます。暗黙の長さは、CREATE PROCEDURE ステートメントの中で暗黙的または明示的 に指定された値と正確に一致している必要があります。
FOR DATA 文節または CCSID 文節の指定はオプショナルです。 いずれの文節も指定しないと、データ・タイプが一致するかどうかを判定する場合に、データベース・マネージャーが属性を無視することを示します。 どちらか一方の文節を指定する場合は、CREATE PROCEDURE ステートメントに 暗黙的または明示的に指定されている値と一致させる必要があります。
- AS LOCATOR
- プロシージャーが、このパラメーターのロケーターを受け取るように定義されることを示します。 AS LOCATOR を指定する場合は、データ・タイプは LOB または XML、あるいは LOB または XML に基づく特殊タイプでなければなりません。 AS LOCATOR を指定した場合、FOR SBCS DATA または FOR MIXED DATA を指定してはなりません。
- SPECIFIC PROCEDURE specific-name
- プロシージャーを特定名によって識別します。 特定名 は、現行サーバーに存在してい る特定のプロシージャーを識別していなければなりません。
- variable
- プロシージャー名または特定名を含んでいる変数を
指定します。variable を指定した場合:
- その変数は、文字ストリング変数またはユニコード・グラフィック・ストリング変数でなければなりません。この変数は、グローバル変数にすることはできません。
- 標識変数を伴っていてはなりません。
- 変数内に含まれる名前は左寄せでなければならず、その長さが変数の長さより短い場合は、右側にブランクを埋め込まなければなりません。
- 名前は、区切り文字付きの名前でない限り、大文字でなければなりません。
この名前の 1 つのプロシージャーのみが CALL ステートメントを 使用して呼び出された場合、変数はプロシージャー名として使用されます。 この名前の複数のプロシージャーが呼び出された場合、変数は特定名として 使用されます。
- USING
- SQL 記述子を識別します。
- LOCAL
- 記述子の名前の有効範囲はプログラム呼び出しのローカルであることを指定します。
- GLOBAL
- 記述子の名前の有効範囲は SQL セッション全体であることを指定します。
- SQL-descriptor-name
- SQL 記述子の名前を指定します。名前は、指定の有効範囲を持つ既存の記述子を識別するものでなければなりません。
DESCRIBE PROCEDURE の実行後に、GET DESCRIPTOR ステートメントで以下の値を取得できます。
- DB2_RESULT_SETS_COUNT。結果セットの総数が入ります。 0 の値は結果セットがないことを示します。
各結果セットについて 1 つの記述子域がある。
- DB2_RESULT_SET_LOCATOR。結果セットに関連した結果セット・ロケーターの値が入ります。
- DB2_CURSOR_NAME。プロシージャーが結果セットを返すために使用したカーソルの名前が入ります。
- DB2_RESULT_SET_ROWS。結果セットの行の概数。数が不明な場合は、-1 が設定されます。
SQL 記述子に入る情報の説明については、GET DESCRIPTORを参照してください。
- INTO descriptor-name
- SQL 記述子域 (SQLDA) を指定します。これについては、SQLDA (SQL 記述子域)で説明しています。DESCRIBE PROCEDURE ステートメントを実行する前に、SQLDA の以下の変数をセットしておく必要があります。
- SQLN
- SQLDA で用意される SQLVAR オカレンスの数を指定します。 DESCRIBE PROCEDURE ステートメントを実行する前に、SQLN にゼロ以上の値をセットしておく必要があります。
DESCRIBE ステートメントが実行されると、データベース・マネージャーでは、SQLDA の各変数に次のような値を割り当てます。
- SQLDAID
- 最初の 5 バイトは「SQLPR」に設定される。6 から 8 バイトは予約されている。
- SQLDABC
- SQLDA の長さ (バイト)。
- SQLD
- 結果セットの総数。0 の値は結果セットがないことを示します。
- SQLVAR
- SQLD の値が 0 の場合、または SQLD の値が SQLN の値より大きい場合は、SQLVAR のオカレンスには値が割り当てられません。
SQLD の値が n (ただし、n は 0 より大きいが、SQLN の値より小さいか、または等しい値) の場合は、値が SQLVAR の最初の n 個のオカレンスに割り当てられ、その結果、SQLVAR の最初のオカレンスには最初の結果セットの記述が入り、SQLVAR の 2 番目のオカレンスには 2 番目の結果セットの記述が入ります。以下同様です。それぞれの SQLVAR 項目ごとに、以下のようになります。
- SQLDATA フィールドは結果セットと関連する結果セット・ロケーター値に設定される。
- SQLIND フィールドは結果セット内の行の予測数に設定される。数が不明な場合は、-1 が設定されます。
- SQLNAME フィールドは、結果セットを戻すために ストアード・プロシージャーが使用するカーソル名に 設定される。カーソル名の長さが 30 文字を超えている場合は、カーソル名が 30 文字に切り捨てられます。
注
DESCRIBE PROCEDURE はプロシージャーが必要とするパラメーターについての情報を戻しません。
DESCRIBE PROCEDURE ステートメントの前に、対象のプロシージャーに対する CALL が必要です。
SQL 記述子の割り振り: DESCRIBE PROCEDURE ステートメントを実行する前に、ALLOCATE DESCRIPTOR ステートメントを使用して SQL 記述子を割り振らなければなりません。割り振られた記述子項目の数が結果セットの数よりも小さい場合、警告 (SQLSTATE 01005) が戻されます。
SQLDA の割り振り: DESCRIBE PROCEDURE ステートメントを実行する前に、SQLN にゼロ以上の値をセットして、SQLDA に用意する SQLVAR のオカレンスの数を指示するとともに、SQLN の各オカレンスを収容するのに十分な記憶域を割り振っておく必要があります。プロシージャーの結果セットの記述を取得するには、SQLVAR のオカレンスの数が結果セットの数以上でなければなりません。
提供されるオカレンスが不足していて、オカレンスのすべてのセットを戻せるとは限らない場合、SQLN は、すべての情報を戻すのに必要なオカレンスの合計数に設定されます。それ以外の場合、SQLN は、結果セットの数に設定されます。
ロケーター値の割り当て: SET RESULT SETS ステートメントがプロシージャーで実行される場合は、その SET RESULT SETS ステートメントが結果セットを識別します。ロケーター値は、SET RESULT SETS ステートメントで指定した順序で、記述子域の項目または SQLDA の SQLVAR 項目に割り当てられます。プロシージャーで SET RESULT SETS ステートメントを実行しなかった場合は、関連するカーソルが実行時にオープンした順序で、記述子域の項目または SQLDA の SQLVAR 項目にロケーター値が割り当てられます。ロケーター値は、呼び出し側のアプリケーションに制御が戻されるとクローズされるカーソルには提供されません。カーソルがクローズされ、呼び出し側のアプリケーションに戻る前に再度オープンされた場合は、プロシージャー結果セットにロケーター値が戻される順序を決めるために、カーソルに対して最新に実行された OPEN CURSOR ステートメントが使用されます。例えば、プロシージャー P1 が 3 つのカーソル A、B、および、C をオープンして、カーソル B をクローズし、呼び出し側のアプリケーションに戻る前にカーソル B に対して別の OPEN CURSOR ステートメントを実行したとします。ロケーター値は、A、C、B の順序で割り当てられます。
また、ASSOCIATE LOCATORS ステートメントを使用して、ロケーター値を結果セットのロケーター変数にコピーすることもできます。
例
プロシージャー P1 から返される結果セットに関する情報を SQL 記述子に配置します。
EXEC SQL CALL P1;
EXEC SQL ALLOCATE DESCRIPTOR 'DESC1';
EXEC SQL DESCRIBE PROCEDURE P1 USING SQL DESCRIPTOR 'DESC1';