ASSOCIATE LOCATORS ステートメント

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

呼びかけ ASSOCIATE LOCATORS

このステートメントは、アプリケーション・プログラムに組み込むことができます。このステートメントは、動的に作成できる実行可能ステートメントです。このステートメントは対話式に出すことはできません。

承認 ASSOCIATE LOCATORS

不要です。

構文 ASSOCIATE LOCATORS

説明の対象: ASSOCIATE LOCATORS

rs-locator-variable

結果セット・ロケーター変数を宣言するための規則に従い、既に宣言された規則セット・ロケーター変数を指定します。

WITH PROCEDURE procedure-name または host-variable

1 つ以上の結果セットを戻したストアード・プロシージャーを識別します。 ASSOCIATE LOCATORS ステートメントを実行する際のプロシージャー名は、リクエスターが既に SQL CALL ステートメントを使用して呼び出したストアード・プロシージャーを示している必要があります。プロシージャー名は、1 部構成、2 部構成、または 3 部構成の名前として指定できます。 ASSOCIATE LOCATORS ステートメントのプロシージャー名は、 CALL ステートメントで指定したのと同じ方法で指定しなければなりません。例えば、CALL ステートメントに 2 部構成のプロシージャー名が指定されている場合は、ASSOCIATE LOCATORS ステートメントに 2 部構成のプロシージャー名を指定する必要があります。

ホスト変数を使用して名前を指定する場合は、次の規則に従ってください。

長さ属性が 255 以下の文字ストリング変数でなければなりません。
後ろに標識変数を置いてはなりません。
ホスト変数の値の指定は、サーバーによって異なります。その指定は、サーバーに関係なく、次の規則に従う必要があります。
- ホスト変数内では左寄せ
- 埋め込まれたブランクを含まない
- 長さがホスト変数の長さより短い場合は、ブランクが右方に埋め込まれる

注釈 ASSOCIATE LOCATORS

ロケーター値の割り当て: ASSOCIATE LOCATORS ステートメントが複数のロケーター変数を指定している場合、まだオープンかどうかには関係なく実行時に関連したカーソルがオープンされる順序でロケーター値がロケーター変数に割り当てられます。ロケーター値がロケーター変数に割り当てられる順序は、DESCRIBE PROCEDURE ステートメントの結果としてロケーター値が SQLDA 内の SQLVAR 項目に配置される順序と同じです。

ロケーター値は、呼び出し側のアプリケーションに制御が戻されるとクローズされるカーソルには提供されません。カーソルがクローズされ、呼び出し側のアプリケーションに戻る前に再オープンされた場合は、プロシージャー結果セットにロケーター値が戻される順序を決めるために、カーソルに対して最新に実行された 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;
   -- assigns locators for result set cursors A, C, and B

複数のロケーターを結果セットに関連付けることができます。同じストアード・プロシージャーに対して、異なる結果セット・ロケーター変数を指定して複数の 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 ステートメントから得られた結果セットへのアクセス: アプリケーションは、複数の CALL ステートメントによって作成された結果セットにアクセスできます。結果セットは、異なるプロシージャーによって作成されたものであっても、同じプロシージャーを複数回呼び出して作成されたものであっても構いません。

