Skip Headers
Oracle® Database Lite Oracle Lite Client Guide
Release 10.3

Part Number E12548-02
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

6 Managing Your Oracle Lite Mobile Client

One of the benefits of Oracle Database Lite is that you can have an application downloaded onto a device, where data can be synchronized between the device and the back-end Oracle database.

In general, the types of Oracle Lite Mobile clients are as follows:

The following sections detail how to set up your Mobile client device and how to use the Oracle Database Lite technology on that device:

6.1 Start the Mobile Client

The following details how to start the Oracle Lite Mobile client:

For Win32 and WinCE devices, you do not have to perform anything extra to start the Mobile client. However, for the Linux and Windows-based clients (OC4J and Web-to-Go), you may have to perform an extra step.

When you installed the Mobile client on Linux or Windows, it configured that the Mobile client should always be started automatically when the device is initiated. So, most of the time, you do not have to do anything to start the Mobile client. However, if you have a failure, you can manually start the Mobile client, as follows:

6.2 Log on to Mobile Client Workspace

If you are using a Windows or Linux Web Mobile client, then you must have installed the appropriate Mobile client on your client machine. Upon machine startup, the Mobile client is automatically started. Then, you can connect to the Mobile Client Workspace with a browser by connecting to one of the following:

If the Windows Mobile client is unexpectedly terminated, you can start the client by double-clicking on the following icon in the corner of your Windows desktop:

Windows icon for Mobile Client Workspace
Description of the illustration use_log1.gif

For all other scenarios, launch the Mobile client by accessing your Oracle Database Lite program group and choosing the Mobile client.

Figure 6-1 displays the Mobile Client Workspace Logon page.

Figure 6-1 The Mobile Workspace Logon Page

Mobile Workspace logon page
Description of "Figure 6-1 The Mobile Workspace Logon Page"

Enter the username and password for the Mobile user and click Logon.

However, if a member logs on who is attached to more than one user, the member must identify the user under whose context the member is acting. As shown in Figure 6-2, the member provides its name, password and selects the user under whose context he/she is acting. The user owns the data and the application, so this is required. Click Logon.

Figure 6-2 Member Logon Page

Member logon
Description of "Figure 6-2 Member Logon Page"

6.3 Synchronize or Execute Applications on the Mobile Client

The following details how to synchronize each Mobile client stack type:


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."

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, mSQL, Web-to-Go or the client synchronization APIs.

The first synchronization for the Mobile client creates several Oracle Lite database (ODB) files on your client device for storing either Oracle Database Lite information or your application information. These ODB files are stored in the <ORACLE_HOME>\Mobile\SDK\Oldb40 directory, as follows:


The following describes the purpose and access for these ODB files:

6.4 Manage the Mobile Client

There are several tools that you can use on the client to manage functionality. The following sections describe other tools that you can use in each platform:

6.4.1 Manage Your Clients Locally With the Mobile Client Workspace

Start the Mobile Client Workspace GUI tool for managing OC4J, Windows Web-to-Go, Linux Web-to-Go, BC4J, or Branch Office Mobile clients. The Mobile Client Workspace displays only the relevant functionality for the user that logs in. Use the Mobile Client Workspace to manage the application or to initiate synchronization on the client-side device. Instructions for Using the Mobile Client Workspace

The Mobile Client Workspace provides you access to your Mobile applications through hyperlinks in a Web browser. The following tabs are available when you use the Mobile Client Workspace for a Mobile client: Display Installed Applications

The Applications tab displays the list of applications that have been installed on the client, which you can execute. To access a Mobile application, click the icon or application name. The Mobile Client Workspace allows you to execute multiple applications concurrently in separate browsers.


When you log on as an Administrator, the Mobile Manager is listed as the available application. Configure the Mobile Client

To modify your Workspace configuration, select the Configuration tab.


When you select the Configuration tab, maximize the window to your display. If you do not, you might not be able to see all of the configuration options on the left.

The configuration options appear on the left as shown in Figure 6-3:

