3
Synchronization

3.1.1 Synchronization Concepts

Data is synchronized between an Oracle Lite database on an offline client and an Oracle database instance by invoking the Mobile Sync Client module from the client device which interacts with the Mobile Server. The Mobile Server uses synchronization objects such as users, publications, publication items, and subscriptions to handle client operations during a synchronization session. This makes up the publish and subscribe model of synchronization which underlies Oracle Lite.

• Publication items contain SQL queries that are defined against Oracle database tables. Publication items are snapshot definitions that can have optional subscription parameters, which determine what data is synchronized.

• Publications serve as containers for publication items in the Mobile Server repository, and map to the snapshot created on a client device.

• Publication items contain SQL queries that are defined against Oracle database tables. Publication items are snapshot definitions that can have optional subscription parameters, which determine what data is synchronized.

• Parameters are used to define user-dependent data subsetting variables. Data subsetting allows refinement of the data requirements for a given user subscribed to a publication.

• A publication is subscribed to by one or more users. Users and subscriptions are tracked by the Mobile Server.

• Through established subscriptions, the Mobile Server prepares any new data for each client which is then downloaded when the client synchronizes. Only the required subset of data is downloaded to each client. If the publication has been flagged for complete refresh, all the data is downloaded.

3.2.1 Fast Refresh Synchronization

The default method of synchronization is the fast refresh mode which is displayed in Figure 3-1. Fast refresh is an incremental refresh where changes are uploaded and stored in inqueues during the upload phase, then the changes, which have been stored in outqueues, are downloaded and applied to the client. Meanwhile, the MGP periodically looks at the inqueues and takes anything found in an inqueue and applies it to the database during the apply phase. Changes generated by this client, other clients, and server-side applications to the Oracle database are then composed and stored in an outqueue until the next time the client synchronizes.

The upload/download phases are performed independently of any apply/compose phases. An apply phase is not dependent on an upload phase, nor is a download phase dependent on a compose phase. During any synchronization session, download occurs after upload, and compose occurs after apply.

3.2.1.1 Client Upload/Download Operations

When synchronization is initiated, the client opens a connection to the Mobile Server via the selected mode of transport, which causes the Mobile Server to open a connection to the Oracle database server. The following process is displayed in Figure 3-2.

Figure 3-2 Upload/ Download Phases

Changes to Oracle Lite database records are accumulated and flagged with codes for the type of Data Manipulation Language (DML) operation performed, Insert, Update, or Delete. The the data is encrypted, compressed, and sent to the Mobile Server to populate objects called inqueues. An inqueue is a persistent database object created to store data temporarily during synchronization.

During the same session, snapshots on the client are updated by applying data from the outqueue to the Oracle Lite database. An outqueue differs from an inqueue in that it is not a table but a datastructure containing a reference to the data contained in the Oracle database base tables. See Section 6.4.9, "Queue Interface for Customizing Replication" for information on customizing the way the inqueues and outqueues process data.

3.2.1.2 Mobile Server Apply Operation

The MGP takes any contents of the inqueue and applies it to the base tables on the Oracle database. Any conflicts are detected and resolved at this time. See Section 6.5, "Synchronization Errors and Conflicts" for more information about this topic.

Figure 3-3 Apply/Compose Phases

3.2.2 Complete Refresh Synchronization

During a complete refresh, all contents of the snapshot tables present on the client are refreshed from the Oracle database tables. The MGP is not involved because all the contents are refreshed, but this form of synchronization is more time and system-resource intensive.

3.2.3 Synchronizing an Encrypted Database

It is possible to encrypt an Oracle Lite database using a utility called ENCRYPDB. Synchronizing with an encrypted database is requires an understanding of how Oracle Lite manages encrypted databases. For more information, see Section B.4, "ENCRYPDB".

3.3.1 Active Sync Overview

Active Sync allows data to be synchronized between a Windows based desktop system and a Windows CE device or devices. The synchronization process can occur through any form of transport between device and computer and can include addition, deletion, or other revision type operations.

