ASSOCIATE LOCATORS

ASSOCIATE LOCATORS ステートメントは、プロシージャーが戻すそれぞれの結果セットについての結果セット・ロケーター変数を入手します。

呼び出し

このステートメントは、 アプリケーション・プログラムに組み込むことができます。これは、動的に準備できる実行可能ステートメントです。これを対話式に発行することはできません。REXX で指定してはなりません。

権限

権限は不要です。

構文

構文図を読む構文図をスキップする
                                               .-,-------------------.      
              .-RESULT SET-.                   V                     |      
>>-ASSOCIATE -+------------+--+-LOCATOR--+--(----rs-locator-variable-+--)-->
                              '-LOCATORS-'                                  

>--WITH--+-+-+-PROCEDURE-+--procedure-name--+------------------------------+-+-+-><
         | | '-ROUTINE---'                  '-(--+--------------------+--)-' | |   
         | |                                     | .-,--------------. |      | |   
         | |                                     | V                | |      | |   
         | |                                     '---parameter-type-+-'      | |   
         | '-SPECIFIC--+-PROCEDURE-+--specific-name--------------------------' |   
         |             '-ROUTINE---'                                           |   
         '-PROCEDURE--variable-------------------------------------------------'   

parameter-type

|----data-type--+------------+----------------------------------|
                '-AS LOCATOR-'     

data-type

|--+-built-in-type------+---------------------------------------|
   '-distinct-type-name-'   

構文図を読む構文図をスキップする
built-in-type

|--+-+---SMALLINT---+----------------------------------------------------------------------+--|
   | +-+-INTEGER-+--+                                                                      |   
   | | '-INT-----'  |                                                                      |   
   | '---BIGINT-----'                                                                      |   
   |                  .-(5,0)------------------------.                                     |   
   +-+-+-DECIMAL-+-+--+------------------------------+-------------------------------------+   
   | | '-DEC-----' |  |             .-,0--------.    |                                     |   
   | '-+-NUMERIC-+-'  '-(--integer--+-----------+--)-'                                     |   
   |   '-NUM-----'                  '-, integer-'                                          |   
   |          .-(--52--)------.                                                            |   
   +-+-FLOAT--+---------------+-+----------------------------------------------------------+   
   | |        '-(--integer--)-' |                                                          |   
   | +-REAL---------------------+                                                          |   
   | |         .-PRECISION-.    |                                                          |   
   | '-DOUBLE--+-----------+----'                                                          |   
   |             .-(--34--)-.                                                              |   
   +---DECFLOAT--+----------+--------------------------------------------------------------+   
   |             '-(--16--)-'                                                              |   
   |                    .-(--1--)-------.                                                  |   
   +-+-+-+-CHARACTER-+--+---------------+----------+--+----------------+-----------------+-+   
   | | | '-CHAR------'  '-(--integer--)-'          |  +-FOR BIT DATA---+                 | |   
   | | '-+-+-CHARACTER-+--VARYING-+--(--integer--)-'  +-FOR SBCS DATA--+                 | |   
   | |   | '-CHAR------'          |                   +-FOR MIXED DATA-+                 | |   
   | |   '-VARCHAR----------------'                   '-ccsid-clause---'                 | |   
   | |                                      .-(--1M--)-------------.                     | |   
   | '---+-+-CHARACTER-+--LARGE OBJECT-+----+----------------------+--+----------------+-' |   
   |     | '-CHAR------'               |    '-(--integer--+---+--)-'  +-FOR SBCS DATA--+   |   
   |     '-CLOB------------------------'                  +-K-+       +-FOR MIXED DATA-+   |   
   |                                                      +-M-+       '-ccsid-clause---'   |   
   |                                                      '-G-'                            |   
   |                .-(--1--)-------.                                                      |   
   +-+---GRAPHIC----+---------------+-------+--+--------------+----------------------------+   
   | |              '-(--integer--)-'       |  '-ccsid-clause-'                            |   
   | +-+-GRAPHIC VARYING-+--(--integer--)---+                                              |   
   | | '-VARGRAPHIC------'                  |                                              |   
   | |             .-(--1M--)-------------. |                                              |   
   | '---DBCLOB----+----------------------+-'                                              |   
   |               '-(--integer--+---+--)-'                                                |   
   |                             +-K-+                                                     |   
   |                             +-M-+                                                     |   
   |                             '-G-'                                                     |   
   |                             .-(--1--)-------.                                         |   
   +-+-+-+-NATIONAL CHARACTER-+--+---------------+----------+---------------------+--------+   
   | | | +-NATIONAL CHAR------+  '-(--integer--)-'          |                     |        |   
   | | | '-NCHAR--------------'                             |                     |        |   
   | | '-+-+-NATIONAL CHARACTER-+--VARYING-+--(--integer--)-'                     |        |   
   | |   | +-NATIONAL CHAR------+          |                                      |        |   
   | |   | '-NCHAR--------------'          |                                      |        |   
   | |   '-NVARCHAR------------------------'                                      |        |   
   | |                                                   .-(--1M--)-------------. |        |   
   | '-----+-+-NATIONAL CHARACTER-+--LARGE OBJECT-+------+----------------------+-'        |   
   |       | '-NCHAR--------------'               |      '-(--integer--+---+--)-'          |   
   |       '-NCLOB--------------------------------'                    +-K-+               |   
   |                                                                   +-M-+               |   
   |                                                                   '-G-'               |   
   |             .-(--1--)-------.                                                         |   
   +-+-+-BINARY--+---------------+---------+-----------------+-----------------------------+   
   | | |         '-(--integer--)-'         |                 |                             |   
   | | '-+-BINARY VARYING-+--(--integer--)-'                 |                             |   
   | |   '-VARBINARY------'                                  |                             |   
   | |                              .-(--1M--)-------------. |                             |   
   | '---+-BLOB----------------+----+----------------------+-'                             |   
   |     '-BINARY LARGE OBJECT-'    '-(--integer--+---+--)-'                               |   
   |                                              +-K-+                                    |   
   |                                              +-M-+                                    |   
   |                                              '-G-'                                    |   
   +-+-DATE-------------------------+------------------------------------------------------+   
   | |       .-(--0--)-.            |                                                      |   
   | +-TIME--+---------+------------+                                                      |   
   | |            .-(--6--)-------. |                                                      |   
   | '-TIMESTAMP--+---------------+-'                                                      |   
   |              '-(--integer--)-'                                                        |   
   |             .-(--200--)-----.                                                         |   
   +---DATALINK--+---------------+--+--------------+---------------------------------------+   
   |             '-(--integer--)-'  '-ccsid-clause-'                                       |   
   +---ROWID-------------------------------------------------------------------------------+   
   '---XML---------------------------------------------------------------------------------'   

