2.9 コールバック機能の利用方法

Symfoware Server アプリケーション開発ガイド(埋込みSQL編) - FUJITSU -

目次索引

2.9 コールバック機能の利用方法

ここでは、コールバック機能の利用方法について説明します。

コールバック関数の概要
コールバック関数の登録方法

コールバック機能とは、アプリケーションでSQL文を実行するとき、あらかじめSQL文の種別に対して登録した関数を実行する機能です。コールバック機能を利用すると、SQL文の実行ログを採取したり、SQL文の実行を迂回することができます。また、コールバック関数にはSQL文の実行結果が通知されるため、デッドロックやコネクション切断などの特定のエラーが発生したSQL文の実行ログを採取することも可能になります。

■コールバック関数の概要

コールバック機能を利用する場合は、コールバック関数とよばれる利用者定義関数を作成し、SQL文の種別ごとに登録します。これにより、アプリケーションでSQL文が実行されるたびに、登録されたコールバック関数が実行されます。

コールバック関数にはセションID（マルチスレッド環境で動作するアプリケーションの場合）、SQL文、実行結果および入出力データが通知されるため、利用者は必要に応じてデータを加工してください。

◆コールバック関数

コールバック関数は、利用者が作成する関数です。関数名は利用者によって任意に指定できますが、復帰値や関数のパラメタは規定されています。

コールバック関数は、SQL文の処理の直前か直後かによって、入口コールバック関数または出口コールバック関数と呼ばれます。入口コールバックまたは出口コールバックは、コールバック関数の登録時に指定します。

入口コールバック関数は、復帰値によってその後の動作が異なります。入口コールバック関数がSQLRDB_CONTINUEを返した場合は、SQL文の処理を実行します。しかし、SQLRDB_NOCONTINUEを返した場合はSQL文の処理は実行されず、出口コールバック関数が実行されます。入口コールバック関数でエラーが発生した場合などSQL文の処理を実行したくない場合は、SQLRDB_NOCONTINUEを返してください。

出口コールバック関数には、SQL文の実行結果としてSQLSTATEおよびSQLMSGが通知されます。エラーが発生したSQL文の実行ログを採取する場合は、SQLSTATEおよびSQLMSGの情報を使用してください。ただし、アプリケーションでホスト変数SQLMSGが定義されていない場合は、SQLMSGは通知されません。また、入口コールバック関数には、SQLSTATEおよびSQLMSGは通知されません。

アプリケーションとデータを共有するため、コールバック関数に対し利用者定義領域のアドレスを設定することができます。コールバック関数の結果をアプリケーションに通知するには、利用者定義領域を使用してください。利用者定義領域のアドレスは、コールバック関数の登録時に指定します。

■コールバック関数の登録方法

アプリケーションにコールバック関数を登録する方法には以下があります。

アプリケーションのソースに記述する方法
動的ライブラリを使用して登録する方法

SQL文を実行する場面に合わせて、個別の処理が必要なコールバック関数の場合は、アプリケーションのプログラムソースに記述する方法で登録します。コールバック関数を登録するには、アプリケーションの修正およびコンパイルが必要になります。

アプリケーションの全体を通して、汎用的な処理を行うコールバック関数の場合は、動的ライブラリを使用する方法で登録します。アプリケーションの修正は必要ありません。

◆アプリケーションのソースに記述する方法

コールバック関数を静的に登録するには、アプリケーション中にSQLSetCallback関数を記述します。登録は各SQL文の種別ごとに行うため、登録するSQL文種別の数だけSQLSetCallback関数を実行します。また、複数のSQL文種別に対し同一のコールバック関数を登録する場合は、登録するSQL文種別のリストをSQLSetCallback関数に指定することで、一括して登録することができます。

SQLSetCallback関数はアプリケーション中のどこでも記述することができますが、コールバック関数を実行したいSQL文より前に記述する必要があります。

一度登録したSQL文種別に対し再度コールバック関数を登録すると、コールバック関数を変更することができます。また、登録したコールバック関数を解除したい場合は、SQLSetCallback関数の関数アドレスを指定するパラメタにNULLを指定してください。コールバック関数の変更および解除は、アプリケーション中のどの位置でも可能です。

マルチスレッド環境で動作するアプリケーションの場合、コールバック関数はセションごとにSQL文種別に登録されます。そのため、SQLSetCallback関数のパラメタにはコールバック関数を登録するセションIDを指定してください。また、SQLSetCallback関数を実行できるのは、SQLThrAllocID関数によるセション作成後になります。

コールバック関数を登録するSQL文の種別は、リストの形式で指定します。リストはshort型の配列変数の各要素に、登録したいSQL文の種別を設定して作成します。また、0が設定されている要素までをリストとみなすため、リストの最後には必ず0を設定してください。これは1種類のSQL文に対し登録する場合でも同様に設定する必要があります。

一度に設定できるSQL文の種別に制限はありません。また、重複して指定された場合もエラーにはなりません。

一度に複数のSQL文種別に対し登録した場合でも、再登録や解除は、個々または別の組合せで行うことが可能です。

例

