设置 dbmlsync 的 DBTools 接口

本节指导您使用 dbmlsync 的 DBTools 接口的基本步骤。

有关 DBTools 库的详细信息，请参见数据库工具接口简介。

有关使用开发环境的导入库的详细信息，请参见使用数据库工具接口。

♦ 使用 DBTools 接口以 C 或 C++ 配置和启动 dbmlsync

包括 DBTools 头文件。

DBTools 头文件 dbtools.h 列出了 DBTools 库的入口点并定义了需要的数据类型。
#include "dbtools.h"

启动 DBTools 接口。

声明并初始化 a_dbtools_info 结构。

a_dbtools_info   info;
short ret;
...
// clear a_dbtools_info fields
memset( &info, 0, sizeof( info ) ); 
info.errorrtn = dbsyncErrorCallBack;

dbsyncErrorCallBack 函数用于处理错误消息，在此过程的第 4 步中进行定义。

使用 DBToolsInit 函数初始化 DBTools。

ret = DBToolsInit( &info );
if( ret != 0 ) {
 printf("dbtools initialization failure \n");
}

有关 DBTools 初始化的详细信息，请参见：

初始化 a_sync_db 结构。

声明一个 a_sync_db 实例。例如，声明一个名为 dbsync_info 的实例：
a_sync_db dbsync_info;

清除 a_sync_db 结构字段。

memset( &dbsync_info, 0, sizeof( dbsync_info ) );

设置需要的 a_sync_db 字段。

dbsync_info.version = DB_TOOLS_VERSION_NUMBER;
dbsync_info.output_to_mobile_link = 1;
dbsync_info.default_window_title 
  = "dbmlsync dbtools sample";

设置数据库连接字符串。

dbsync_info.connectparms = "uid=DBA;pwd=sql";

有关数据库连接参数的详细信息，请参见-c 选项。

设置其它 a_sync_db 字段以自定义同步。

多数字段都对应于 dbmlsync 命令行选项。有关此对应关系的详细关系，请参见 dbtools.h。

在下面的示例中，启用了详细操作。

dbsync_info.verbose_upload = 1;
dbsync_info.verbose_option_info = 1;
dbsync_info.verbose_row_data = 1;
dbsync_info.verbose_row_cnts = 1;

有关 a_sync_db 字段的详细信息，请参见a_sync_db 结构。

创建在同步过程中接收反馈的回调函数，并将这些函数指派给相应的 a_sync_db 字段。

以下函数使用标准输出流显示 dbmlsync 错误、日志和进度信息。

有关 DBTools 回调函数的详细信息，请参见使用回调函数。

例如，创建一个名为 dbsyncErrorCallBack 的函数来处理生成的错误消息：

extern short _callback dbsyncErrorCallBack( char *str )
{
    if( str != NULL ) {
        printf( "Error Msg    %s\n", str );
    }
    return 0;
}

例如，创建一个名为 dbsyncWarningCallBack 的函数来处理生成的警告消息：

extern short _callback dbsyncWarningCallBack( char *str )
{
    if( str != NULL ) {
        printf( "Warning Msg  %s\n", str );
    }
    return 0;
}

例如，创建一个名为 dbsyncLogCallBack 的函数来接收您可能希望记录到文件而不是显示在窗口中的详细的信息性消息：

extern short _callback dbsyncLogCallBack( char *str )
{
    if( str != NULL ) {
        printf( "Log Msg      %s\n", str );
    }
    return 0;
}

例如，创建一个名为 dbsyncMsgCallBack 的函数来接收同步过程中生成的信息性消息。

extern short _callback dbsyncMsgCallBack( char *str )
{
    if( str != NULL ) {
        printf( "Display Msg  %s\n", str );
    }
    return 0;
}

例如，创建一个名为 dbsyncProgressMessageCallBack 的函数来接收进度文本。在 dbmlsync 实用程序中，此文本直接显示在进度条上。

extern short _callback dbsyncProgressMessageCallBack(
 char *str )
{
    if( str != NULL ) {
        printf( "ProgressText %s\n", str );
    }
    return 0;
}

例如，创建一个名为 dbsyncProgressIndexCallBack 的函数来接收更新进度指示器或进度条的信息。此函数接收两个参数：

index 一个表示同步的当前进度的整数。
max 最大进度值。如果该值为 0，则自上次触发该事件后，最大值未曾更改。

