UltraLite Embedded SQL User's Guide
Adding Non Data Access Features to UltraLite Applications
Adding synchronization to your application
Monitoring and canceling synchronization
The callback function that monitors synchronization takes a ul_synch_status structure as parameter.
The ul_synch_status structure has the following members:
ul_synch_state state;
ul_u_short tableCount;
ul_u_short tableIndex;
struct {
ul_u_long bytes;
ul_u_short inserts;
ul_u_short updates;
ul_u_short deletes;
} sent;
struct {
ul_u_long bytes;
ul_u_short inserts;
ul_u_short updates;
ul_u_short deletes;
} received;
p_ul_synch_info info;
ul_bool stop;
state One of the following states:
UL_SYNCH_STATE_STARTING No synchronization actions have yet been taken.
UL_SYNCH_STATE_CONNECTING The synchronization stream has been built, but not yet opened.
UL_SYNCH_STATE_SENDING_HEADER The synchronization stream has been opened, and the header is about to be sent.
UL_SYNCH_STATE_SENDING_TABLE A table is being sent.
UL_SYNCH_STATE_SENDING_DATA Schema information or data is being sent.
UL_SYNCH_STATE_FINISHING_UPLOAD The upload stage is completed and a commit is being carried out.
UL_SYNCH_STATE_RECEIVING_UPLOAD_ACK An acknowledgement that the upload is complete is being received.
UL_SYNCH_STATE_RECEIVING_TABLE A table is being received.
UL_SYNCH_STATE_SENDING_DATA Schema information or data is being received.
UL_SYNCH_STATE_COMMITTING_DOWNLOAD The download stage is completed and a commit is being carried out.
UL_SYNCH_STATE_SENDING_DOWNLOAD_ACK An acknowledgement that download is complete is being sent.
UL_SYNCH_STATE_DISCONNECTING The synchronization stream is about to be closed.
UL_SYNCH_STATE_DONE Synchronization has completed successfully.
UL_SYNCH_STATE_ERROR Synchronization has completed, but with an error.
For a description of the synchronization process, see The synchronization process.
tableCount Returns the number of tables being synchronized. For each table there is a sending and receiving phase, so this number may be more than the number of tables being synchronized.
tableIndex The current table which is being uploaded or downloaded, starting at 0. This number may skip values when not all tables are being synchronized.
info A pointer to the ul_synch_info structure.
sent.inserts The number of inserted rows that have been uploaded so far.
sent.updates The number of updated rows that have been uploaded so far.
sent.deletes The number of deleted rows that have been uploaded so far.
sent.bytes The number of bytes that have been uploaded so far.
received.inserts The number of inserted rows that have been downloaded so far.
received.updates The number of updated rows that have been downloaded so far.
received.deletes The number of deleted rows that have been downloaded so far.
received.bytes The number of bytes that have been downloaded so far.
stop Set this member to true to interrupt the synchronization. The SQL exception SQLE_INTERRUPTED is set, and the synchronization stops as if a communications error had occurred. The observer is always called with either the DONE or ERROR state so that it can do proper cleanup.
getUserData Returns the user data object.
getStatement Returns the statement that called the synchronization. The statement is an internal UltraLite statement, and this method is unlikely to be of practical use, but is included for completion.
getErrorCode When the synchronization state is set to ERROR, this method returns a diagnostic error code.
isOKToContinue This is set to false when cancelSynchronization is called. Otherwise, it is true.
The following code illustrates a very simple observer function:
extern void __stdcall ObserverFunc(
p_ul_synch_status status )
{
printf( "UL_SYNCH_STATE is %d: ",
status->state );
switch( status->state ) {
case UL_SYNCH_STATE_STARTING:
printf( "Starting\n");
break;
case UL_SYNCH_STATE_CONNECTING:
printf( "Connecting\n" );
break;
case UL_SYNCH_STATE_SENDING_HEADER:
printf( "Sending Header\n" );
break;
case UL_SYNCH_STATE_SENDING_TABLE:
printf( "Sending Table %d of %d\n",
status->tableIndex + 1,
status->tableCount );
break;
...This observer produces the following output when synchronizing two tables:
UL_SYNCH_STATE is 0: Starting UL_SYNCH_STATE is 1: Connecting UL_SYNCH_STATE is 2: Sending Header UL_SYNCH_STATE is 3: Sending Table 1 of 2 UL_SYNCH_STATE is 3: Sending Table 2 of 2 UL_SYNCH_STATE is 4: Receiving Upload Ack UL_SYNCH_STATE is 5: Receiving Table 1 of 2 UL_SYNCH_STATE is 5: Receiving Table 2 of 2 UL_SYNCH_STATE is 6: Sending Download Ack UL_SYNCH_STATE is 7: Disconnecting UL_SYNCH_STATE is 8: Done
An example of an observer function is included in the CustDB sample application. The implementation in CustDB provides a dialog that displays synchronization progress and allows the user to cancel synchronization. The user-interface component makes the observer function platform specific.
The CustDB sample code is in the Samples\UltraLite\CustDB subdirectory of your SQL Anywhere directory. The observer function is contained in the platform-specific subdirectories of the CustDB directory.