異なるプロシージャーの呼び出し: 異なるコレクションを指定することによって明示的に、あるいは PACKAGE PATH を使用して暗黙的に、異なるプロシージャーを同じ名前によって呼び出すことができます。例えば、異なるコレクションを明示的に識別するには、CALL ステートメントに修飾名を指定します。プロシージャーの名前は両方とも P2 ですが、これらは異なるプロシージャーです。 2 番目の CALL ステートメントの後、アプリケーションは両方のプロシージャーからの結果セットにアクセスできます。
```
CALL X.P2;
CALL Y.P2;
```
CALL ステートメントの中で非修飾のプロシージャー名が指定されている場合は、2 つの異なるプロシージャーのコレクションが PACKAGE PATH から暗黙的に決定されることもあります。例えば、プロシージャー P4 がコレクション X および Z に存在するとします。アプリケーションには、プロシージャー P4 を呼び出すための 2 つの CALL ステートメントが含まれています。 CALL ステートメント内で、プロシージャー P4 の参照は非修飾です。この場合、プロシージャー名を解決するために PACKAGE PATH 特殊レジスターが使用されます。最初の CALL ステートメントに対してはプロシージャー X.P4 が呼び出され、2 番目の CALL ステートメントはプロシージャー Z.P4 を呼び出します。 2 番目の CALL ステートメントの後、アプリケーションは両方のプロシージャーからの結果セットにアクセスできます。
```
SET CURRENT PACKAGE PATH = X, Y, Z;
CALL P4;
SET CURRENT PACKAGE PATH = PATH Z, Y, X;
CALL P4;
```
同じプロシージャを複数回呼び出す場合 ：サーバーとリクエスト側がともに同じバージョンの Db2 の場合、アプリケーション内で同じネストレベルでストアドプロシージャを複数回呼び出すことができます。同じストアード・プロシージャーを呼び出すたびに、ストアード・プロシージャーの固有のインスタンスが実行されます。ストアード・プロシージャーが結果セットを戻す場合、ストアード・プロシージャーの各インスタンスは結果セット・カーソルのセットを個別にオープンします。この状況の詳細については、「同じストアドプロシージャへの複数の呼び出し」を参照してください。
アプリケーション内でプロシージャーを複数回呼び出すときに、異なるインスタンスからの結果セットを同時に処理する必要がある場合は、プロシージャーのそれぞれの呼び出しから戻されたロケーター値を取り込むために、それぞれの CALL ステートメントの後で必ず ASSOCIATE LOCATORS ステートメントを使用してください。例えば、プロシージャー P がコレクション Z に存在し、アプリケーションが CALL ステートメントを 2 回使用してプロシージャー P を呼び出すとします。最初の CALL ステートメントにあるプロシージャーのコレクションの判別には PACKAGE PATH が使用され、2 番目の CALL ステートメント内ではコレクションが明示的に指定されています。最初の CALL ステートメントによって作成された結果セットのロケーターが、プロシージャーの 2 回目の呼び出しより前に ASSOCIATE LOCATOR ステートメントによって取り込まれていれば、アプリケーションは両方の CALL ステートメントの後で両プロシージャーからの結果セットにアクセスできます。
```
SET CURRENT PACKAGE PATH = X, Y, Z;
CALL P3;
ASSOCIATE LOCATORS ...
CALL Z.P3;
ASSOCIATE LOCATORS ...
-- process the result sets using the locators
```

ホスト変数の使用: ASSOCIATE LOCATORS ステートメントにホスト変数が含まれている場合には、次の条件が適用されます。

ステートメントが静的に実行される場合、ホスト変数の内容は、ステートメントが含まれているパッケージまたはプランのバインド時に ENCODING パラメーターに指定されていたコード化スキームであると見なされます。
ステートメントが動的に実行される場合には、ホスト変数の内容は、APPLICATION ENCODING バインド・オプションに指定されているコード化スキームであると見なされます。

例 ASSOCIATE LOCATORS

以下の例のステートメントは、PL/I プログラムを前提としています。

例 1: 結果セット・ロケーター変数 LOC1 と LOC2 を使用して、ストアード・プロシージャー P1 が戻す 2 つの結果セット用の結果セット・ロケーター値を獲得します。ストアード・プロシージャーは、現行サーバー SITE2 から 1 部構成の名前によって呼び出されたとします。

   EXEC SQL CONNECT TO SITE2;
   EXEC SQL CALL P1;
   EXEC SQL ASSOCIATE RESULT SET LOCATORS (:LOC1, :LOC2)
            WITH PROCEDURE P1;

例 2: 例 1 のシナリオを繰り返しますが、スキーマ MYSCHEMA 内のストアード・プロシージャー P1 が確実に使用されるように、 2 部構成の名前を使用して、ストアード・プロシージャーの明示的スキーマ名を指定します。

   EXEC SQL CONNECT TO SITE2;
   EXEC SQL CALL MYSCHEMA.P1;
   EXEC SQL ASSOCIATE RESULT SET LOCATORS (:LOC1, :LOC2)
            WITH PROCEDURE MYSCHEMA.P1;

例 3: 結果セット・ロケーター変数 LOC1 と LOC2 を使用して、ストアード・プロシージャー (ホスト変数名 HV1) が戻す 2 つの結果セット用の結果セット・ロケーター値を獲得します。ホスト変数 HV1 に値 SITE2.MYSCHEMA.P1 が含まれていて、ストアード・プロシージャーを 3 部構成の名前を使用して呼び出すとします。

   EXEC SQL CALL SITE2.MYSCHEMA.P1;
   EXEC SQL ASSOCIATE LOCATORS (:LOC1, :LOC2)
            WITH PROCEDURE :HV1;

ホスト変数 HV1 に 2 部構成の名前である値 MYSCHEMA.P1 が含まれている場合、上記の例は無効になります。ホスト変数 HV1 に 2 部構成の名前がある場合に、上記の例を有効にするには、以下のステートメントに示したように、現行サーバーが、CALL ステートメントに指定されているロケーション名と同じでなければなりません。これは、名前を同じ方法で指定する必要がなく、CALL ステートメント上の 3 部構成の名前を、ASSOCIATE LOCATORS ステートメント上の 2 部構成の名前とともに使用できる唯一の条件です。

   EXEC SQL CONNECT TO SITE2;
   EXEC SQL CALL SITE2.MYSCHEMA.P1;
   EXEC SQL ASSOCIATE LOCATORS (:LOC1, :LOC2)
            WITH PROCEDURE :HV1;