sqlca   SQLCA 構造体へのポインタ。

index   後述するように、コールバックのタイプを特定するインデックス値。

callback   ユーザ定義コールバック関数のアドレス。

DB_CALLBACK_DEBUG_MESSAGE   指定の関数がデバッグメッセージごとに 1 回呼び出され、デバッグメッセージのテキストを含む NULL で終了する文字列が渡されます。デバッグメッセージは、LogFile のファイルに記録されるメッセージです。デバッグメッセージをこのコールバックに渡すには、LogFile 接続パラメータを使用する必要があります。通常、この文字列の末尾の NULL 文字の直前に改行文字 (\n) が付いています。コールバック関数のプロトタイプを次に示します。

void SQL_CALLBACK debug_message_callback(
SQLCA * sqlca,
char * message_string );

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

void SQL_CALLBACK start_callback( SQLCA * sqlca );

この関数は、データベース要求がサーバに送信される直前に呼び出されます。DB_CALLBACK_START は、Windows でのみ使用されます。

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

void SQL_CALLBACK finish_callback( SQLCA * sqlca );

この関数は、データベース要求に対する応答を DBLIB インタフェース 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   この関数は、要求の処理中にサーバから受け取ったメッセージをアプリケーションが処理できるようにするために使用します。メッセージは、SQL MESSAGE 文を使用してクライアントアプリケーションからデータベースサーバに送信できます。実行時間が長いデータベースサーバ文によってメッセージも生成できます。

コールバックプロトタイプを次に示します。

void SQL_CALLBACK message_callback(
SQLCA * sqlca,
unsigned char msg_type,
an_sql_code code,
unsigned short length,
char *  msg
);

msg_type パラメータは、メッセージの重大度を示します。異なるメッセージタイプを異なる方法で処理できます。msg_type に指定できる次の値は、sqldef.h で定義されています。

code フィールドにはメッセージに関連付けられた SQLCODE を指定できます。それ以外の場合、値は 0 です。length フィールドはメッセージの長さを示します。メッセージは、NULL で終了しません。SQL Anywhere DBLIB および ODBC クライアントは、DB_CALLBACK_MESSAGE パラメータを使用して、進行メッセージを取得します。

たとえば、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 クライアントライブラリはデータの転送を無条件で許可します。それ以外の場合は、上述の検証コールバックがアプリケーションで登録されていることが必要です。登録されていない場合、転送は拒否されて文が失敗し、エラーが発生します。データベース内に既存しているストアドプロシージャがクライアントの文で呼び出された場合、ストアドプロシージャそのものの実行はクライアントの文で開始されたものと見なされません。ただし、クライアントアプリケーションでテンポラリストアドプロシージャを明示的に作成してストアドプロシージャを実行した場合、そのプロシージャはクライアントによって開始されたものとしてサーバは処理します。同様に、クライアントアプリケーションでバッチ文を実行する場合も、バッチ文はクライアントアプリケーションによって直接実行されるものと見なされます。