Setting up the DBTools interface for dbmlsync

This section guides you through the basic steps for using the DBTools interface for dbmlsync.

For more information about the DBTools library, see Introduction to the database tools interface.

For more information about using import libraries for your development environment, see Using the database tools interface.

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

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"

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:

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.

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;

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.

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.

Shutdown the DBTools interface.
The DBToolsFini function frees DBTools resources.
DBToolsFini( &info );
See DBToolsFini function.

Discuss this page in DocCommentXchange.
Send feedback about this page using email.