2 Installing the Mobile Client

One of the benefits of Oracle Database Mobile Server 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. When you install the mobile client, Oracle Database Mobile Server installs the Sync Engine and Device Manager.

Note:

Every mention of the mobile client in this book refers to both the Berkeley DB Mobile Client and the SQLite Mobile Client.

Each mention of Berkeley DB refers to the Berkeley DB SQL interface.

The following sections detail how to install the mobile client software on your client device:

See Chapter 1, "Oracle Database Mobile Server Management" in the Oracle Database Mobile Server Administration and Deployment Guide for information on how to manage functionality from the mobile server.

2.1 Supported Platforms and Requirements for the Mobile Client

The Berkeley DB and SQLite Mobile Clients are certified for SUN JDK 1.6 for the Java APIs and can be installed on the following platforms:

  • Android 1.6, 2.1, 2.2, 2.3, and 3.0

  • Blackberry RIM 5.0 and 6.0

  • Microsoft Windows 2003 (32-bit and 64-bit)

  • Microsoft Windows 2008 (32-bit and 64-bit R2)

  • Microsoft Windows XP Professional Edition with Service Pack 3, 32-bit

  • Microsoft Windows 7 (32-bit and 64-bit)

  • Microsoft Windows Vista Ultimate

  • Oracle Enterprise Linux 5.0, or 6.0 (32-bit and 64-bit)

You can also install Berkeley DB and SQLite Mobile Clients on the Microsoft Windows Mobile 6 and 6.5 platforms.

Note:

You can configure only one device for a particular user. For example, it is not possible to have two devices both executing the mobile client for the user JOHN.

Automatic synchronization and device management are available on most mobile client platforms. Table 2-1 displays what features are available on which platforms.

Table 2-1 Feature Support for Client Platforms

Platform Automatic synchronization Device management through the DM Agent

Blackberry

Yes

No

Android

Yes

Yes

Win32

Yes

Yes

WinCE

Yes

Yes

Windows Mobile

Yes

Yes

Linux

Yes

Yes

2.1.1 Certified Operating Systems and Other Software Requirements

The following tables detail the requirements for the client platforms on which you may install the mobile client. The requirements do not include requirements for either client database, but are only the requirements for the mobile client including the Sync Engine and Device Manager.

Table 2-2 BlackBerry and Android Platform Requirements

Platform Minimum Storage for Mobile Client

BlackBerry

100 KB

Android

100 KB

Table 2-3 Software Requirements for Windows Mobile Clients

Device Platform Certified Operating System Other Software Requirements

Win32

Minimum storage needed for mobile client is 2,756 KB.

Windows 2003, Windows 2008, Windows Vista Ultimate, Windows XP Professional Edition with Service Pack 2, Windows 7

If using Java APIs for synchronization, use Sun JDK 1.6.

If implementing any .NET applications, use Compact Framework .NET 1.1 or 2.0

Windows CE

Windows CE 5.0

See Table 2-5, "Pocket PC and Windows Mobile Supported Platforms" for full details.

If using Java APIs for synchronization, use Sun JDK 1.6.

ActiveSync version 3.8 or higher.

Microsoft .NET Compact Framework 1.0

Windows Mobile

  • Windows Mobile 5

  • Windows Mobile 5 for Pocket PC

  • Windows Mobile 5 for Pocket PC Phone Edition

  • Windows Mobile 5 AKU2

If using Java APIs for synchronization, use Sun JDK 1.6..

ActiveSync version 4.1 or higher.

Microsoft .NET Compact Framework 1.1 or 2.0

  • Windows Mobile 6

  • Windows Mobile 6 Classic

  • Windows Mobile 6 Professional

If using Java APIs for synchronization, use Sun JDK 1.6..

ActiveSync version 4.5 or higher.

Microsoft .NET Compact Framework 1.1 or 2.0

You should install all of the patches required for the JDK for the Windows operating system. This is constantly under review and published on the JDK download page on the Sun Microsystems Web site.

2.1.2 Supported and Certified Technologies for Native Mobile Clients

The following are the supported and certified technologies for native mobile clients:

Note:

Ensure that after you install the required software, that they the appropriate directories are included in the PATH. For example, after you install the JDK, ensure that the JAVA_HOME is included in the PATH.

For both the Berkeley DB and SQLite Mobile Clients, ADO.Net is supported by SQLite. For more information on ADO.Net support, see the following URL:

http://system.data.sqlite.org/index.html/doc/trunk/www/features.wiki

Table 2-4 Supported and Certified Technologies for Native Mobile Clients

Device Platform Supported Technologies Certified Technologies

Win32

  • ADO.Net

  • JDBC

  • ODBC

Sun Microsystems Java Runtime Edition 5.0 and 6.0

Windows CE

  • Microsoft ActiveSync version 3.8 or for Windows CE 5.0, use Microsoft ActiveSync version 4.1 or higher.

  • ADO.Net

  • JDBC

  • ODBC

Sun JDK 1.6.

Linux x86

JDBC

Sun Microsystems Java Runtime Edition 5.0 and 6.0

For each native platform, a CAB file is downloaded from the setup page. The naming structure for each CAB file is as follows: <mobile_client>.<language>.<platform>.<cpu>.cab, where <mobile_client> can be bdb or sqlite.

Table 2-5 Pocket PC and Windows Mobile Supported Platforms

Product Name WinCE Version Chipsets SQLite Client CAB file download from Setup page

Windows Mobile 5 and Windows Mobile 5 AKU2

5.0 and 5.1.465

ARMV4I

PPC50 ARMV4I, which uses the <mobile_client>.<language>.ppc50.armv4i.cab

Windows Mobile 6

5.2.1236

ARMV4I

PPC60 ARMV4I, which uses the <mobile_client>.<language>.ppc60.armv4i.cab

2.2 Preparing the Device for a Mobile Application

To execute mobile applications on a device, do the following:

  1. Install the mobile client software that is appropriate for the client platform on your client machine. For example, install the SQLite WIN32 on a Windows 32 client machine.

    See Section 2.3, "Installing the Mobile Client" for a full description.

  2. Download the user applications and its associated data.

    Synchronize the mobile client for the first time. Sign in with the user name/password of the mobile user who owns the mobile applications. The data for each application is retrieved.

    Notes:

    For the restrictions on creating the user name and password, see Section 4.3.1.2.1, "Define User Name and Password" in the Oracle Database Mobile Server Administration and Deployment Guide.

    For more information about synchronization, see Chapter 5, "Managing Synchronization" in the Oracle Database Mobile Server Administration and Deployment Guide.

  3. You can now launch your applications from your client machine or from your mobile device.

2.3 Installing the Mobile Client

We do not support the following configuration scenarios:

  • A mobile client and the Mobile Development Kit (MDK) cannot be installed on a single system.

  • A client user cannot have more than one device.

  • While you can synchronize multiple Berkeley DB or SQLite databases on the same client, you cannot synchronize both SQLite and Berkeley DB on the same mobile client.

The following sections provide directions for the mobile client install:

2.3.1 Installing the Mobile Client on Blackberry Devices

To install the mobile client on Blackberry devices, perform the following:

Note:

Applications cannot be downloaded to your Blackberry device from the mobile server, since device management is not supported for this device. You must download all applications to your Blackberry device as documented on the Blackberry Web site at http://www.blackberry.com.

  1. On the Blackberry device, open a browser to point to the mobile server setup page using the following URL.

    http://<mobile_server>:<port>/mobile/setup

    Note:

    Substitute https if using HTTP over SSL.

    Figure 2-1 displays the mobile client setup page, which contains links to install mobile client software for multiple languages. You can select another language than English on the Language pulldown.

  2. Click the mobile client for your language and the Blackberry client platform. This downloads and installs the mobile client.

  3. Perform a manual synchronization for the mobile client.

  4. Synchronization requires you to enter the user name and password for the mobile user. During the first synchronization, all data for this user is brought down and installed on your mobile device.

    Note:

    For the restrictions on creating the user name and password, see Section 4.3.1.2.1, "Define User Name and Password" in the Oracle Database Mobile Server Administration and Deployment Guide.

2.3.2 Installing the Mobile Client on Android Devices

Android platforms require that any software downloaded to the device is digitally signed with a certificate whose private key is held by the application's developer. This means that you cannot simply download and install the mobile client binaries unless they are downloaded within the context of a signed application.

Thus, the instructions for installing the mobile client on Android devices is presented with an example of creating and downloading the Android application on a SQlite Mobile Client, which is provided in Chapter 4, "Using an Android Application on the SQLite Mobile Client".

2.3.3 Installing the Mobile Client for Win32, WinCE, Windows Mobile or Linux

