3 Managing Your SQLite Mobile Client

The following sections describe how to manage the Oracle Database Lite functionality on the SQLite Mobile client:

• Section 3.1, "Starting the SQLite Mobile Client"

• Section 3.2, "Synchronize Data for Applications on the SQLite Mobile Client"

• Section 3.3, "Use the mSync GUI to Initiate Synchronization"

• Section 3.4, "Reset the Mobile User Password"

• Section 3.5, "Manage Snapshots on SQLite Mobile Client"

• Section 3.6, "Control Automatic Synchronization for a Specific SQLite Mobile Client"

• Section 3.7, "Improve Performance by Disabling the Resume Feature"

• Section 3.8, "Use the Device Manager Client GUI to Manage the Client-Side Device"

• Section 3.9, "Initiate Updates for the SQLite Mobile Client"

• Section 3.10, "Communicate Between the Internet and Intranet Through a Reverse Proxy"

3.1 Starting the SQLite Mobile Client

When you installed the SQLite Mobile client on Linux or Windows, it configured that the Mobile client should always be started automatically when the device is initiated. For Win32 and WinCE devices, you do not have to perform anything extra to start the Mobile client. However, for the Linux platform, you may have to start the Linux Mobile client by executing the webtogo.sh file in the <mobile_client>/bin.

3.2 Synchronize Data for Applications on the SQLite Mobile Client

You can have an application downloaded onto a device, where data can be synchronized between the SQLite Mobile client and the back-end Oracle database.

The following describes how to initiate synchronization from each type of SQLite Mobile client:

• Blackberry and Android clients: The application built for these clients initiate synchronization by executing the SQLite Mobile client Java APIs. For details on synchronization APIs, see Chapter 2, "Synchronization" and Chapter 3, "Invoking Synchronization APIs from Applications" in the Oracle Database Lite Developer's Guide for more information. For full details on the Java APIs, see the Javadoc

• Linux, Win32, and WinCE clients: The application built for these clients can use the SQLite Mobile client Java APIs or C/C++ APIs. Thus, start the application as you would start any application on these platforms.

  Note:

  When you initiate a synchronization from the client, either manually or by scheduling a job, the synchronization cannot occur if there is an active connection with an uncommitted transaction opened from another source. This could be from scheduling two jobs to synchronize at the same time, from mSync, or the client synchronization APIs.

  Initiate synchronization through one of the following methods:

  • Execute the msync executable, described in Section 3.3, "Use the mSync GUI to Initiate Synchronization".

  • Implement synchronization within your application using the synchronization APIs, as described in Chapter 2, "Synchronization" and Chapter 3, "Invoking Synchronization APIs from Applications" in the Oracle Database Lite Developer's Guide.

Note:

The Mobile client device clock must be accurate for the time zone set on the device before attempting to synchronize. An inaccurate time may result in the following exception during synchronization: CNS: 9026 "Wrong username or password. Please enter correct value and reSync."

3.3 Use the mSync GUI to Initiate Synchronization

You can initiate synchronization of the SQLite Mobile client using the mSync GUI, as shown in Figure 3-1.

Figure 3-1 Using the mSync GUI to Initiate Synchronization

Description of "Figure 3-1 Using the mSync GUI to Initiate Synchronization"

To bring up the mSync GUI, execute msync.exe on WinCE and Win32 or msync on Linux, which is located in the /SQLite subdirectory under the directory where you installed the Mobile client. For Blackberry and Android platforms, start mSync by clicking the mSync application icon.

Modify the following supplied values, if incorrect:

• Username and password for the user that is starting the synchronization.

  Note:

  See Section 4.3.1.2.1, "Define Username and Password" in the Oracle Database Lite Administration and Deployment Guide for conventions for creating the username or password.

• Check if you want the password saved for future requests.

• Host name where the Mobile Server is installed.

Click Sync to start the Synchronization. Click Apply to save any modifications you made to the entries. Click Exit to leave the tool.

If there are software updates that are waiting to be downloaded to the client, then the update tool is automatically executed after the end of the synchronization process. See Section 3.9, "Initiate Updates for the SQLite Mobile Client" for more information.

Note:

The only time that the client does not check for software updates is if you are using the Synchronization APIs. If you want to launch the update UI, then enter update on the command line.

You can also modify the tool options by selecting the Tools Selection at the bottom of the UI, as shown in Figure 3-2.

Figure 3-2 The mSync Tools Selection