3.3.2 Installing Files from the Mobile Server

To distribute necessary files from Mobile Server to their devices, point your browser to the instance of Mobile Server you are using and append /setup to view the setup screen. For example, if your Mobile Server instance is called MyMobileServer, you would enter MyMobileServer/webtogo/setup.

Select the version which corresponds to the Windows CE device connected to your desktop via ActiveSync. Selecting the link causes a .cab file to be downloaded to the desktop and silently registered with Active Sync. You can then run the Active Sync, select the version in the list which they wish to download, and press "OK". Only the language set for the instance of Mobile Server you are using is available for download.

3.3.3 Data Source Name Creation

Data Source Names (DSN) are names the ODBC and JDBC interfaces used to identify a database. Applications connect to databases by providing their DSNs.

Mobile Client creates DSN automatically for each publication item that is synchronized to the client. This section describes how these names are generated.

Each publication item is mapped to a specific database on the client device.

Each database has a DSN associated to it. The name of the database and the name of the DSN are the same (except that the database file has the .ODB extension). You can define the name of the DSN and database created on the client when you publish the application. Under the publication panel, you can set the "Client Database Name". This string will be used as the DSN and database name. If you do not specify the name, a unique string will be generated and used as the DSN and database name.

For example, when you publish an application, if you create a publication with the Client Database Name set to "Orders", then on the client device after the first sync you will see the DSN "Orders" and the database file "Orders.odb" created.

3.3.4 Storing Databases in Flash Memory Cards

Oracle Lite supports the storage of database files in flash memory cards. When a flashcard is inserted, a directory named "Storage Card" shows up on the root directory. You can use this directory as any other directory in the device. All files you move or copy in this directory are stored in the flash card.

You can tell Oracle Lite to store all databases in the flash card by modifying the polite.txt configuration file before your first sync. Note that if you modify the file after your first sync, only new publications will be stored in the new location specified.

To store all your databases in the flash card, before the first sync, follow these steps:

1. Install Oracle Lite for Windows CE from Active Sync application tools.

2. Run File Explorer on the device and open up the file /ORACE/polite.txt.

3. Add or change an entry under the section [All Databases]

   DATADIRECTORY=/Storage Card:/Orace:/tmp

   In fact, you can set DataDirectory to any valid directory and it will create all databases in that directory. However the directory must be created prior to the first sync.

4. 4. Run mSync.exe to synchronization

First the first sync, you will see all your databases created in the /Storage Card directory and all the DSNs pointing to it in odbc.txt.

3.3.5 Syncronizing with ActiveSync

The are a few ways to start synchronizing, and it depends on the Sync Mode that you have selected. To change the Sync Mode, go to the ActiveSync Options dialog displayed in Figure 3-4, and click on the Sync Mode tab.

If you have selected either "Continuously while the device is connected" or "Once upon connection", then the minute you place the device in the cradle, it will start to synchronize all the enabled providers. If you have "Manually" selected, then it will not synchronize unless you click on the "Sync" button in the ActiveSync main window. This button appears in the upper-left corner of the button-bar and has upward- and downward-pointing arrows on it.

3.3.5.1 Synchronization Settings

There are two ways you can change the sync settings. If mSync is enabled, double- click on the mSync icon in the ActiveSync main window as shown in Figure 3-5. You can also go to the ActiveSync Options dialog, select mSync, then select the "Settings" button. In either case the dialog appears as displayed in Figure 3-6:

Figure 3-6 mSync Provider Settings Screen

The settings in the dialog are listed in Table 3-1:

Table 3-1 mSync Provider Settings Screen Options