Before you install the mobile client on your device, make sure that there is 1 MB of space available to download the setup.exe.

To install the mobile client software, perform the following tasks.

Note:

Any developer can modify how the client is installed before the installation with the INF file. For details on how to customize your Win32, WinCE, Windows Mobile or Linux client, see Section 7.1, "Customize the Mobile Client Software Installation for Your Mobile Device" in the Oracle Database Mobile Server Administration and Deployment Guide.

  1. On the mobile client, open a browser to point to the mobile server using the following URL.

    http://<mobile_server>:<port>/mobile/setup

    Note:

    Substitute https if using HTTP over SSL.

    Figure 2-1 displays the mobile client setup page, which contains links to install mobile client software for multiple platforms and languages.

    • Language: Select a language other than English on the Language pulldown. English is the default.

    • Platform: Choose to see all available platforms for the indicated language.

    Client platforms are provided in the mobile client setup page. These client CAB files are optimized for size to minimize the footprint on your device. For each native platform, a CAB file is downloaded from the setup page. The naming structure for each CAB file is <mobile_client>.<language>.<platform>.<cpu>.cab, where <mobile_client> can be bdb or sqlite.

    However, if you are using a client with the Standard SDK for WinCE 5.0 platforms for Windows Mobile 5 (WCESTDSDK), use the appropriate CAB files that are provided in the MDK install. For information on how to install the WCESTDSDK CAB files, see Section 2.3.3.1, "Installing Standard SDK Windows Mobile Files for Your Mobile Client".

    Figure 2-1 Mobile Client Setup Page

    Mobile Client Setup
    Description of "Figure 2-1 Mobile Client Setup Page"

    Note:

    Available clients may differ from what is shown above.

  2. Click the mobile client for your language and client platform.

  3. The Save As dialog box appears. The file name field displays the setup executable file for the selected platform as an .exe file type. Save the executable file to a directory on the client machine.

    Note:

    For WinCE, install any of the Oracle Database Mobile Server Windows Mobile platforms to ActiveSync. Then, when the device is put into the cradle, ActiveSync installs the Oracle Database Mobile Server on the device when it synchronizes.

  4. Install the mobile client. For all platforms, except installing WinCE on ActiveSync, go to the directory where you saved the setup executable file. Double-click the file to execute it.

  5. Enter the user name and password for the mobile user.

    Note:

    For the restrictions on creating the user name and password, see Section 4.3.1.2.1, "Define User Name and Password" in the Oracle Database Mobile Server Administration and Deployment Guide.

  6. You may be required to select the type of privilege under which to install the mobile client. This may already be designated by the administrator in the INF file before installation or the current user may have a privilege that defaults to a certain privilege for the installation.

    • All Users—The user installing this mobile client has administrator privileges and can install the mobile client.

    • Current User—Selecting this option designates that the user does not have administrator privileges, but can install and use the mobile client as a single user.

    Note:

    For details on how to designate the user privilege and for more information on user installation types, see Section 7.1, "Customize the Mobile Client Software Installation for Your Mobile Device" in the Oracle Database Mobile Server Administration and Deployment Guide.

    Figure 2-2 Select Installation Privileges

    installation privilege
    Description of "Figure 2-2 Select Installation Privileges"

  7. Provide the client directory name where to install the mobile client.

  8. Once installed, synchronize the mobile client for the first time. During the first synchronization, all applications and data for this user is brought down and installed on your mobile client.

  9. Each platform has further steps. See Table 2-6 for a description of the steps for each platform.

    Note:

    See Section 2.5, "Configuring for Automatic Synchronization When Installing the Client" for directions on how to enable a default synchronization after any client installation on your device.

Table 2-6 Initializing the First Synchronization for Each Mobile Client Platform

Mobile Client Initial Synchronization Details

PocketPC for WinCE devices

Perform the following steps.

  1. If you install the PocketPC platform to ActiveSync, insert the WinCE device in the cradle. ActiveSync performs a synchronization to install Oracle Database Mobile Server on the device.

  2. After the mobile client is installed on the device, start the Device Manager Agent on the device either by selecting Device Manager in the programs group or by executing dmagent.exe, which is in the orace directory.

  3. Enter the user name and password. If the mobile server URL field is empty, provide the URL as well.

    You can either enter the complete URL of the mobile server, the IP address or the hostname of the mobile server. If left off, the prefix "http://" is added automatically. Only use the hostname if the device is properly configured to use DNS name resolution. Otherwise, enter the IP address.