Description of "Figure 3-2 The mSync Tools Selection"

The following sections describe the Tools options:

• Section 3.3.1, "Network Options for MSync Tool"

• Section 3.3.2, "Sync Options for MSync Tool"

• Section 3.3.3, "Sync to a File Using File-Based Sync"

• Section 3.3.4, "Use SQLite Mobile Client Tools on Linux"

3.3.1 Network Options for MSync Tool

Figure 3-3 displays the Network options screen where you can specify a proxy if your network provider requires that you use a proxy server to access the internet. Click Use Proxy to use a proxy and then enter the proxy server and port number.

Figure 3-3 The mSync Network Options Selection

Description of "Figure 3-3 The mSync Network Options Selection"

3.3.2 Sync Options for MSync Tool

Figure 3-4 displays the Sync Options screen where you can specify the following:

• Mobile User Password—Modify the existing password. The Mobile user password is stored on both the client and the Mobile Server. To ensure that both are modified, only change the password when connected to the Mobile Server. See Section 3.4, "Reset the Mobile User Password" for details.

• High Priority—Select this checkbox to specify synchronizing only High Priority data. This specifies under what conditions the different priority records are synchronized. By default, the value is LOW, which is synchronized last. If you have a very low network bandwidth and a high ping delay, you may only want to synchronize your HIGH priority data.

  When you select this checkbox, you are enabling pre-defined high priority records to be synchronized first. This only for those publication items that have specified a restricting predicate. See Section 1.2.10, "Priority-Based Replication" in the Oracle Database Lite Troubleshooting and Tuning Guide for more information.

• Force Refresh—The force refresh option is an emergency only synchronization option. Check this option when a client is corrupt or malfunctioning, so that you decide to replace the Mobile client data with a fresh copy of data from the enterprise data store with the forced refresh. When this option is selected, any data transactions that have been made on the client are lost.

  When a force refresh is initiated all data on the client is removed. The client then brings down an accurate copy of the client data from the enterprise database to start fresh with exactly what is currently stored in the enterprise data store.

Figure 3-4 The mSync Options Selection

Description of "Figure 3-4 The mSync Options Selection"

3.3.3 Sync to a File Using File-Based Sync

Once you select File Based Sync off the Tools menu, the screen shown in Figure 3-5 is displayed. To synchronize to a file, click on the File based sync checkbox and perform the following:

• If you select the send radio button, then browse for a directory where you want the client to save the upload data file from the Mobile client for the Mobile Server.

• If you select the receive radio button, then provide the location for the download data file from the Mobile Server.

For full details on File-Based Sync, see Section 5.8, "Synchronizing to a File with File-Based Sync" in the Oracle Database Lite Administration and Deployment Guide.

Figure 3-5 File Sync Options

Description of "Figure 3-5 File Sync Options"

3.3.4 Use SQLite Mobile Client Tools on Linux

The SQLite Mobile client for Linux supports the msync, dmagent and update tools. To use the UI-based tools, use the following executables: msync, dmagent, or update.

To synchronize on a Linux client with the command line tool, use the msync executable for synchronization, as follows:

./msync username/password@server[:port][@proxy:port]
 

For example,

./msync john/john@testserver:8000

The other msync options, such as -save, -a, -password and -force currently will not result in a successful sync. This is a limitation only for the msync executable in the MDK installation on Linux.

3.4 Reset the Mobile User Password

Because the Mobile user password is stored on both the client and the Mobile Server, modify the password as follows:

• Modify the password on the client using the mSync UI. Only modify the password with the mSync UI if you are connected to the Mobile Server to ensure that the user password change is propagated to the Mobile repository.

• Modify the Mobile user password in the Mobile Manager in the User Properties page. If you simply want to invalidate the Mobile user, then you only have to modify the password on this screen; however, if you want to reset the password on both the Mobile Server and the Mobile user, then also send a Reset Password command from the Device Management section in the Mobile Manager to the Mobile client.

  After sending the Reset Password command, you need to perform a synchronization on the client with the new password. Then, you will be able to connect to the client database using the new password.

  Note:

  If you modify the password on the server and do not send the Reset Password, then the client cannot synchronize. In this case, either send the Reset Password or return the password back to its original value on the server before retrying the synchronization.

See Section 11.2, "Which Password is Which" in the Oracle Database Lite Administration and Deployment Guide for details on passwords.

3.5 Manage Snapshots on SQLite Mobile Client