/* INSERT文、UPDATE文にコールバック関数を登録する場合 */
SQLRETURN CallbackSQL1( ・・・ );
SQLRETURN CallbackSQL2( ・・・ );
SQLRETURN CallbackSQL3( ・・・ );
                                ・
                                ・
short       list[3];
                                ・
                                ・
/* 一括して登録する場合 */
list[0] = SQLRDB_CF_INSERT;
list[1] = SQLRDB_CF_UPDATE;
list[2] = 0;
SQLSetCallback( 0, CallbackSQL1, NULL, list, RDB_CALL_IN );
                                ・
/* 個別に登録する場合 */
list[0] = SQLRDB_CF_INSERT;
list[1] = 0;
SQLSetCallback( 0, CallbackSQL2, NULL, list, RDB_CALL_IN );
list[0] = SQLRDB_CF_UPDATE;
list[1] = 0;
SQLSetCallback( 0, CallbackSQL3, NULL, list, RDB_CALL_IN );
                                ・
                                ・

各SQL文の種別に対し現在コールバック関数が登録されているかどうかは、SQLGetCallback関数を使用することで取得できます。SQLGetCallback関数は、コールバック関数が登録されている場合はSQLRDB_ENTRYを返し、登録されていない場合はSQLRDB_NOENTRYを返します。

◆動的ライブラリを使用して登録する方法

コールバック関数を動的に登録するためには、SQLDynSetCallback関数を含む登録用の動的ライブラリを作成します。動的ライブラリには、以下のSymfoware/RDBのライブラリをリンクしてください。

32ビットで実行するアプリケーション：

libsqldrv.soをリンクします。また、マルチスレッド環境で動作するアプリケーションの場合は、libsqldrvm.soをリンクしてください。

64ビットで実行するアプリケーション：

libsql64drv.soをリンクします。また、マルチスレッド環境で動作するアプリケーションの場合は、libsql64drvm.soをリンクしてください。

32ビットで実行するアプリケーション：

f3cwdrv.libをリンクします。また、マルチスレッド環境で動作するアプリケーションの場合は、f3cwdrvm.libをリンクしてください。

Windows Server(R) 2003 for Itaniumにおいて、64ビットで実行するアプリケーション：

f3cwdrv_ia64.libをリンクします。また、マルチスレッド環境で動作するアプリケーションの場合は、f3cwdrvm_ia64.libをリンクしてください。

Windows Server(R) 2003 x64 Editionsにおいて、64ビットで実行するアプリケーション：

f3cwdrv_x64.libをリンクします。また、マルチスレッド環境で動作するアプリケーションの場合は、f3cwdrvm_x64.libをリンクしてください。

SQLDynSetCallback関数は利用者が作成する関数ですが、関数名、復帰値およびパラメタは規定されています。利用者はこの関数内で、SQLSetCallback関数を使用してコールバック関数を登録します。

SQLDynSetCallback関数が正常終了する場合は、復帰値としてSQLRDB_NORMALを返してください。しかし、エラーなどで関数が異常終了する場合は、SQLRDB_NORMAL以外を返却してください。

SQLDynSetCallback関数がエラーを返すとコールバック関数を利用するアプリケーションに以下のエラーが返ります。

マルチスレッド環境で動作するアプリケーションの場合は、SQLThrAllocID関数でエラー復帰します。
シングルスレッド環境で動作するアプリケーションの場合は、SQLDynSetCallback関数が実行されたSQL文の実行結果としてSQLSTATEに74600を設定しエラー復帰します。またアプリケーションにホスト変数SQLMSGが定義されている場合は、返却された値を埋め込んだ以下のエラーメッセージを出力します。
SQLMSG JYP1085E：コールバック関数の登録処理でエラーが発生しました．詳細種別=“@1@”

動的ライブラリは、環境変数RDBSETCALLBACKまたはクライアント用の動作環境ファイルのSET_CALLBACKパラメタに指定します。環境変数RDBSETCALLBACKは、アプリケーションを実行する前に指定してください。

Cシェルで設定する場合
setenv RDBSETCALLBACK ライブラリ名

bash、Bシェル、Kシェルで設定する場合
RDBSETCALLBACK=ライブラリ名;export RDBSETCALLBACK

set RDBSETCALLBACK=ライブラリ名

[動作環境ファイルのパラメタの指定]

SET_CALLBACK = (ライブラリ名)

環境変数または動作環境ファイルに設定するライブラリ名が絶対パスでの指定でない場合は、以下のディレクトリにライブラリを格納する必要があります。

環境変数LD_LIBRARY_PATHに指定したディレクトリ

PATHに指定したディレクトリ

環境変数RDBSETCALLBACKと動作環境ファイルのパラメタSET_CALLBACKの両方が指定された場合、環境変数RDBSETCALLBACKに指定された値が有効になります。

アプリケーションが実行されると、プロセス内で最初に実行されるSQL文の処理において、環境変数およびクライアント用の動作環境ファイルがチェックされ、動的ライブラリ内のSQLDynSetCallback関数が実行されます。なお、プロセス内の最初のSQL文に対しコールバック関数が指定されている場合もコールバック関数は実行されます。

なお、マルチスレッド環境で動作するアプリケーションの場合、SQLDynSetCallback関数はSQLThrAllocID関数の処理で実行されます。

目次索引