Click here to view and discuss this page in DocCommentXchange. In the future, you will be sent there automatically.

SQL Anywhere 11.0.1 (日本語) » Mobile Link - クライアント管理 » Mobile Link 用 SQL Anywhere クライアント » dbmlsync の DBTools インタフェース

 

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

この項では、dbmlsync の DBTools インタフェースの基本的な使用手順を示します。

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

ご使用の開発環境でのインポート・ライブラリの使用についての詳細は、データベース・ツール・インタフェースの使い方を参照してください。

♦  C や C++ で作成された DBTtools インタフェースを使用して dbmlsync の設定と起動を行うには、次の手順に従います。
  1. DBTools ヘッダ・ファイルをインクルードします。

    DBTools ヘッダ・ファイル dbtools.h は、DBTools ライブラリのエントリ・ポイントをリストし、必要なデータ型を定義します。

    #include "dbtools.h"
  2. 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 の初期化の詳細については、次の項を参照してください。

  3. 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 構造体を参照してください。

  4. 同期中にフィードバックを受け取るコールバック関数を作成し、これらの関数を適切な 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 という関数を作成します。この関数は、次の 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;
  5. どのパブリケーションを同期するかを指定する a_syncpub 構造体のリンク・リストを作成します。

    リンク・リスト内の各ノードは、dbmlsync コマンド・ライン上の -n オプションの 1 つのインスタンスに対応します。

    • 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 オプションの 1 つの定義に相当します。

    -n オプションa_syncpub 構造体を参照してください。

  6. 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 は、同じパラメータ値または異なるパラメータ値を指定して複数回繰り返すことができます。

  7. DBTools インタフェースをシャットダウンします。

    DBToolsFini 関数は、DBTools リソースを開放します。

    DBToolsFini( &info );

    DBToolsFini 関数を参照してください。