Figure 6-3 Configuration Options for Client Workspace

Mobile client workspace configuration options
Description of "Figure 6-3 Configuration Options for Client Workspace"


For member users, only the Change Password option is shown.

These options are described in the following sections:

Automatic Sync History

This screen shows you the history for all automatic synchronization events that occurred for your Mobile client. The following information is displayed about each event:

Table 6-1 History of Automatic Synchronization Events for Mobile Client

Label Description

Event code

An internal code that supplies more information to Oracle Support, if called.

Event type

An icon showing the outcome of the synchronization, as follows:

  • An X demonstrates there was an error.

  • An exclamation point indicates a warning.

  • An i indicates the synchronization was successful.


Date and time of the automatic synchronization.

Event Description

A message that describes the outcome of the automatic synchronization between your Mobile client and the back-end Oracle database.


Check the delete checkbox and click Save if you no longer wish to see the history for this event.

In addition, you can perform the following:

  • If you have more than a single page of events listed, click Previous and Next to view all events.

  • To delete one or more events, select the Delete checkbox of these items and then click Save.

  • To delete all events on this screen, click Select All and then click Save.

  • To deselect all Delete checkboxes, click Clear All.

This screen displays what automatic synchronization events took place in the past and the results of these events.


To configure an application to use the default setting for automatic synchronization, see Section, "Configure Application Synchronization Default".

Workspace Settings

Configure your Mobile Client Workspace settings, such as display options and client options. Table 6-2 discusses the Web client settings:

Table 6-2 Workspace Configuration Options

Label Description

Display icons?

Enables you to display Web application icons. To display Web application icons, select Yes. If you do not want to display Web application icons, select No.

Display description?

Enables you to display Web application descriptions. To display Web application descriptions, select Yes. If you do not want to display Web application descriptions, select No.

Applications per row

Enables you to specify the number of applications arranged in a horizontal row in the Workspace.

Use default settings for synchronization?

If you select this option, all applications (including new applications) are synchronized at once. If you de-select this option, then you can choose which applications synchronize— for manual synchronization only. Using this list, you can reduce sychronization time by selecting which applications you want to synchronize. In this mode, you are notified when new applications become available.

Mobile Client for OC4J or Web-to-Go Mode

Selecting Always Offline enables you to work continuously. If you want to use the backwards compatible option of offline/online, select the Online/Offline option.

Ask before ugrading the Mobile Client for OC4J or Web-to-Go?

Selecting this option instructs the Mobile client to ask you before downloading newer software versions for the Mobile client. If you do not select this option, your Mobile client is automatically upgraded the next time you synchronize if a new version is available.

Enable Automatic Sync?

By default, this is enabled. If checked, then automatic sync is automatically enabled. Uncheck if you want to manually synchronize this client yourself.

Number of Automatic Sync History Messages to be displayed per page.

This defines the number of history records to display on the Automatic Sync History page. By default, this value is 25.

Enable File-Based Sync?

By default, this is disabled. If checked, then file-based sync is enabled. Uncheck if you want to synchronize this client over the network. For details about file-based synchronization, see Section 5.8, "Synchronizing to a File with File-Based Sync" in the Oracle Database Lite Administration and Deployment Guide.

Application Settings

Select the applications that you want to synchronize by default. In the default synchronization mode, the Mobile Server synchronizes your client applications automatically with the Mobile Server. See Section, "Configure Application Synchronization Default" for full details.

Change Password

The password is stored on both the client and the Mobile server. To ensure that the password is modified on both the client and the Mobile server, only change the password using the Client Workspace when you have a connection to the Mobile Server. See Section 6.4.3, "Reset the Mobile User Password" for more details.

List Jobs

You can schedule a time when synchronization is to be initiated on the client. This is configured as a job initiated by the client. There is a small job engine on the client, so when you set up a job to execute at a certain time and interval, it initiates the application at the specified time. The only job that you can schedule on the client is for synchronization. You should not schedule multiple client synchronization jobs for the same time on the client. In fact, you should make sure that all other connections to the database, such as mSQL, JDBC, and so on, are closed before starting the synchronization. For more information on scheduling jobs on the server-side, see Chapter 6, "Managing Jobs with the Job Scheduler" in the Oracle Database Lite Administration and Deployment Guide.

