To configure and start dbmlsync using the DBTools interface in C or C++

1. Include the DBTools header file.

   The DBTools header file, dbtools.h, lists the entry points to the DBTools library and defines required data types.

   #include "dbtools.h"

2. Start the DBTools interface.

   • Declare and initialize the a_dbtools_info structure.

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

     The dbsyncErrorCallBack function handles error messages and is defined in step 4 of this procedure.

   • Use the DBToolsInit function to initialize DBTools.

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

     For more information about DBTools initialization, see:

     • Using the database tools interface
     • a_dbtools_info structure
     • DBToolsInit function

3. Initialize the a_sync_db structure.

   • Declare an a_sync_db instance. For example, declare an instance called dbsync_info:

     a_sync_db dbsync_info;

   • Clear a_sync_db structure fields.

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

   • Set required a_sync_db fields.

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

   • Set the database connection string.

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

     For more information about database connection parameters, see -c option.

   • Set other a_sync_db fields to customize synchronization.

     Most fields correspond to dbmlsync command line options. For more information about this correspondence, see dbtools.h.

     In the example below, verbose operation is enabled.

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

   For more information about a_sync_db fields, see a_sync_db structure.

4. Create callback functions to receive feedback during synchronization and assign these functions to the appropriate a_sync_db fields.

   The following functions use the standard output stream to display dbmlsync error, log, and progress information.

   For more information about DBTools callback functions, see Using callback functions.

   • For example, create a function called dbsyncErrorCallBack to handle generated error messages:

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

   • For example, create a function called dbsyncWarningCallBack to handle generated warning messages:

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

   • For example, create a function called dbsyncLogCallBack to receive verbose informational messages that you might choose to log to a file instead of displaying in a window:

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

   • For example, create a function called dbsyncMsgCallBack to receive informational messages generated during synchronization.

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

   • For example, create a function called dbsyncProgressMessageCallBack to receive the progress text. In the dbmlsync utility, this text is displayed directly above the progress bar.

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

   • For example, create a function called dbsyncProgressIndexCallBack to receive information for updating a progress indicator or progress bar. This function receives two parameters:

     • index   An integer representing the current progress of a synchronization.

     • max   The maximum progress value. If this value is zero, the maximum value has not changed since the last time the event was fired.

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

     A typical sequence of calls to this callback is shown below

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

     This sequence should result in the progress bar being set to 0% done, 25% done, 50% done, 75% done, and 100% done.

   • For example, create a function called dbsyncWindowTitleCallBack to receive status information. In the dbmlsync utility, this information is displayed in the title bar.

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

   • The dbsyncMsgQueueCallBack function is called when a delay or sleep is required. It must return one of the following values, which are defined in dllapi.h.

     • MSGQ_SLEEP_THROUGH   indicates that the routine slept for the requested number of milliseconds. In most cases this is the value you should return.

     • MSGQ_SHUTDOWN_REQUESTED   indicates that you would like the synchronization to terminate as soon as possible.

     • MSGQ_SYNC_REQUESTED   indicates that the routine slept for less than the requested number of milliseconds and that the next synchronization should begin immediately if a synchronization is not currently in progress.

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

   • Assign callback function pointers to the appropriate a_sync_db synchronization structure fields.

     // 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. Create a linked list of a_syncpub structures to specify which publications should be synchronized.

   Each node in the linked list corresponds to one instance of the -n option on the dbmlsync command line.

   • Declare an a_syncpub instance. For example, call it publication_info:

     a_syncpub publication_info;

   • Initialize a_syncpub fields, specifying publications you want to synchronize.

     For example, to identify the template_p1 and template_p2 publications together in a single synchronization session:

     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;

     This is equivalent to specifying -n template_p1,template_p2 on the dbmlsync command line.

     The associated script version specified using the ext_opt field, provides the same functionality as the dbmlsync -eu option.

     See -eu option.

   • Assign the publication structure to the upload_defs field of your a_sync_db instance.

     dbsync_info.upload_defs = &publication_info;

   You can create a linked list of a_syncpub structures. Each a_syncpub instance in the linked list is equivalent to one specification of the -n option on the dbmlsync command line.

   See -n option and a_syncpub structure.

6. Run dbmlsync using the DBSynchronizeLog function.

   In the following code listing, sync_ret_val contains the return value 0 for success or non-0 for failure.

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

   You can repeat step 6 multiple times with the same or different parameter values.

7. Shutdown the DBTools interface.

   The DBToolsFini function frees DBTools resources.

   DBToolsFini( &info );

   See DBToolsFini function.