アプリケーション開発の手引き

DB2DARI ストアード・プロシージャー

DB2DARI ストアード・プロシージャーは、呼び出されると、以下の機能を実行します。

  1. クライアント・アプリケーションから SQLDA データ構造を受け取る。 (ホスト変数は、SQL CALL ステートメントが実行されたときにデータベース・マネージャーが生成した SQLDA データ構造を介して渡されます。)
  2. クライアント・アプリケーションと同じトランザクションの下で、データベース・サーバー上で実行する。
  3. SQLCA 情報と任意指定の出力データを、クライアント・アプリケーションに戻す。

クライアント・アプリケーションでの SQLDA の使用

ストアード・プロシージャーを呼び出す前に、使用される SQLDA 構造ごとに以下のステップを実行してください。

  1. 要求される基本 SQLVAR 要素数を指定して、構造に記憶域を割り振る。
  2. SQLN フィールドを、割り振られる SQLVAR 要素の数に設定する。
  3. SQLD フィールドを、実際に使用される SQLVAR 要素の数に設定する。
  4. 以下のようにして、使用される各 SQLVAR 要素を初期化する。

アプリケーションが FOR BIT DATA として定義されている文字ストリングを使用して作動する場合は、 SQLDAID フィールドを初期化して、 FOR BIT DATA 定義および FOR BIT DATA 要素を定義する各 SQLVAR の SQLNAME フィールドを SQLDA に含めるように指示する必要があります。

アプリケーションが大きなオブジェクトで作動する場合、すなわち CLOB、BLOB、DBCLOB などのタイプのデータで作動する場合、 SQLVAR の第 2 要素も初期化する必要があります。 SQLDA 構造の詳細については、 SQL 解説書 を参照してください。

DB2DARI クライアントにおけるホスト変数の使用

SQLVAR を宣言するには、ホスト変数の割り振りで説明されているのと同じ方法を使います。さらに、クライアント・アプリケーションは、出力専用 SQLVAR の標識を データ構造の操作で説明されているように -1 に設定しなければなりません。これにより、SQLDATA ポインターの内容ではなく標識のみが送られるので、パラメーターを渡す機構のパフォーマンスが向上します。 SQLTYPE フィールドは、これらのパラメーター用のヌル値可データ・タイプに設定しなければなりません。 SQLTYPE がヌル値不可のデータ・タイプである場合、データベース・マネージャーは標識変数を検査しません。

ストアード・プロシージャーにおける SQLDA の使用

ストアード・プロシージャーは、SQL CALL ステートメントにより呼び出され、クライアント・アプリケーションによって渡されたデータを使用して実行されます。情報は、ストアード・プロシージャーの SQLDA 構造を使用して、クライアント・アプリケーションに戻されます。

SQL CALL ステートメントのパラメーターは、入出力両方のパラメーターとして扱われ、ストアード・プロシージャーのために以下の形式に変換されます。

     SQL_API_RC SQL_API_FN proc_name( void *reserved1,
                                      void *reserved2,
                                      struct sqlda *inoutsqlda, 
                                      struct sqlca *sqlca )

SQL_API_FN は、サポートされるオペレーティング・システムごとに異なる関数の呼び出し規則を指定するマクロです。このマクロは、ストアード・プロシージャーや UDF を作成する場合に必要です。

以下に、CALL ステートメントによるサーバーのパラメーター・リストへのマップ方法の例を示します。

     CALL OUTSRV (:empno:empind,:salary:salind)

この呼び出しに対するパラメーターは、SQLVAR を 2 つ持つ SQLDA 構造に変換されます。最初の SQLVAR は、empno ホスト変数および empind 標識変数を指します。 2 番目の SQLVAR は、salary ホスト変数および salind 標識変数を指します。
注:SQLDA 構造は、その要素の数である SQLD が 0 に設定されている場合は、ストアード・プロシージャーに渡されない。この場合、SQLDA が渡されないと、ストアード・プロシージャーは NULL ポインターを受け取ります。

データ構造の操作

データベース・マネージャーは、重複した SQLDA 構造を自動的にデータベース・サーバーに割り振ります。ネットワーク通信量を低減するために重要なのは、入力専用および出力専用のホスト変数をそれぞれ指示することです。クライアントのプロシージャーは、出力専用 SQLVAR の標識を -1 に設定しなければなりません。サーバーのプロシージャーは、入力専用 SQLVAR の標識を -128 に設定しなければなりません。これにより、データベース・マネージャーは、渡される SQLVAR を選択できるようになります。

なお、クライアントまたはサーバーが (SQLVAR を渡さないと指示して) 標識変数を負の値に設定した場合、それはリセットされません。ストアード・プロシージャーまたはクライアント・コードで SQLVAR が参照するホスト変数に値を与える場合、その標識変数は、値が渡されるようにゼロまたは正の値に設定しなければなりません。たとえば、1 つの出力専用パラメーターを取り、以下のように呼び出されるストアード・プロシージャーを例に考えてみます。

     empind = -1; 
     EXEC SQL CALL storproc(:empno:empind);

ストアード・プロシージャーは、最初の SQLVAR に値を設定する際に標識の値を負ではない値に設定するため、結果は empno に戻されます。

データ構造使用法の要約

