MobiLink Synchronization Reference
Synchronization Events
When a synchronization request occurs and MobiLink server decides that a new connection must be created, the begin_connection event is fired and synchronization starts.
Following the synchronization, the connection is placed in a connection pool, and MobiLink again waits for a synchronization request for the current script version. Before a connection is eventually dropped from the connection pool, the end_connection event is fired. But if another synchronization request for the same version is received, then MobiLink handles the next synchronization request on the same connection. There are a number of events that affect the current synchronization.
The primary phases of a synchronization are the upload and download transactions. The events contained in the upload and download transactions are outlined below.
The upload transaction applies changes uploaded from a remote database.
The begin_upload event marks the beginning of the upload transaction. The upload transaction is a two-part process. First, inserts and updates are uploaded for all remote tables, and second, deletes are uploaded for all remote tables.
The end_upload event marks the end of the upload transaction.
For more information about the events that happen during upload, see Writing scripts to upload rows.
The download transaction fetches rows from the consolidated database. It begins with the begin_download event.
The download transaction is a two-part process. For each table, first deletes are downloaded, and then update/insert rows (upserts) are downloaded. The end_download event ends the download transaction.
For more information about the events that happen during download, see Writing scripts to download rows.
The following pseudo code provides an overview of the sequence in which events, and hence the script of the same name, are invoked.
The following pseudo-code shows the complete MobiLink synchronization event model. This model assumes a full synchronization (not upload-only or download-only) with no errors.
In most cases, if you have not defined a script for a given event, the default action is to do nothing.
The begin_connection and end_connection events are connection-level events. They are independent of any single synchronization and have no parameters.
Some events are invoked once per synchronization for each table being synchronized. Scripts associated with these events are called table-level scripts.
While each table can have its own table scripts, you can also write table-level scripts that are shared by several tables.
Some events, such as begin_synchronization, occur at both the connection level and the table level. You can supply both connection and table scripts for these events.
The COMMIT statements illustrate how the synchronization process is broken up into distinct transactions.
A database error can occur at any point within the synchronization process. Database errors are handled using the handle_error or handle_odbc_error scripts.
WarningThere should be no implicit or explicit commit or rollback in your synchronization scripts or the procedures or triggers that are called from your synchronization scripts. COMMIT or ROLLBACK statements within scripts alter the transactional nature of the synchronization steps. If you use them, you cannot guarantee the integrity of your data in the event of a failure. |
------------------------------------------------------ Synchronization events in pseudo-code. Legend: - // This is a comment - <name> The pseudo code for <name> is listed separately in a later section, under a banner: ------------------------ name ------------------------ - VariableName <- value Assign the given value to the given variable name. Variable names are in mixed case. - event_name If you have defined a script for the given event name, it will be invoked. ------------------------------------------------------
CONNECT to consolidated database begin_connection_autocommit begin_connection COMMIT for each synchronization request with the same script version { <synchronize> } end_connection COMMIT DISCONNECT from consolidated database
------------------------------------------------------ synchronize ------------------------------------------------------ <authenticate> <begin_synchronization> <upload> <prepare_for_download> <download> <end_synchronization>
------------------------------------------------------ authenticate ------------------------------------------------------ Status <- 1000 UseDefaultAuthentication <- TRUE if( authenticate_user script is defined ) { UseDefaultAuthentication <- FALSE TempStatus <- authenticate_user if( TempStatus > Status ) { Status <- TempStatus } }
if( authenticate_user_hashed script is defined ) { UseDefaultAuthentication <- FALSE TempStatus <- authenticate_user_hashed if( TempStatus > Status ) { Status <- TempStatus } } if( UseDefaultAuthentication ) { if( the user exists in the ml_user table ) { if( ml_user.hashed_password column is not NULL ) { if( password matches ml_user.hashed_password ) { Status <- 1000 } else { Status <- 4000 } } else { Status <- 1000 } } else if( -zu+ was on the command line ) { Status <- 1000 } else { Status <- 4000 } }
if( Status <= 2000 ) { if( authenticate_parameters script is defined ) { TempStatus <- authenticate_parameters if( TempStatus > Status ) { Status <- TempStatus } } if( Status >= 3000 ) { ROLLBACK // Abort the synchronization. } else { // UserName defaults to MobiLink user name // sent from the remote. if( modify_user script is defined ) { UserName <- modify_user // The new value of UserName is later passed to // all scripts that expect the MobiLink user name. } COMMIT }
------------------------------------------------------ begin_synchronization ------------------------------------------------------ begin_synchronization for each publication being synchronized { begin_publication COMMIT }
------------------------------------------------------ end_synchronization ------------------------------------------------------ for each publication being synchronized { if( begin_publication script was called ) { end_publication } } for each table being synchronized { if( begin_synchronization table script was called ) { end_synchronization // table event } } end_synchronization // connection event synchronization_statistics time_statistics COMMIT
For the details of upload stream processing, see Events during upload.
For the details of download stream processing, see Events during download.
Events during upload
Events during download