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

SQL Anywhere 17 » UltraLite - Database Management and Developer Guide » UltraLite as a MobiLink client » UltraLite clients » UltraLite client synchronization design

Synchronization setup for your UltraLite application

In UltraLite, synchronization begins by opening a specific connection with the MobiLink server over the configured communication stream (also known as a network protocol).

In addition to synchronization support for direct network connections, Windows Mobile devices also support Microsoft ActiveSync synchronization.

Defining the connection

Each UltraLite remote database that synchronizes with a MobiLink server does so over a network protocol. You set the network protocol with the synchronization stream parameter. Supported network protocols include TCP/IP, HTTP, HTTPS, and TLS. For the protocol you choose, you also need to supply stream parameters that define other required connection information like the MobiLink server host and the port. You must also supply the MobiLink user information and the synchronization script version.

Defining the synchronization behavior

You can control synchronization behavior by setting various synchronization parameters. The way you set parameters depends on the specific UltraLite interface you are using.

Important behaviors to consider include:

  • Synchronization direction

    By default, synchronization is bi-directional. When using only one-way synchronizations, remember to use the appropriate upload_only or download_only parameter. By performing one-way synchronizations, you minimize the synchronization time required. Also, with download-only synchronization, you do not have to commit all changes to the UltraLite database before synchronization. Uncommitted changes to tables not involved in synchronization are not uploaded, so incomplete transactions do not cause problems.

    To use download-only synchronization, you must ensure that rows overlapping with the download are not changed locally. If any data is changed locally, synchronization fails in the UltraLite application with a SQLE_DOWNLOAD_CONFLICT error.

  • Concurrent changes during synchronization

    During the upload phase, UltraLite applications can access UltraLite databases in a read-only fashion. During the download phase, read-write access is permitted, but if an application changes a row that the download then attempts to change, the download will fail and roll back. You can disable concurrent access to data during synchronization by setting the DisableConcurrency synchronization parameter.

The following procedure is generally used to add synchronization functionality to your application:

  1. Supply the necessary synchronization parameters and protocol options needed for the session as fields of a synchronization information structure.

    For example, using the UltraLite C++ API, you add synchronization to your application by setting appropriate values in the ul_sync_info structure:

    ul_sync_info info;       
           // define a sync structure named "info"
            ULEnableTcpipSynchronization( &sqlca );
           // use a TCP/IP stream
           conn->InitSynchInfo( &info );
           // initialize the structure
  = ULSocketStream();
           // specify the Socket Stream
           info.stream_parms= UL_TEXT( "host=myMLserver;port=2439"  );
           // set the MobiLink host information
           info.version = UL_TEXT( "custdb 11.0" );
           // set the MobiLink version information
           info.user_name = UL_TEXT( "50" );
           // set the MobiLink user name
           info.download_only =ul_true;
           // make the synchronization download-only
  2. Initialize synchronization.

    For direct synchronization, you would call an API-specific synchronization method. These methods return a boolean value, indicating success or failure of the synchronization operation. If the synchronization fails, you can examine detailed error status fields in another structure to get additional error information.

    For Microsoft ActiveSync synchronization, you must catch the synchronization message from the Microsoft ActiveSync provider and use the DoSync method to call the ULSynchronize method.

  3. Use an observer callback function to report the progress of the synchronization to the user.

    Note If you have an environment where DLLs fail either because the download is very large or the network connection is unreliable, you may want to implement resumable downloads.