Option	Description
Use settings from device	This is checked by default. If this is selected, then the local settings are disable and the provider attempts to use the synchronization settings from the device. In this case, the device profile must be set up by running mSync.exe from the device and entering the information, then click on "Apply". If this is not done prior to synchronization, an error returns, usually stating that it could not connect to the Mobile Server. If this checkbox is not selected, the local settings controls are enabled. The local settings are used for the synchronization instead. This is useful for people who have different network settings on their desktop than from the direct modem or wireless connection with the Windows CE device. For example, use proxy when connected to the office network, and don't use proxy when using wireless modem.
Mobile Server: Hostname	This is the name of Mobile Server. You can also enter the IP address in the format XXX.XXX.XXX.XXX. No space are allowed.
Proxy Server…	Select this button to change the proxy settings.
Username	Your login used to authenticate with the Mobile Server.
Password	Your password.

3.3.5.2 mSync Proxy Settings

If you open the Proxy Settings screen you are able to set the options displayed in Figure 3-7:

Figure 3-7 mSync Proxy Settings Screen

The proxy settings parameters are listed in Table 3-2:

Table 3-2 mSync Proxy Settings Screen Options

Option	Description
Use Proxy Server	Selecting this check-box enables the proxy server for the provider.
Hostname	Hostname or IP address of the proxy server.
Port	Port number of the proxy server. You can also enter in the service name but it must be available in the system service table.
Use Default	Select this to copy the proxy settings from your browser or operating system.

3.4.1 Configuring NT RAS

To enable TCP/IP communications between Windows CE device and your Windows NT server using Windows NT RAS, perform the following steps:

1. In the Windows Control panel, double-click the network icon.

2. Click the Add button in the Services tab of the Network window.

3. Select Remote Access Service and then click the OK button.

4. Insert the Windows NT CD into the disk drive and specify the location where you want the setup program to search for existing Windows NT RAS files.

5. Click the Continue button. The setup program copies the Windows NT RAS files into the appropriate directories. If the setup program fails to detect a modem, it prompts you to add a modem.

6. Click the Yes button and enter the required information to install a modem. The Add RAS Device window appears.

7. Select COM1-Dial-Up Networking Serial Cable from the drop down list and click the OK button. The Remote Access Setup window appears.

8. Under Port, select COM1 and click the Configure button. The Configure Port Usage window appears.

9. Select the "Receive calls only" radio button and click the OK button.

10. Click the Network button in the Remote Access Setup window. The Network Configuration window appears.

11. Select TCP/IP and click the OK button. The RAS Server TCP/IP Configuration window appears.

12. Select "Entire network" and "Use static address pool".

13. You can specify a range of TCP/IP addresses for multiple devices. Enter the beginning of a TCP/IP address range in the Begin field and enter the ending of a TCP/IP address range in the End field. The range should be equal to the number of clients plus 1. For Example, if you have fifty devices you could enter the following range:

    Begin: 10.1.0.1

    End: 10.1.0.51

    
    

    Important: You must ensure that the TCP/IP addresses in your selected range are not already in use by other computers in your network.

    
    

14. Click the OK button.

15. In the Network Configuration window, select "Any authentication including clear text" and click the OK button. Click the Continue button. The Setup Message window appears. Click the OK button.

16. In the Network window, click the Close button. The Network Settings Change window appears. Click the Yes button.

17. Once the system reboots, click the Services icon in the Windows Control Panel. The Services window appears.

18. Select Remote Access Server and click the Startup button.

19. Select Automatic and click the OK button. Click the Close button.

20. From the Windows Start menu select Administrative Tools and then select User Manager. The User Manager window appears.

3.4.2 Create a RAS User account for the device as follows:

1. Select New User from the User menu. The New User window dialog appears.

2. Enter a user name, password, and password confirmation in the required fields.

3. Select "Password Never Expires".

4. Click the Dialin button. The Dialin Information dialog appears.

5. Select "Grant dial-in permission to user". Click the OK button.

6. Click the OK button to exit the New User dialog.

7. Exit the User Manager screen.

8. From the Windows Start menu select Administrative Tools and then select Remote Access Administration. The Remote Access Admin window appears. Installing the Sample Application on the Device.

9. Verify that the new RAS user is granted remote access permission and click the OK button.

3.4.3 Windows Desktop RAS Settings

When you configure RAS verify that:

• The modem setting is "dial out and receive calls".