Scheduled replication jobs will not run on client if there are any pending transactions that have not been committed on that client.

Member Initialization

After the Mobile client is installed and the user completes the first synchronization, you can use the member initialization screen to perform a batch initialization of any selected members. Each of these members belong the the user that logged into the client Workspace. This can be performed at any time after the first synchronization assuming that there is an available network connection to the Mobile Server.


The other method for member initialization is automatically performed when the member requests a manual synchronization.

After the successful authentication of each user, the schema for that user will be created in the database using the password provided by the user. Once the schema is created, the member may login to the system without requiring any connectivity to the Mobile Server.

This is useful where connectivity to the Mobile Server is not always readily available; thus, this option enables you to initialize all desired members at the most opportune time.

To initialize one or more members of this user, perform the following:

  1. Select the checkbox for all members you want to initialize.

  2. Enter the password for all selected members, where the password of the member should be same as the one set during creation of the member.

  3. Click Save.

If any of the members fail to initialize, the confirmation page displays the members that failed to initialize. The only reason that this can occur is if the incorrect password is provided. Provide the correct password and try again.

If the user, the owner of these members, wishes to disable any member, then this user should perform the following:

  1. Select the Disable checkbox next to each member that you want to disable. Alternatively, if you want to enable any disabled member, unclick the Disable checkbox next to the desired members.

  2. Click Save.

The Reset link discards any options selected on the Members Initialization page and reload the first page. Enable Remote Access for Mobile Client

To block a remote machine from getting access to the Mobile Client for Web, set the DISABLE_REMOTE_ACCESS parameter in the client-side webtogo.ora file to YES. Once this parameter is set to YES and the Mobile client is restarted, only the request coming from the local machine is served by the Mobile client listener. Any other request is blocked and not served.

For Mobile Client for OC4J, this parameter will not turn off remote access, as the access is controlled by the OC4J layer, not the Oracle Database Lite layer. For Branch Office clients, this parameter must be set to NO, as all clients must have remote access. For more information on the DISABLE_REMOTE_ACCESS parameter, see Section A.2, "[WEBTOGO]" in the Oracle Database Lite Administration and Deployment Guide.


The DISABLE_REMOTE_ACCESS parameter only works for Web-to-Go and Branch office clients.

However, if you want to disable the remote access for the Mobile client for OC4J, then perform the following in the OC4J configuration file on the Mobile client:

Open the <mobile_client_home>\mobile_client_oc4j\j2ee\mobileclient\application-deployments\mobileclient\webtogo\orion-web.xml file.

Add the following lines after the the <orion-web-app> section:

<access-mask default="deny">
     <ip-access ip=<ip_address> mode="allow"/>
     <host-access domain="localhost" mode="allow"/>
</access-mask> Configure Application Synchronization Default

The Application Settings option allows you to select the applications that you want to assign to the default synchronization setting. In the default mode, the Mobile client synchronizes your client application with the Mobile Server when the user requests synchronization. Selecting fewer applications decreases the amount of data to download and speeds up the synchronization process.

To select the applications for synchronization, click Application Settings. The application settings page appears in the right frame of the Mobile Workspace and displays the following information:

Table 6-3 describes the Application Settings page.

Table 6-3 Application Settings Page Description

Label Description


If selected, the Mobile client synchronizes your client application with the Mobile Server when the user initiates synchronization.

Select the Synchronize check box next to the application and click Save. If you make an error, click Reset to return to the previous settings. Initiate Manual Synchronization

The Sync tab enables you to synchronize data with the Oracle database. By default, when you click Sync, the Mobile Client for Web-to-Go is connected to the Mobile Server and synchronizes data between them. In addition, application updates and new applications accessible to the user are downloaded from Mobile Server.

