db_register_a_callback 関数

プロトタイプ

void db_register_a_callback(
SQLCA * sqlca,
a_db_callback_index index,
( SQL_CALLBACK_PARM ) callback );

説明

この関数は、コールバック関数を登録します。

DB_CALLBACK_WAIT コールバックを登録しない場合は、デフォルトでは何もアクションを実行しません。アプリケーションはブロックして、データベースの応答を待ちます。MESSAGE TO CLIENT 文のコールバックを登録してください。MESSAGE 文を参照してください。

コールバックを削除するには、callback 関数として NULL ポインタを渡します。

index パラメータに指定できる値を次に示します。

DB_CALLBACK_DEBUG_MESSAGE 指定の関数がデバッグ・メッセージごとに 1 回呼び出され、デバッグ・メッセージのテキストを含む NULL で終了する文字列が渡されます。デバッグ・メッセージは、LogFile のファイルに記録されるメッセージです。デバッグ・メッセージをこのコールバックに渡すには、LogFile 接続パラメータを使用する必要があります。通常、この文字列の末尾の NULL 文字の直前に改行文字 (\n) が付いています。コールバック関数のプロトタイプを次に示します。
```
void SQL_CALLBACK debug_message_callback(
SQLCA * sqlca,
char * message_string );
```
詳細については、LogFile 接続パラメータ [LOG]を参照してください。
DB_CALLBACK_START プロトタイプを次に示します。
```
void SQL_CALLBACK start_callback( SQLCA * sqlca );
```
この関数は、データベース要求がサーバに送信される直前に呼び出されます。DB_CALLBACK_START は、Windows でのみ使用されます。
DB_CALLBACK_FINISH プロトタイプを次に示します。
```
void SQL_CALLBACK finish_callback( SQLCA * sqlca );
```
この関数は、データベース要求に対する応答をインタフェース DLL が受け取ったあとに呼び出されます。DB_CALLBACK_FINISH は、Windows オペレーティング・システムでのみ使用されます。
DB_CALLBACK_CONN_DROPPED プロトタイプを次に示します。
```
void SQL_CALLBACK conn_dropped_callback (
SQLCA * sqlca,
char * conn_name );
```
この関数は、DROP CONNECTION 文を通じた活性タイムアウトのため、またはデータベース・サーバがシャットダウンされているために、データベース・サーバが接続を切断しようとするときに呼び出されます。複数の接続を区別できるように、接続名 conn_name が渡されます。接続が無名の場合は、値が NULL になります。

DB_CALLBACK_WAIT プロトタイプを次に示します。

void SQL_CALLBACK wait_callback( SQLCA * sqlca );

この関数は、データベース・サーバまたはクライアント・ライブラリがデータベース要求を処理しているあいだ、インタフェース・ライブラリによって繰り返し呼び出されます。

このコールバックは次のように登録します。

db_register_a_callback( &sqlca,
   DB_CALLBACK_WAIT,
   (SQL_CALLBACK_PARM)&db_wait_request );

DB_CALLBACK_MESSAGE この関数は、要求の処理中にサーバから受け取ったメッセージをアプリケーションが処理できるようにするために使用します。
コールバック・プロトタイプを次に示します。
```
void SQL_CALLBACK message_callback(
SQLCA * sqlca,
unsigned char msg_type,
an_sql_code code,
unsigned short length,
char *  msg
);
```
msg_type パラメータは、メッセージの重大度を示します。異なるメッセージ・タイプを異なる方法で処理する場合に使用できます。使用可能なメッセージ・タイプは、MESSAGE_TYPE_INFO、MESSAGE_TYPE_WARNING、MESSAGE_TYPE_ACTION、MESSAGE_TYPE_STATUS です。これらの定数は、sqldef.h で定義されています。code フィールドにはメッセージに関連付けられた SQLCODE を指定できます。それ以外の場合、値は 0 です。length フィールドはメッセージの長さを示します。メッセージは、NULL で終了しません。

たとえば、Interactive SQL のコールバックは STATUS と INFO メッセージを [メッセージ] タブに表示しますが、ACTION と WARNING メッセージはウィンドウに表示されます。アプリケーションがコールバックを登録しない場合は、デフォルトのコールバックが使用されます。これは、すべてのメッセージをサーバ・ログ・ファイルに書き込みます (デバッグがオンでログ・ファイルが指定されている場合)。さらに、メッセージ・タイプ MESSAGE_TYPE_WARNING と MESSAGE_TYPE_ACTION は、オペレーティング・システムに依存した方法で表示されます。

アプリケーションによってメッセージ・コールバックが登録されていない場合、クライアントに送信されたメッセージは LogFile 接続パラメータが指定された際にログ・ファイルに保存されます。また、クライアントに送信された ACTION または STATUS メッセージは、Windows オペレーティング・システムではウィンドウに表示され、UNIX オペレーティング・システムでは stderr に記録されます。
DB_CALLBACK_VALIDATE_FILE_TRANSFER これは、ファイル転送の検証コールバック関数を登録するために使用します。転送を許可する前に、クライアント・ライブラリは検証コールバックが存在している場合は、それを呼び出します。ストアド・プロシージャからなどの間接文の実行中にクライアントのデータ転送が要求された場合、クライアント・ライブラリはクライアント・アプリケーションで検証コールバックが登録されていないかぎり転送を許可しません。どのような状況で検証の呼び出しが行われるかについては、以下でより詳しく説明します。
コールバック・プロトタイプを次に示します。
```
int SQL_CALLBACK file_transfer_callback(
SQLCA * sqlca,
char * file_name,
int is_write
);
```
file_name パラメータは、読み込みまたは書き込み対象のファイルの名前です。is_write パラメータは、読み込み (クライアントからサーバへの転送) が要求された場合は 0、書き込みが要求された場合は 0 以外の値になります。ファイル転送が許可されない場合、コールバック関数は 0 を返します。それ以外の場合は 0 以外の値を返します。

データのセキュリティ上、サーバはファイル転送を要求している文の実行元を追跡します。サーバは、文がクライアント・アプリケーションから直接受信されたものかどうかを判断します。クライアントからデータ転送を開始する際に、サーバは文の実行元に関する情報をクライアント・ソフトウェアに送信します。クライアント側では、クライアント・アプリケーションから直接送信された文を実行するためにデータ転送が要求されている場合にかぎり、Embedded SQL クライアント・ライブラリはデータの転送を無条件で許可します。それ以外の場合は、上述の検証コールバックがアプリケーションで登録されていることが必要です。登録されていない場合、転送は拒否されて文が失敗し、エラーが発生します。データベース内に既存しているストアド・プロシージャがクライアントの文で呼び出された場合、ストアド・プロシージャそのものの実行はクライアントの文で開始されたものと見なされません。ただし、クライアント・アプリケーションでテンポラリ・ストアド・プロシージャを明示的に作成してストアド・プロシージャを実行した場合、そのプロシージャはクライアントによって開始されたものとしてサーバは処理します。同様に、クライアント・アプリケーションでバッチ文を実行する場合も、バッチ文はクライアント・アプリケーションによって直接実行されるものと見なされます。