dbmlsync の DBTools インタフェースの設定

この項では、C または C++ の DBTools インタフェースを使用することによって dbmlsync を設定し開始する基本的な手順を説明します。

前提条件

この作業を実行するための前提条件はありません。

内容と備考

DBTools ライブラリの詳細については、データベースツールインタフェース (DBTools)を参照してください。

ご使用の開発環境でのインポートライブラリの使用の詳細については、DBTools インポートライブラリを参照してください。

♦ タスク

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";

同期をカスタマイズするための他の a_sync_db のフィールドを設定します。

ほとんどのフィールドは、dbmlsync コマンドラインオプションに対応しています。

次の例では、冗長オペレーションが指定されています。

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 のフィールドに割り当てます。

次の関数は、標準出力ストリームを使用して dbmlsync のエラー、ログ、進行状況情報を表示します。

たとえば、生成されたエラーメッセージを処理する 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 という関数を作成します。この関数は、次の 2 つのパラメータを受け取ります。

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 コマンドライン上の -s オプションの 1 つのインスタンスに対応します。

a_syncpub インスタンスを宣言します。たとえば、これを publication_info とします。

a_syncpub publication_info;

a_syncpub フィールドを初期化し、同期するサブスクリプションを指定します。

たとえば、単一の同期セッションで template_p1 サブスクリプションと template_p2 サブスクリプションをまとめて同期するには、次のように指定します。

publication_info.next = NULL; // linked list terminates
publication_info.subscription = "template_p1,template_p2";
publication_info.ext_opt  = "dir=c:\\logs";
publication_info.alloced_by_dbsync = 0;
publication_info.pub_name = NULL;

これは、dbmlsync コマンドラインで -s template_p1,template_p2 と指定するのと同じです。

ext_opt フィールドを使用して拡張オプションを指定すると、dbmlsync -eu オプションと同じ機能が提供されます。

a_sync_db インスタンスの upload_defs フィールドにパブリケーション構造体を割り当てます。

dbsync_info.upload_defs   = &publication_info;

a_syncpub 構造体のリンクリストを作成できます。リンクリスト内の各 a_syncpub インスタンスは、dbmlsync コマンドライン上の -n または -s オプションの 1 つの定義に相当します。

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( &info );
DBToolsFini 関数は、DBTools リソースを解放します。

結果

dbmlsync が設定され、開始されます。

参照

DocCommentXchange で意見交換できます