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 函数。

对于 index 参数，允许使用以下值：

DB_CALLBACK_DEBUG_MESSAGE 对每条调试信息都要调用一次提供的函数，而且会有一个包含该调试信息文本的以空值终止的字符串传递给该函数。调试消息是记录到 LogFile 文件的消息。为了将调试消息传递给此回调函数，必须使用 LogFile 连接参数。该字符串通常在紧邻终止的空字符之前有一个换行符 (\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 字段指定消息的长度。消息不是以空值终止的。

例如，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，否则返回非零值。

为确保数据安全，服务器会跟踪请求文件传输的语句的源。服务器会确定语句是否是从客户端应用程序直接接收的。从客户端启动数据传输时，服务器会将语句源的相关信息发送到客户端软件。对于嵌入式 SQL 客户端库而言，仅当是由于执行客户端应用程序直接发送的语句而请求数据传输时，它才会允许无条件传输数据。否则，应用程序必须注册上文所述的校验回调函数，如果未注册该函数，则传输会被拒绝，而且语句失败并出现一个错误。请注意，如果客户端语句调用的某个存储过程在数据库中已经存在，则对该存储过程本身的执行不被视为是客户端启动的语句所完成的。但是，如果客户端应用程序显式地创建一个临时存储过程，则服务器会将对该存储过程的执行视为是由客户端启动的。同样，如果客户端应用程序执行一个批处理语句，则该批处理语句的执行被视为是直接由客户端应用程序完成的。