ccsid-clause

|--CCSID--integer-----------------------------------------------|

説明

rs-locator-variable
結果セット・ロケーター変数を宣言するための 規則に従い、すでに宣言された 規則セット・ロケーター変数を指定します。
WITH PROCEDURE procedure-name または variable
1 つ以上の結果セットを戻したプロシージャーを識別します。ASSOCIATE LOCATORS ステートメントを実行する際のプロシージャー名は、リクエスターがすでに 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 ステートメントを 使用して呼び出された場合、変数はプロシージャー名として使用されます。 この名前の複数のプロシージャーが呼び出された場合、変数は特定名として 使用されます。

ロケーター値の割り当て。SET RESULT SETS ステートメントがプロシージャーで実行される場合は、その SET RESULT SETS ステートメントが結果セットを識別します。ロケーター値は、SET RESULT SETS ステートメントで指定した順序で、記述子域の項目または SQLDA の SQLVAR 項目に割り当てられます。プロシージャーで SET RESULT SETS ステートメントが実行されなかった場合は、実行時に関連カーソルがオープンした順序でロケーター値がロケーター変数に割り当てられます。ロケーター値がロケーター変数に割り当てられる順序は、DESCRIBE PROCEDURE ステートメントの結果としてロケーター値が SQL 記述子域または SQLDA 内の項目に配置される順序と同じです。

ロケーター値は、呼び出し側のアプリケーションに制御が戻されるとクローズされるカーソルには提供されません。カーソルがクローズされ、呼び出し側のアプリケーションに戻る前に再度オープンされた場合は、プロシージャー結果セットにロケーター値が戻される順序を決めるために、カーソルに対して最新に実行された OPEN CURSOR ステートメントが使用されます。例えば、プロシージャー P1 が 3 つのカーソル A、B、C をオープンして、カーソル B をクローズし、呼び出し側のアプリケーションに戻る前にカーソル B に対して別の OPEN CURSOR ステートメントを実行したとします。次の ASSOCIATE LOCATORS ステートメントに割り当てられるロケーター値の順序は、A、C、B になります。