表 53 には、ストアード・プロシージャーのアプリケーションによるさまざまな構造フィールドの使用法が要約されています。その表の中で、sqlda とはストアード・プロシージャーに渡される SQLDA 構造のことで、 n とは SQLDA の特定の SQLVAR 要素を示す数値です。右側の数字は、表の後の注番号を示します。


表 53. ストアード・プロシージャーのパラメーター変数
入出力 SQLDA sqlda.SQLDAID


4





sqlda.SQLDABC


4





sqlda.SQLN
2
4





sqlda.SQLD
2 3
5



入出力 SQLVAR sqlda.n.SQLTYPE
2 3
5




sqlda.n.SQLLEN
2 3
5




sqlda.n.SQLDATA 1 2 3

6
8

sqlda.n.SQLIND 1 2 3

6
8 9

sqlda.n.SQLNAME.length




6 7


sqlda.n.SQLNAME.data




6 7


sqlda.n.SQLDATATYPE_NAME
2 3
5




sqlda.n.SQLLONGLEN
2 3
5




sqlda.n.SQLDATALEN 1 2 3

6 7

SQLCA (全要素)





6 7

注:

    ストアード・プロシージャーを呼び出す前に、クライアント・アプリケーションは次のことを行う必要があります。

  1. SQLTYPE および SQLLEN に基づいてポインター要素のための記憶域を割り振る。
  2. 適切なデータを使って要素を初期化する。

    アプリケーションによって呼び出されると、データベース・マネージャーは次のことを行います。

  3. 元の要素中のデータを、ストアード・プロシージャーで割り振られている重複要素に送る。 SQLN 要素は、SQLD 要素中のデータで初期化されます。

    呼び出しの際、ストアード・プロシージャーは次のことを行えます。

  4. 重複要素中のデータを変える。データは、妥当性検査をされたりクライアント・アプリケーションに戻されたりしないので、必要に応じて変更することができる。

    ストアード・プロシージャーが終了すると、データベース・マネージャーは次のことを行います。

  5. 重複要素中のデータを検査する。そのフィールド内の値が元の要素中のデータと一致していないと、エラーが戻されます。
  6. 重複要素中のデータを元の要素に戻す。
  7. データは、妥当性検査をされないので、必要に応じて変更することができる。
  8. 要素により指示されたデータは、妥当性検査をされたりクライアント・アプリケーションに戻されたりしないので、必要に応じて変更することができる。
  9. SQLIND フィールドは、列のタイプがヌル値可でないことを SQLTYPE が示す場合は受け渡しされない。

入出力 SQLDA および SQLCA 構造

ストアード・プロシージャーは、 SQLDA 構造の入力変数に渡されたすべての情報を使用して実行されます。情報は、SQLDA の出力変数でクライアントに戻されます。 SQLDA の SQLD、SQLTYPE、および SQLLEN フィールドは、データが戻される前にクライアント・アプリケーションにより設定されている元の値と比較されるため、これらのフィールドの値は変更しないでください。これらが異なる場合は、以下の SQLCODE のうちいずれか 1 つが戻されます。

SQLCODE -1113 (SQLSTATE 39502)
変数のデータ・タイプ (SQLTYPE の値) が変更されました。
SQLCODE -1114 (SQLSTATE 39502)
変数の長さ (SQLLEN の値) が変更されました。
SQLCODE -1115 (SQLSTATE 39502)
SQLD フィールドが変更されました。

さらに、SQLDATA および SQLIND フィールドにより指定される値は変更可能ですが、これらのフィールドのポインターは変更しないでください。
注:同じ変数を入出力の両方に使用することができます。

SQLCA 情報は、ストアード・プロシージャーが戻る前にストアード・プロシージャーの SQLCA パラメーターに明示的に複写しなければなりません。

DB2DARI ストアード・プロシージャーの戻り値

ストアード・プロシージャーの戻り値は、クライアント・アプリケーションに戻されることはありません。データベース・マネージャーは、終了時にメモリーから解放するかどうかを判別するのに戻り値を使用します。

ストアード・プロシージャーは、以下のいずれかの値を戻します。

SQLZ_DISCONNECT_PROC
ライブラリーを解放 (アンロード) するようにデータベース・マネージャーに指示します。

SQLZ_HOLD_PROC
サーバー・ライブラリーをメイン・メモリーに保持するようデータベース・マネージャーに指示し、ライブラリーがストアード・プロシージャーの次の呼び出し時に使用できるようにします。これによりパフォーマンスが向上します。

ストアード・プロシージャーが 1 度だけ呼び出される場合は、 SQLZ_DISCONNECT_PROC が戻されます。

クライアント・アプリケーションが、同じストアード・プロシージャーを呼び出すために複数の呼び出しを行った場合には、 SQLZ_HOLD_PROC がストアード・プロシージャーの戻り値にならなければなりません。ストアード・プロシージャーは、アンロードされません。

SQLZ_HOLD_PROC が使用される場合、最後のストアード・プロシージャー呼び出し要求は、メイン・メモリーからストアード・プロシージャー・ライブラリーを解放するために、 SQLZ_DISCONNECT_PROC という値を戻さなければなりません。戻されないと、ライブラリーはデータベース・マネージャーが停止するまでメイン・メモリーに残ります。ストアード・プロシージャーに対する警告として、クライアント・アプリケーションは、パラメーターの 1 つに最後の呼び出しを示すフラグを入れて渡すことがあります。


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]