The device is now registered with the mobile server and ready to be used.

All other platforms

Perform the following steps.

  1. Locate the directories where you installed the runtime libraries, and launch the Mobile Sync application.

  2. The mSync dialog appears. Enter the user name and password of the mobile user. If you do not know your user name and password, ask your system administrator, who creates users and assigns passwords to each user. In the Server field, enter the URL for your mobile server. Click Apply and click Sync.

2.3.3.1 Installing Standard SDK Windows Mobile Files for Your Mobile Client

By default, the Windows Mobile 5 (PPC50) and Windows Mobile 6, 6.1 and 6.5 (PPC60) CAB files are installed with the mobile server and thus, are displayed as options on the mobile client setup page. These CAB files are registered with the mobile server. However, if your mobile client is a Standard SDK WinCE 5.0 platform, use one of the WCESTDSDK CAB files contained in the MDK install.

A mobile client platform consists of a CAB file, an Installation Configuration File (INF file) that describes how to install the files, and an INI file that specifies the platform.

The following steps describe how to install the Standard SDK WinCE platform:

  1. The WCESTDSDK CAB file must be copied from the MDK install to either the mobile server or the mobile client, as described below:

    • Option One: Register the WCESTDSDK CAB file on the mobile server. The mobile server client setup page displays the predefined client platforms that you can download and install on your mobile device.

      If you want the Standard SDK WinCE CAB files to be displayed on the mobile server client setup page, then register the desired platform in the mobile server. After registration, the mobile client can download the SDK CAB file from the Client setup page.

      Find the unregistered CAB file for the desired platform and language in the MDK installation in the following directory:

      <ORACLE_HOME>\Mobile\SDK\wince\<platform>\cabfiles

      Copy and rename the CAB file. The CAB files are named <mobile_client>.<language>.<platform>.<cpu>.cab. Rename the CAB file to bdb.cab or sqlite.cab as appropriate and copy it into a subdirectory according to language and client platform type relative to the <app_server_deployment_dir>\mobile\setup directory. Take note of the directory path as you will provide the location of the CAB file in the INF file.

    • Option Two: Copy the desired WCESTDSDK CAB file directly to the mobile client from the <ORACLE_HOME>\Mobile\SDK\wince\<platform>\cabfiles\ directory.

  2. On the mobile server, create an INF file and place it in the appropriate subdirectory according to the language and platform type in the <app_server_deployment_dir>\Mobile\Setup\devmgr directory. The INF file provides the instructions for installing the CAB file on the client platform. You can copy one of the existing INF files, such as the sqlite_std500.inf file. If you want to add additional instructions, copy the file and make sure the INI file refers to the new INF file.

    If you have to modify it for the new platform, make sure that you give it a new name to avoid changing an existing platform. Provide the location of the CAB file—which you found in step 1—in the <file><item><src> and <des> tags, which are described in Section 7.9, "Installation Configuration (INF) File"in the Oracle Database Mobile Server Administration and Deployment Guide.

    The following demonstrates how to specify a CAB file located in the WINCE/<language>/stdsdk500/<cpu> directory, which is relative to the setup directory, and the destination for the CAB file.

    <file>
  <item type='WINCE'>
    <src>/$OS_LANG$/stdsdk500/$CPU$/sqlite.cab</src>
    <des>$APP_DIR$\sqlite.cab</des>
  </item>
</file>

  3. On the mobile server, create an INI file that refers to the INF file for this platform. See Section 2.3.3.1.1, "Defining the INI File" for details.

  4. On the mobile server, register the new platform with the device manager resource loader, which uses the INI script to create a new Platform.

    ORACLE_HOME\mobile\server\admin\dmloader 
        <repository_owner>/<repository_password>@jdbc_url <ini_filename>

    For example, to load the std500.ini file as shown in step 3, perform the following:

    ORACLE_HOME\mobile\server\admin\dmloader 
        <repository_owner>/<repository_password>@jdbc_url std500.ini

    Note:

    if you supply a RAC URL as the JDBC URL, then enclose it within two double-quotes as the operating system treats the equal sign (=) as a delimiter, which truncates the RAC URL and throws the syntax error: unexpected token '('. error

  5. On the mobile server, copy the setup_<language>.exe files to the following directory on the mobile server:

    <app_server_deployment_dir>\Mobile\Setup\devmgr\wince\<platform>\<chipset>\

    For example, registering the wcestd500_sdk CAB file, the setup files should be copied to the following directory:

    <app_server_deployment_dir>\Mobile\Setup\devmgr\wince\ppcstd500\armv4i

  6. Restart the mobile server to see the newly registered platform in the setup GUI.

  7. On the client, open a new browser that points to the setup page to select the newly registered platform with the SDK CAB file.

