2 Installing the SQLite 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. When you install the SQLite Mobile client, Oracle Database Lite installs the Sync Engine.

The following sections detail how to install the SQLite Mobile client software on your client machine:

Section 2.1, "Supported Platforms and Requirements for the SQLite Mobile Client"
Section 2.2, "Preparing the Device for a Mobile Application"
Section 2.3, "Installing the SQLite Mobile Client"
Section 2.4, "Configuring the Location of the SQLite Database and Mobile Client Files"
Section 2.5, "Configuring for Automatic Synchronization When Installing the Client"

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

2.1 Supported Platforms and Requirements for the SQLite Mobile Client

In general, you can synchronize data in an installed SQLite database on the following Mobile client platforms:

Blackberry and Android devices
Windows clients
Linux, Win32, and WinCE clients

Note:

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

Automatic synchronization and device management are only available on certain SQLite Mobile client platforms. Table 2-1 displays what features are available on which platforms.

Table 2-1 Platform Restrictions

Platform	Automatic synchronization	Device management through the DM Agent
Blackberry	No	No
Android	No	No
Win32	Yes	Yes
WinCE	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 SQLite Mobile client. The requirements do not include the SQLite database requirements, but are only the requirements for the SQLite Mobile client including the Sync Engine.

Table 2-2, "BlackBerry and Android Platform Requirements"
Table 2-3, "Software Requirements for Windows Mobile Clients"
Table 2-4, "Supported and Certified Technologies for Native Mobile Clients"
Table 2-5, "Pocket PC and Windows Mobile Supported Platforms"

Table 2-2 BlackBerry and Android Platform Requirements

Platform	Minimum OS Version	Minimum Storage for Mobile Client
BlackBerry	RIM 5.0	100 KB
Android	Android 1.5	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 Vista Ultimate, Windows XP Professional Edition with Service Pack 2, or Windows 2003	If using Java APIs for synchronization, use JRE 5.0 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 synchronization, use either IBMJ9 or the CrEme JDK version 4.1 from `NSI.com`. ActiveSync version 3.8 or higher. Microsoft .NET Compact Framework 1.0
Windows Mobile	Windows Mobile 2003 Windows Pocket PC 2003 Windows Mobile 2003, 2nd edition Windows Pocket PC 2003, 2nd edition See Table 2-5, "Pocket PC and Windows Mobile Supported Platforms" for full details.	If using synchronization, use either IBMJ9 or the CrEme JDK version 4.1 from `NSI.com`. ActiveSync version 3.8 or higher. Microsoft .NET Compact Framework 1.1
	Windows Mobile 5 Windows Mobile 5 for Pocket PC Windows Mobile 5 for Pocket PC Phone Edition Windows Mobile 5 AKU2	If using synchronization, use either IBMJ9 or the CrEme JDK version 4.1 from `NSI.com`. 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 synchronization, use either IBMJ9 or the CrEme JDK version 4.1 from `NSI.com`. 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 SQLite 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.

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

Device Platform Supported Technologies Certified Technologies

Device Platform	Supported Technologies	Certified Technologies
Win32	Sun Microsystems Java Runtime Edition 5.0 ADO.Net 1.1 – requires Microsoft .Net Framework 1.1 or 2.0 ADO.Net 2.0 – requires Microsoft .Net Framework 2.0
Windows CE	ADO.Net 1.1 (Requires Microsoft Compact .Net Framework 1.0 + Service Pack 2) or 2.0 ADO.Net 2.0 – requires Microsoft .Net Compact Framework 2.0 Microsoft ActiveSync version 3.8 or for Windows CE 5.0, use Microsoft ActiveSync version 4.1 or higher.	Oracle Database Lite is certified with the following JVMs on Windows Mobile 2003 Second Edition: IBM J9 Websphere Everyplace Micro Environment for Windows Mobile 2003 ARM Personal Profile Creme JVM 4.1, which can be obtained at `http://www.nsicom.com`
Linux x86	RedHat Enterprise Linux AS release 4	JavaSoft Java Runtime Edition 1.4.2

Win32

Sun Microsystems Java Runtime Edition 5.0
ADO.Net 1.1 – requires Microsoft .Net Framework 1.1 or 2.0
ADO.Net 2.0 – requires Microsoft .Net Framework 2.0

Windows CE

ADO.Net 1.1 (Requires Microsoft Compact .Net Framework 1.0 + Service Pack 2) or 2.0
ADO.Net 2.0 – requires Microsoft .Net Compact Framework 2.0
Microsoft ActiveSync version 3.8 or for Windows CE 5.0, use Microsoft ActiveSync version 4.1 or higher.