extern short _callback dbsyncProgressIndexCallBack
(a_sql_uint32 index, a_sql_uint32 max )
{
    printf( "ProgressIndex    Index %d Max: %d\n",
         index, max );
    return 0;
}

对此回调函数的典型调用顺序显示如下

// example calling sequence
dbsyncProgressIndexCallBack( 0, 100 );
dbsyncProgressIndexCallBack( 25, 0 );
dbsyncProgressIndexCallBack( 50, 0 );
dbsyncProgressIndexCallBack( 75, 0 );
dbsyncProgressIndexCallBack( 100, 0 );

此顺序可使进度条被设置为已完成 0%、已完成 25%、已完成 50%、已完成 75% 和已完成 100%。

例如，创建一个名为 dbsyncWindowTitleCallBack 的函数来接收状态信息。在 dbmlsync 实用程序中，此信息显示在标题栏中。

extern short _callback dbsyncWindowTitleCallBack(
 char *title )
{
    printf( "Window Title     %s\n", title );
    return 0;
}

在需要延迟或休眠时调用 dbsyncMsgQueueCallBack 函数。它必须返回以下值之一，这些值在 dllapi.h 中定义。

MSGQ_SLEEP_THROUGH 表示例程休眠请求的毫秒数。多数情况下，这是应返回的值。
MSGQ_SHUTDOWN_REQUESTED 表示希望尽快终止同步。
MSGQ_SYNC_REQUESTED 表示例程休眠的时间少于请求的毫秒数，并且如果当前没有同步操作，应立即开始下一个同步。

extern short _callback dbsyncMsgQueueCallBack(
   a_sql_uint32 sleep_period_in_milliseconds )
{

 printf( "Sleep %d ms\n", sleep_period_in_milliseconds );
 Sleep( sleep_period_in_milliseconds );
 return MSGQ_SLEEP_THROUGH; 
}

将回调函数指针指派给相应的 a_sync_db 同步结构字段。

// set call back functions
dbsync_info.errorrtn    = dbsyncErrorCallBack;
dbsync_info.warningrtn  = dbsyncWarningCallBack;
dbsync_info.logrtn      = dbsyncLogCallBack;
dbsync_info.msgrtn      = dbsyncMsgCallBack;
dbsync_info.msgqueuertn = dbsyncMsgQueueCallBack;
dbsync_info.progress_index_rtn
     = dbsyncProgressIndexCallBack;
dbsync_info.progress_msg_rtn
     = dbsyncProgressMessageCallBack;
dbsync_info.set_window_title_rtn
     = dbsyncWindowTitleCallBack;

创建一个 a_syncpub 结构的链接列表以指定应同步哪些发布。

链接列表中的每个节点对应于 dbmlsync 命令行上的一个 -n 选项实例。

声明一个 a_syncpub 实例。例如，称其为 publication_info：
a_syncpub publication_info;

初始化 a_syncpub 字段，指定要同步的发布。

例如，在一个同步会话中同时标识 template_p1 和 template_p2 发布：

publication_info.next = NULL; // linked list terminates
publication_info.pub_name = "template_p1,template_p2";
publication_info.ext_opt  = "sv=template_ver1";
publication_info.alloced_by_dbsync = 0;

这等同于在 dbmlsync 命令行上指定 -n template_p1,template_p2。

使用 ext_opt 字段指定的关联脚本版本提供与 dbmlsync -eu 选项相同的功能。

请参见-eu 选项。

将发布结构指派给 a_sync_db 实例的 upload_defs 字段。

dbsync_info.upload_defs   = &publication_info;

可以创建一个 a_syncpub 结构的链接列表。链接列表中的每个 a_syncpub 实例都等同于 dbmlsync 命令行上 -n 选项的一个说明。

请参见-n 选项和a_syncpub 结构。

使用 DBSynchronizeLog 函数运行 dbmlsync。

在以下代码列表中，sync_ret_val 包含代表成功的返回值 0 或代表失败的返回值非 0。

short sync_ret_val;
printf("Running dbmlsync using dbtools interface...\n");
sync_ret_val = DBSynchronizeLog(&dbsync_info); 
printf("\n Done... synchronization return value is: %I \n", sync_ret_val);

可以使用相同或不同的参数值多次重复第 6 步。

关闭 DBTools 接口。
DBToolsFini 函数释放 DBTools 资源。
DBToolsFini( &info );
请参见DBToolsFini 函数。