2.3.3.1.1 Defining the INI File

Create an INI file that refers to the INF file, as well as other attributes. The following shows how the INI file is organized:

# List platforms to be created in the [Platform] section
#
# Format: platform_name;language
[PLATFORM]
# Provide string to be displayed in the setup UI
PLATFORM1;LANGUAGE 
#
# Platform details. One entry for each platform listed in the 
#[PLATFORM] Section. Provide the same info but prepend with "PLATFORM."
[PLATFORM.PLATFORM1;LANGUAGE]
TYPE=OS_CPU_LANGUAGE_NAME
INF=file.inf
BOOTSTRAP=dmcommand
ATTRIBUTES=attribute1=value1&attribute2=value2

Where the tags define the following:

  • PLATFORM: Provide the platform type and language separated by a semi-colon.

  • TYPE: Provide a name for the platform that is a concatenation of the operating system, CPU, language, and name—where each are separated by an underscore—such as WINCE_ARMV4I_US_SQLite_60.

  • INF: Provide the name of the INF file, such as sqlite_win32.inf or sqlite_linux-x86.inf.

  • BOOTSTRAP: You can find a list of the bootstrap commands in a pull-down in the Mobile Devices page.

  • ATTRIBUTES: The attributes are separated by an ampersand (&). These are the same attributes that are discussed in Section 7.4.3.2, "Create a Custom Platform By Extending an Existing Platform" in the Oracle Database Mobile Server Administration and Deployment Guide and are as follows:

    • Can the device be updated: update=true|false

    • Is the platform enabled: enabled=true|false

    • Can applications on the device be updated: app_upgrade=true|false

    • Should the device manager on the client be started automatically: dmc=auto

For example, the following is an INI file that describes the WinCE Standard SDK 5.00 for ARMV4I:

# Platforms
#
[PLATFORM]
# Windows CE Standard SDK 5.00 - ARMV4I
# Provide string to be displayed in the setup UI 
SQLite WCESTD500 ARMV4I;US 
#
# Windows CE Standard SDK 5.00 ARM V4i
[PLATFORM.SQLite WCESTD500 ARMV4I;US]
TYPE=WINCE_ARMV4I_US_SQLite_60
INF=sqlite_std500.inf
BOOTSTRAP=DeviceInfo
ATTRIBUTES=dmc=auto&update=true&enabled=true

2.4 Configuring the Location of Mobile Client and Database Files

The location of the client database is determined by the DATA_DIRECTORY parameter in the OSE.INI file.

  • All client databases and temporary synchronization data are stored in the DATA_DIRECTORY/sqlite_db/<user> directory, where <user> is the synchronization user id. These are named with the .db extension, such as TERRY\mysqlite.db. These files are used to manage the change control for transactions and synchronization for the user.

  • Internal settings and parameters for the mobile client is stored in the DATA_DIRECTORY/oseconf directory.

The following shows an example of configuring the client database directory on a Win32 platform:

[SQLITE]
DATA_DIRECTORY=C:\mobileclient\sqlite

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

2.5 Configuring for Automatic Synchronization When Installing the Client

In the default configuration, mobile clients do not automatically synchronize after you install the client. However, for Win32, WinCE, Windows Mobile or Linux platforms, you can modify your configuration to automatically synchronize each client after it is installed, as follows:

  1. Logon to the mobile server as an administrator and launch the Mobile Manager tool.

  2. Click on Mobile Devices, followed by Administration.

  3. Click on Command Management.

  4. Edit the Command Device Info (Retrieve device information).

  5. Insert 'Synchronize' as a Selected Command and click Apply to accept the changes.

See Section 7.5, "Sending Commands to Your Mobile Devices" in the Oracle Database Mobile Server Administration and Deployment Guide for more details on sending commands to your mobile device.

2.6 Uninstalling the Mobile Client

When you want to uninstall the mobile client, execute the uninst.exe that is located in the install directory for the mobile client.