The following are the types of snapshots you can enable for tracking the changes on the SQLite database:

• State-based. State-based snapshots decipher the difference in the state of the data between subsequent synchronization events. This snapshot type is more resource efficient than queue-based snapshots. The SQLite Mobile client Java APIs only support state-based snapshots. To enable state-based snapshots, set the SQLITE.QUEUES parameter in the OSE.INI file to NO.

  Snapshot state tables, OSE_ST$<snapshot>, are created in the SQLite database and are populated by SQL triggers with primary keys of the modified rows.

• Queue-based: Both client and server changes are stored in a single queue. Whenever the snapshot is not locked by an application, the synchronization retrieves data from the In Queue and applies it to the base snapshot. At this point, the synchronization propagates data from the Out Queue to the server.

  Although both snapshot types rely on triggers, queue-based snapshots allow concurrent operations on the SQLite database while any synchronization is in progress. The Sync Agent compose operation places modified data into the Out Queue. Later, the sync session uploads multiple client transactions delineated by a unique transaction id to the server.

  To enable queue-based snapshots, set the SQLITE.QUEUES parameter in the OSE.INI file to YES. This is the default.

  When you use queue-based snapshots, a queue database file is created, which is named OSE_<database name>.db. This database file contains the following tables:

  • Data queue for both In Queue and Out Queue records named OSE$DATAQ.

  • BLOB queue named OSE$BLOBQ.

  • Snapshot registry named OSE$TABLES.

  • Transactions registry named OSE$TRANS.

  • Transaction sequences per publication in the OSE$TRSEQ table,

  The OSE$DATAQ queue is used for all snapshots and contains both In and Out Queue records. The TRID column is positive when the record is an Out Queue record. When you synchronize with queue-based snapshots enabled, new data from the client is uploaded from the OSE$DATAQ queue table and new data from the Oracle database is downloaded into this queue.

For more details on this parameter, see Appendix A, "SQLITE.QUEUES".

3.6 Control Automatic Synchronization for a Specific SQLite Mobile Client

As described in Section 5.4, "Using Automatic Synchronization" in the Oracle Database Lite Administration and Deployment Guide, you can enable automatic synchronization for native Mobile clients either in the publication item or for the entire platform.

However, you can disable automatic synchronization for a single client by configuring the BGSYNC.DISABLE parameter to YES in the OSE.INI file on the SQLite Mobile client. This disables the Sync Agent and the only method for synchronization is a manual synchronization.

For more details on this parameter, see Appendix A, "BGSYNC.DISABLE".

3.7 Improve Performance by Disabling the Resume Feature

The resume feature manages intermittent network failures. If resume is enabled on both the server and the client, synchronization will resume automatically within the specified resume timeout period. Also, if sync session was interrupted during a network operation, the next synchronization will try to resume the operation, as long as resume is enabled and the resume timeout has not expired.

The resume transport adds overhead with additional network round trips and additional data to be saved on the client and on the server. Any device with reliable networks may disable the resume feature to improve performance of the synchronization system for this device and improve scalability on the server.

You can disable the resume feature for the SQLite Mobile client device by setting the OSE.RESUME parameter in the OSE.INI file to NO. For more details on the resume feature and disabling it for your SQLite Mobile client, see Section A.1.3, "OSE.RESUME" and Section 5.6, "Resuming an Interrupted Synchronization" in the Oracle Database Lite Administration and Deployment Guide.

3.8 Use the Device Manager Client GUI to Manage the Client-Side Device

On Win32, WinCE, or Linux client platforms, you can manage the client software using the Device Manager. See Section 7.8, "Using the Device Manager Agent (dmagent) on the Client" in the Oracle Database Lite Administration and Deployment Guide for a full description.

3.9 Initiate Updates for the SQLite Mobile Client

You can initiate a request for software updates from the Mobile Server by executing the Oracle Database Lite Update tool. For details, see Section 7.7.3, "Initiate Updates of Oracle Database Lite Software for Mobile Clients" in the Oracle Database Lite Administration and Deployment Guide.

3.10 Communicate Between the Internet and Intranet Through a Reverse Proxy

If a Win32, WinCE or Linux SQLite Mobile client is on either side of the firewall, you set up a proxy or reverse proxy to facilitate communication between the Mobile client and Mobile Server. See Section 11.6, "Using a Firewall Proxy or Reverse Proxy" in the Oracle Database Lite Administration and Deployment Guide.