• You select the option to allow the Windows CE device to connect to any computer in the domain.

• The static IP addresses for the Windows CE device are in the same subnet as the desktop connected to the device. Otherwise, you cannot make an HTTP connection and replication fails.

• The ending IP address for the Windows CE device is not in use on the network.

• The Domain Logon server is available to the Windows CE device.

• The IP address is set correctly for the Windows CE device before running Mobile Sync Client application.

3.4.4 Windows Desktop Settings

When you configure the Windows desktop settings, verify that:

• The baud rate is set correctly in the Modems and Ports configuration in the Control Panel. Also, the baud rate for the Windows CE device matches the baud rate on the desktop.

• You reinstall your current Windows NT service pack after installing the Windows CE services.

3.7.1 Java Interface

Using the Java interface to Mobile Sync client-side synchronization, programs written in Java can use the functionality provided by the OCAPI library. The Java interface resides in the oracle.lite.msync package.

The Java interface provides for the following functions:

• Setting of client side user profiles containing data such as user name, password, and server.

• Starting the synchronization process

• Tracking the progress of the synchronization process.

The Java interface consists of two files, mSync.jar and msync_java.dll. In order to use the Java interface, msync.jar must be included in the classpath. The mSync.jar file is located in <ORACLE_HOME>\Mobile\classes directory. The msync_java.dll file is located in the <ORACLE_HOME>\Mobile\bin directory.

There are four parts to the Java interface:

• Section 3.7.1.1, "Sync Class"

• Section 3.7.1.2, "SyncException Class"

• Section 3.7.1.3, "SyncOption Class"

• Section 3.7.1.6, "SyncProgressListener Interface"

Sync(SyncOption option)

SyncProgressListener add(ProgressListener listener)

try

{

  Sync mySync = new Sync( new SyncOption());

  mySync.doSync();

}

catch ( SyncException e)

{

  System.err.println( "Sync Error:"+e.getMessage());

}

SyncException()

SyncException( int errorCode, String errorMessage)

SyncOption()

SyncOption

   ( String user,

     String password,

     String syncParam,

     String transportDriver,

     String transportParam)

SyncOption opt = new SyncOption

("sam","lion","pushonly","HTTP","server=server1;proxy=www-proxy.us.oracle.com;proxyPort=80");

opt.save();

"name=value;name2=value2;name3=value3, ...;"

"security=SSL; noapps;"

"reset;pushOnly;tableFlag[TestApp.Emp]=disable;tableFlag[TestApp.Dept]=enable;"

"name=value;name2=value2;name3=value3, ...;"

"server=test.oracle.com;proxy=proxy.oracle.com;proxyPort=8080;"

void progress

   (int progressType,

    int completed);

class myProgressTracker implements SyncProgress Listener;

{

  public void progress

     (int progressType, 

     int completed)

    {

      System.out.println( "Status: "+progressType+"="+ completed+"%" );

     } //progress

 }

3.7.2 COM Interface

The COM Interface is used to program applications that can start the synchronization process and enable a variety of settings. This interface is modular and extensible and makes use of the ocapi.dll through a wrapper style interface. The interface is designed to allow applications to be written in Visual Basic, but other programming methods supported by the COM interface including VBScript and others.

Dim sync As Msync.syn

Set sync = CreateObject("MSync.Sync")

sync.DoSync

Set syncOpt = CreateObject("MSync.SyncOption")

' Load last sync info

syncOpt.Load

' Change user name to Sam

syncOpt.usename = "Sam"

Set sync = CreateObject("MSync.Sync")

' Tell ISync to use this option

sync.setOptionObject (syncOpt)

' Do sync

sync.DoSync

"name=value;name2=value2;name3=value3, ...;"

"security=SSL; noapps;"

"reset;pushOnly;tableFlag[TestApp.Emp]=disable;tableFlag[TestApp.Dept]=enable;"

"name=value;name2=value2;name3=value3, ...;"

"server=test.oracle.com;proxy=proxy.oracle.com;proxyPort=8080;"