Oracle Database Lite is certified with the following JVMs on Windows Mobile 2003 Second Edition:

IBM J9 Websphere Everyplace Micro Environment for Windows Mobile 2003 ARM Personal Profile
Creme JVM 4.1, which can be obtained at http://www.nsicom.com

Linux x86

RedHat Enterprise Linux AS release 4

JavaSoft Java Runtime Edition 1.4.2

For each native platform, a CAB file is downloaded from the setup page. The naming structure for each CAB file is as follows: sqlite_sync.<language>.<platform>.<cpu>.cab

Table 2-5 Pocket PC and Windows Mobile Supported Platforms

Product Name	WinCE Version	Chipsets	SQLite Client CAB file download from Setup page
Pocket PC 2003 Windows Mobile 2003	4.20.1081	ARMV4	SQLite PPC2003 ARMV4, which uses the `sqlite_sync.<language>.ppc2003.armv4.cab`
Windows Mobile 2003 2nd Edition	4.21.1088	ARMV4	SQLite PPC2003 ARMV4, which uses the `sqlite_sync.<language>.ppc2003.armv4.cab`
Windows Mobile 5 and Windows Mobile 5 AKU2	5.0 and 5.1.465	ARMV4I	SQLite PPC50 ARMV4I, which uses the `sqlite_sync.<language>.ppc50.armv4i.cab`
Windows Mobile 6	5.2.1236	ARMV4I	SQLite PPC60 ARMV4I, which uses the `sqlite_sync.<language>.ppc60.armv4i.cab`

2.2 Preparing the Device for a Mobile Application

To execute Mobile applications on a device with the SQLite database, do the following:

Note:

Install the SQLite Mobile client for any application after the application is published.

Install the SQLite 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 SQLite Mobile Client" for a full description.
Download the user applications and its associated data.

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

Notes:
For the restrictions on creating the username and password, see Section 5.3.1.2.1, "Defining Username and Password" in the Oracle Database Lite Administration and Deployment Guide.
For more information about synchronization, see Chapter 6, "Managing Synchronization" in the Oracle Database Lite Administration and Deployment Guide.
You can now launch your applications from your client machine or from your Mobile device.

2.3 Installing the SQLite 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.

The following sections provide directions for the SQLite Mobile client install:

Section 2.3.1, "Installing the SQLite Mobile Client on Blackberry Devices"
Section 2.3.2, "Installing the SQLite Mobile Client on Android Devices"
Section 2.3.3, "Installing the SQLite Mobile Client for Win32, WinCE, Windows Mobile or Linux"

2.3.1 Installing the SQLite Mobile Client on Blackberry Devices

To install the SQLite 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.

On the Blackberry device, open a browser to point to the Mobile Server setup page using the following URL.

http://<mobile_server>:<port>/webtogo/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.
Click the SQLite Mobile client for your language and the Blackberry client platform. This downloads and installs the SQLite Mobile client.
Perform a manual synchronization for the SQLite Mobile client.
Synchronization requires you to enter the username 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 username and password, see Section 5.3.1.2.1, "Defining Username and Password" in the Oracle Database Lite Administration and Deployment Guide.

2.3.2 Installing the SQLite 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 SQLite Mobile client binaries unless they are downloaded within the context of a signed application.

Thus, the instructions for installing the SQLite Mobile client on Android devices is described within the context of creating and downloading the Android application. These instructions are described in Chapter 4, "Using an Android Application on the SQLite Mobile Client".

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

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

To install the SQLite 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, or Linux SQLite Mobile client, see Section 7.1, "Customize the Mobile Client Software Installation for Your Mobile Device" in the Oracle Database Lite Administration and Deployment Guide.

On the SQLite Mobile client, open a browser to point to the Mobile Server using the following URL.

http://<mobile_server>:<port>/webtogo/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. You can select another language than English on the Language pulldown.

For viewing platforms, you can choose to see all available platforms for the indicated language, or only those platforms for Windows or WinCE with the Platform pull-down menu.

Client platforms are provided in the Mobile client setup page for the Windows and WinCE platform: Pocket PC 2003 (PPC2003), Pocket PC SDK 5.0 (PPC50), and Windows Mobile 6 Professional SDK (PPC60). In addition, these client CAB files are optimized for size to minimize the footprint on your device.

If you are using a client with the Standard SDK for WinCE 5.0 platforms for Windows Mobile 5 (WCESTDSDK), then 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 WinCE 5.0 CAB Files for Your Mobile Client".