In this mode, you can work continuously whether you have a connection or not. You only need a connection to the Mobile Server when you synchronize your data and applications.

However, if you do not have connectivity, you can perform a file-based synchronization. That is, if you are not able to synchronize because of a lack of network availability, you can save your transactions in an encrypted file, which can be manually copied over to the Mobile Server. Then, when the Mobile Server has updates for the client, these updates are also saved to an encrypted file which are manually uploaded by you.

To perform a file-based sync, do the following:

  1. Enable File Based Sync on the Configuration->Workspace Settings page.

  2. On the Sync page, click Sync. This causes the screen shown in Figure 6-4 to appear.

    Figure 6-4 Provide Filename for File-Based Sync

    Provide filename for file-based sync
    Description of "Figure 6-4 Provide Filename for File-Based Sync"

  3. To send or receive synchronization data between the client and the Mobile Server, perform the following:

    • To download synchronization transactions to an encrypted file, select the Send radio button and enter the directory and filename for the destination file

    • To upload the synchronization file from the Mobile Server, select the Receive radio button and browse for the encrypted file that was copied to the client.

For information on setting synchronization options, see Section, "Configure the Mobile Client". Log Off

The Log Off tab automatically closes all running applications and returns you to the logon page. Execute Mobile Applications Installed on Your Mobile Client

Web-to-Go and OC4J applications appear in the Mobile Workspace with an icon, name, and description.

Sample3 is displayed on the Workspace.
Description of the illustration use_acc1.gif

The icon and application name are both hyperlinks. To execute a Web-to-Go or OC4J application, click either the icon or application name.

The Web Mobile clients, such as OC4J or Web-to-Go, enable you to work disconnected from the Mobile Server. You need a connection to the Mobile Server only when you choose to synchronize any data changes from the client with the Oracle database.

The Web Mobile client propagates the tables that your applications use on the Mobile Server to the Mobile client as database snapshots. When you define your snapshot, you can use the SQL WHERE clause to specify a parameterized SQL query, where only the row data that your application uses is downloaded to the client. Thus, you can define what is downloaded to the client: the entire contents of the table or the subset of information that is relevant to the specific user. Most applications specify a particular subset of data that is relevant only to the user to be downloaded.

You can work continuously with Web Mobile clients storing your data changes in the Oracle Lite database. When you click the Sync tab, the Web Mobile client updates the Oracle database with any data changes you made on your client. The Mobile Server downloads any new applications, application changes, or data changes to your client. Customize the Mobile Client Workspace

You can customize the Mobile Client Workspace. See Section, "Customizing the Workspace Application" in the Oracle Database Lite Developer's Guide. Schedule Data Synchronization Jobs

The Mobile Workspace enables you to create data synchronization jobs for your site from the OC4J or Web-to-Go Mobile client. This synchronization job automatically triggers synchronization with the Mobile Server at the start date and at the specified time for this job that you set using the Mobile Workspace. See Section, "Configure the Mobile Client" for more information.

6.4.2 Use the mSync GUI to Initiate Synchronization of Your Linux, WinCE, and Win32 Applications

You can initiate synchronization of the client using the mSync GUI for Linux, WinCE and Win32 clients, as shown in Figure 6-5.

Figure 6-5 Using the mSync GUI to Initiate Synchronization

msync GUI for synchronization
Description of "Figure 6-5 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 /bin subdirectory under the directory where you installed the Mobile client. Modify the following supplied values, if incorrect:

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 6.4.5, "Initiate Updates for the Oracle Lite Client" for more information.


The only time that the client does not check for software updates is if you are using Branch Office or 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 6-6.

Figure 6-6 The mSync Tools Selection

mSync Tools
Description of "Figure 6-6 The mSync Tools Selection"

The following sections describe the Tools options: Network Options for MSync Tool

Figure 6-7 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 6-7 The mSync Network Options Selection

Network options
Description of "Figure 6-7 The mSync Network Options Selection" Sync Options for MSync Tool