' Define the ISync object with eventsDim WithEvents sync As MSync.sync' Create the callback.' The name of the call back is the name of the ISync object (not the class), and ' underscore and then the function name - progressPrivate Sub sync_progress(ByVal progressType As Long, ByVal param1 As Long, ByVal param2 As Long)    Desc = ""    ' Decipher the progressType    Select Case progressType        Case PT_SEND            Desc = "Sending data..."        Case PT_RECV            Desc = "Receiving..."    End SelectEnd Sub

3.7.3 C/C++ Interface

The C/C++ Interface consists of five function calls and a control structure, the definitions for which can be found in ocapi.h and ocapi.dll which are located in the <ORACLE_HOME>\Mobile\bin directory. This API allows an application to initiate and monitor synchronization with a database from a client rather than requiring that it be started from the Mobile Server. The default transport mechanism is HTTP, but other forms of transport can be specified if they are available.

int ocSessionInit( ocEnv *env );

int ocSessionTerm( ocEnv *env );

int ocSaveUserInfo( ocEnv *env );

int ocDoSynchronize( ocEnv *env );

ocSetTableSyncFlag(ocEnv *env, const char* publication_name, 

const char* table_name, short sync_flag)

typedef struct ocEnv_s {

                       // User infos

char username[MAX_USERNAME];    // Mobile Sync Client id 

char password[MAX_USERNAME];    // Mobile Sync Client password for 

                                // authentication during sync 

char newPassword[MAX_USERNAME]; // resetting Mobile Sync Client password 

                                   // on server side if this field is not blank 

short savePassword;           // if set to 1, save 'password' 

char appRoot[MAX_PATHNAME];     // dir path on client device for deploying files

short priority;              // High priority table only or not

short secure;            // if set to 1, data encrypted over the wire 

enum {

OC_SENDRECEIVE = 0,     // full step of synchronize

OC_SENDONLY,     // send phase only

OC_RECEIVEONLY,     // receive phase only


                       // For Palm Only

OC_SENDTOFILE,     // send into local file | pdb

OC_RECEIVEFROMFILE     // receive from local file | pdb

}syncDirection;     // synchronize direction


enum {

OC_BUILDIN_HTTP = 0,     // Use build-in Http transport method

OC_USER_METHOD     // Use user defined transport method

}trType;           // type of transport


ocError exError;     // extra error code


ocTransportEnv transportEnv;     // transport control information 


                       // GUI related function entry

progressProc fnProgress;     // callback to track progress; this is optional


                 // Values used for Progress Bar. If 0, progress bar won't show.

long totalSendDataLen;      // set by Mobile Sync API informing transport total number of

                       // bytes to send; set before the first fnSend() is called

long totalReceiveDataLen;     // to be set by transport informing Mobile Sync API 

                       // total number of bytes to receive; 

                       // should be set at first fnReceive() call. 

void* userContext;     // user defined context

void* ocContext;     // internal use only

short logged;     // internal use only

long bufferSize;     // send/receive buffer size, default is 0

short pushOnly;     // Push only flag

short syncApps;     // Application deployment flag

} ocEnv;

typedef struct ocTransportEnv_s {

void* ocTrInfo;            // transport internal context

                           // for built-in Http, mapped to ocTrHttp

connectProc fnConnect;     // plug-in callback to establish a connection from

                           // device to server

disconnectProc fnDisconnect;     // plug-in callback to dismantle connection

                           //  from device to server

sendProc fnSend;           // plug-in callback to send data 

receiveProc fnReceive;     // plug-in callback to receive data 

}ocTransportEnv;

3.7.4 Selective Synchronization

This feature allows the mobile application to select the way specific tables are synchronized. The mobile application uses the C/C++ interface API ocSetTableSyncFlag function to determine which publication and publication items need to be synchronized. The application calls this function and sets the sync_flag parameter to either "1" (synchronize) or" 0" (no synchronization) for each table. The list of tables therefore can be changed dynamically during runtime allowing the application developer to programmatically control selective synchronization.