ASSOCIATE RESULT SET LOCATORS (:loc1, :loc2, :loc3) WITH PROCEDURE P1;

複数のロケーターを結果セットに関連付けることができます。同じプロシージャーに対して、異なる結果セット・ロケーター変数を指定して複数の ASSOCIATE LOCATORS ステートメントを発行することにより、それぞれの結果セットに複数のロケーターを関連付けることができます。
  • ASSOCIATE LOCATORS ステートメントに指定された結果セット・ロケーター変数の数が、プロシージャーから戻される結果セットの数より少ない場合、ステートメントに指定されたロケーター変数すべてに値が割り当てられ、警告が出されます。例えば、プロシージャー P1 が存在し、4 つの結果セットを戻すとします。次の ASSOCIATE LOCATORS ステートメントはそれぞれ、最初の結果セットに関する情報とともに、すべての結果セットに関する情報を得るために十分なロケーターがなかったことを示す警告を戻します。

    CALL P1;

    ASSOCIATE RESULT SET LOCATORS (:loc1) WITH PROCEDURE P1; -> loc1 is assigned a value for first result set, and a warning is returned

    ASSOCIATE RESULT SET LOCATORS (:loc2) WITH PROCEDURE P1; -> loc2 is assigned a value for first result set, and a warning is returned

    ASSOCIATE RESULT SET LOCATORS (:loc3) WITH PROCEDURE P1; -> loc3 is assigned a value for first result set, and a warning is returned

    ASSOCIATE RESULT SET LOCATORS (:loc4) WITH PROCEDURE P1; -> loc4 is assigned a value for first result set, and a warning is returned

  • ASSOCIATE LOCATORS ステートメントにリストされている結果セット・ロケーター変数の数が、プロシージャーによって戻されるロケーターの数より多い場合は、余分のロケーター変数に値 0 が割り当てられます。

同じプロシージャーに対する複数の呼び出し: 同じプログラムから同じプロシージャーに対して複数の呼び出しを実行すると、先行の呼び出しの結果セットが失われます。ただし、プロシージャーに対する後続の CALL の前に ASSOCIATE LOCATOR ステートメントを実行する場合は、例外です。ASSOCIATE LOCATORS ステートメントでは、最新の CALL を参照します。

EXEC SQL CALL P1; /* Returns 2 result sets */

EXEC SQL CALL P1; /* Returns 2 result sets, result sets from first invocation are closed */

EXEC SQL ASSOCIATE RESULT SET LOCATORS (:a, :b) WITH PROCEDURE P1; /* Refers to second call */

EXEC SQL CALL P1; /* Returns 2 result sets */

EXEC SQL ASSOCIATE RESULT SET LOCATORS (:c, :d) WITH PROCEDURE P1; /* Refers to third call */

/* The following statements process the result sets from the second call */
EXEC SQL ALLOCATE C1 CURSOR FOR RESULT SET :a;
EXEC SQL ALLOCATE C2 CURSOR FOR RESULT SET :b;
EXEC SQL FETCH C1 INTO :h1;
EXEC SQL CLOSE C1;
EXEC SQL FETCH C2 INTO :h2;
EXEC SQL CLOSE C2;  

/* The following statements process the result sets from the third call */
EXEC SQL ALLOCATE C3 CURSOR FOR RESULT SET :c;
EXEC SQL ALLOCATE C4 CURSOR FOR RESULT SET :d;
EXEC SQL FETCH C3 INTO :h1;
EXEC SQL CLOSE C3;
EXEC SQL FETCH C4 INTO :h2;
EXEC SQL CLOSE C4; 

RETURN TO CLIENT プロシージャー: RETURN TO CLIENT プロシージャーの 結果セットは、呼び出しスタックの最高位のプロシージャーと関連付けられます。 そういった結果セットにロケーターを関連付けるには、 呼び出しスタックの最高位のプロシージャーのプロシージャー名を指定する必要があります。

3 つの結果セットを返すプロシージャー P1 の結果セット・ロケーターを割り振ります。

    ASSOCIATE RESULT SET LOCATORS (:loc11, :loc2, :loc3) WITH PROCEDURE P1;