Figure 6-8 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 6.4.3, "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 6-8 The mSync Options Selection

mSync Options
Description of "Figure 6-8 The mSync Options Selection" Set User Context for Member

If a member is attached to more than one user, then you must specify the user, also known as the data owner, under which the member is synchronizing. Select the appropriate user as the data owner under which to perform the synchronization.

Figure 6-9 Setting the User Context

User context option
Description of "Figure 6-9 Setting the User Context" Sync to a File Using File-Based Sync

Once you select File Based Sync off the Tools menu, the screen shown in Figure 6-10 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 6-10 File Sync Options

File sync options
Description of "Figure 6-10 File Sync Options" Use Mobile Client Tools on Linux

The 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.

6.4.3 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 either mSync UI or Client Workspace. Only modify the password using these tools 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.


    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 all Oracle Lite Database passwords.

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

On any client, you can manage the Mobile device client software using the Oracle Lite 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.

6.4.5 Initiate Updates for the Oracle Lite 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.

6.4.6 Configure JAVA_HOME for Web-to-Go Clients

Web-to-Go clients can execute against the Java version you specify, either J2SDK or J2RE. You can specify the JAVA_HOME that points to the desired JVM or JRE installation using one of the following methods:

  • You can pre-configure a default JAVA_HOME value for all users by editing the WEBTOGO.INF file on the server before the Web-to-Go client is installed. When you invoke the setup.exe file on the Mobile client device, the entries in the pre-configured WEBTOGO.INF file are placed in the webtogo.ora file, which is installed on the Mobile client.

    You can only specify the location of the Java environment on the Web-to-Go Mobile clients if you know the install location of Java on the device where the client will be installed. This would apply to devices that are pre-imaged specifically for Web-to-Go Mobile clients. For full details on how to pre-configure the JAVA_HOME value, see Section 7.2, "Configuring Mobile Clients Before Installation" in the Oracle Database Lite Administration and Deployment Guide.

  • For Web-to-Go clients that have already been installed on a Win32 platform, you can set the JAVA_HOME parameter in the webtogo.ora file on the Mobile client to point to a specific Java environment with the setjavahome.bat utility.

    For example, the following sets the JAVA_HOME parameter in the webtogo.ora file to point to the C:\jdk1.5 directory:

    setjavahome.bat <JAVA_HOME>

    The following examples show how the setjavahome.bat utility sets the JAVA_HOME parameter on the Web-to-Go Mobile client to C:\jdk1.5 and to C:\program files\jdk1.5. The second execution shows that when you have a path name that includes white spaces, you must wrap the directory path within double quotes.

    setjavahome.bat C:\jdk1.5
    setjavahome.bat "C:\program files\jdk1.5"

6.4.7 Defragmentation and Reducing Size of the Client Application Databases

On each client device, an Oracle Lite database stores the application data—either as an embedded database that exists solely for the application or as a repository for data for a specific user that is synchronized with a back-end Oracle database.

You can use the DefragDB utility on your database to perform the following optimizations:

  • Reduce size of Oracle Lite databases by defragmenting the Oracle Lite database.

  • Remove any BLOB data from the Oracle Lite database. All BLOB data—both binary and character— and indexes are stored in separate files with the extension of .obs for Oracle Blob Store. This changes the size limit on your device to either the operating system file size limitations or 16 terabytes.

Before executing this tool, you must stop ALL applications, as the database is erased during this process. This includes the Oracle Lite applications, such as the Sync Agent, Web-to-Go, and so on. To stop the Sync Agent, see Section 5.4.2, "Start, Stop, or Get Status for Automatic Synchronization" in the Oracle Database Lite Administration and Deployment Guide.

For full details on the DefragDB tool, see Section C.7, "DefragDB to Defragment and Reduce Size of the Oracle Lite Database" in the Oracle Database Lite Client Guide.

6.4.8 Communicate Between the Internet and Intranet Through a Reverse Proxy

If your Mobile client is on either side of the firewall, you can 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.