Figure 2-1 Mobile Client Setup Page

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

Note:
Available clients may differ from what is shown above.
Click the SQLite Mobile client for your language and client platform.
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 Lite Windows Mobile platforms to ActiveSync. Then, when the device is put into the cradle, ActiveSync installs the Oracle Database Lite on the device when it synchronizes.
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.
Enter the username and password for the Mobile user.

Note:
For the restrictions on creating the username and password, see Section 5.3.1.2.1, "Defining Username and Password" in the Oracle Database Lite Administration and Deployment Guide.
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 Lite Administration and Deployment Guide.

Figure 2-2 Select Installation Privileges

Description of "Figure 2-2 Select Installation Privileges"
Provide the client directory name where to install the Mobile client.
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.
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

SQLite Mobile Client Initial Synchronization Details

SQLite Mobile Client	Initial Synchronization Details
SQLite PocketPC for WinCE devices	Perform the following steps. If you install the PocketPC platform to ActiveSync, insert the WinCE device in the cradle. ActiveSync performs a synchronization to install Oracle Database Lite on the device. After SQLite Mobile client is installed on the device, then start the Device Manager Agent on the device by either selecting Device Manager in the programs group or by executing `dmagent.exe`, which is in the `orace` directory. Enter the username, password and Mobile Server URL. 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. Locate the directories where you installed the runtime libraries, and launch the Mobile Sync application. 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.

SQLite PocketPC for WinCE devices

Perform the following steps.

If you install the PocketPC platform to ActiveSync, insert the WinCE device in the cradle. ActiveSync performs a synchronization to install Oracle Database Lite on the device.
After SQLite Mobile client is installed on the device, then start the Device Manager Agent on the device by either selecting Device Manager in the programs group or by executing dmagent.exe, which is in the orace directory.
Enter the username, password and Mobile Server URL.

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.

Locate the directories where you installed the runtime libraries, and launch the Mobile Sync application.
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 WinCE 5.0 CAB Files for Your Mobile Client

By default, the Windows 2003, Windows Mobile 5 and Mobile 6 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 SQLite 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:

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 client 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 SQLite CAB files are named sqlite_sync.<language>.<platform>.<cpu>.cab. Rename the CAB file to sqlite_sync.cab and copy it into a subdirectories according to language and client platform type relative to the <ORACLE_HOME>\mobile_oc4j\j2ee\mobileserver\applications\mobileserver\setup\ directory. Take note of the directory path as you will provide the location of the CAB file in the INF 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. Each CAB file is named sqlite_sync.<language>.<platform>.<cpu>.cab.
On the Mobile Server, create an INF file and place it in the appropriate subdirectory according to the language and platform type in the ORACLE_HOME\mobile_oc4j\j2ee\mobileserver\applications\mobileserver\setup\dmc 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 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.10, "Installation Configuration (INF) File"in the Oracle Database Lite 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_sync.cab</src>
    <des>$APP_DIR$\sqlite_sync.cab</des>
  </item>
</file>
```
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.
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

On the Mobile Server, copy the setup_<language>.exe files to the following directory on the Mobile Server:

<ORACLE_HOME>\mobile_oc4j\j2ee\mobileserver\applications\mobileserver \setup\dmc\wince\<platform>\<chipset>\

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

ORACLE_HOME\mobile_oc4j\j2ee\mobileserver\applications\mobileserver \setup\dmc\wince\ppcstd500\armv4i

Restart the Mobile Server to see the newly registered platform in the setup GUI.
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

C reate 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_OLITE_STD500.
INF: Provide the name of the INF file, such as sqlite_win32.inf or sqlite_linux.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 Lite 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_OLITE_STD500
INF=std500.inf
BOOTSTRAP=DeviceInfo
ATTRIBUTES=dmc=auto&update=true&enabled=true

2.4 Configuring the Location of the SQLite Database and Mobile Client Files

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

All SQLite databases and temporary synchronization data are stored in the SQLITE.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 SQLite Mobile client is stored in the SQLITE.DATA_DIRECTORY/oseconf directory.

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

SQLITE.DATA_DIRECTORY=C:\mobileclient\sqlite

For more details on this parameter, see Appendix A, "SQLITE.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:

Logon to the Mobile Server as an Administrator and launch the Mobile Manager tool.
Click on Mobile Devices, followed by Administration.
Click on Command Management.
Edit the Command Device Info (Retrieve device information).
Insert 'Synchronize' as a Selected Command and click Apply to accept the changes.

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