3 Installing the Oracle Lite Database

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, you can install the Oracle Lite database on the following Mobile client platforms:

Windows clients (such as OC4J, Web-to-Go, Branch Office, and BC4J): The applications built for these clients use a Java browser.
Linux, Win32, WinCE, and Windows Mobile clients: These applications are client/server applications. Thus, start the application as you would start any application on these platforms.

Note:

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

When you install the Mobile client, Oracle Database Lite installs an Oracle Lite database within ODB and OBS files with an automatic name and assigns a data source name (DSN). For details on the client Oracle Lite database, see Section 2.1, "Oracle Database Lite Overview" in the Oracle Database Lite Administration and Deployment Guide.

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

Section 3.1, "Preparing the Device for a Mobile Application"
Section 3.2, "Installing the Oracle Lite Mobile Client Software"
Section 3.3, "Configuring for Default Sync When Installing the Client"
Section 3.4, "Configuring the Client for Secure Socket Layer (SSL)"
Section 3.5, "Specifying Whether the Client Uses a Static or Dynamic (DHCP) IP Address"
Section 3.6, "Using Offline Instantiation to Distribute Multiple Mobile Clients"

See Chapter 6, "Managing Your Oracle Lite Mobile Client" for instructions on how to perform certain functions on 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.

3.1 Preparing the Device for a Mobile Application

In order for a device to execute Mobile applications, you must do the following:

Note:

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

Install the Oracle Lite Mobile client software that is appropriate to the client platform on your client machine. For example, install either the Mobile Client for Win32, Mobile client for OC4J or Web-to-Go on a Windows 32 client machine.

See Section 3.2, "Installing the Oracle Lite Mobile Client Software" 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.

3.2 Installing the Oracle Lite Mobile Client Software

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

We do not support the following configuration scenarios:

An Oracle Lite Mobile client and the Mobile Development Kit (MDK) cannot be installed on a single system.
A client user cannot have more than one device.

Note:

If you are installing a Mobile Client for Web-to-Go, follow the instructions provided in Section 3.2.1, "Installing Web-to-Go on Linux" before downloading 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 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 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 3-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 Windows CE with the Platform pull-down menu.

For the Windows and WinCE platforms, the Pocket PC 2003 (PPC2003), Pocket PC SDK 5.0 (PPC50), and Windows Mobile 6 Professional SDK (PPC60) client platforms are provided in the Mobile client setup page. In addition, these client CAB files are optimized for size to minimize the footprint on your device; thus, they exclude Java, msql or utility support. Thus, you may have to perform one or more of the additional steps:
- 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 3.2.2, "Installing Standard SDK WinCE 5.0 CAB Files for Your Mobile Client".
- If you want the Java, msql, or utility support on any Windows or WinCE Mobile client; then install the tools CAB file for that platform as described in Section 3.2.3, "Installing Tools CAB Files for Java, MSQL, and Utility Support".
When you select the language, the collation sequence for the Oracle Lite database is also preconfigured for you. You can also specify the collation sequence with the NLS_SORT parameter. You can only perform a linguistic sort on Oracle Lite databases that have the collation sequence of FRENCH, GERMAN, CZECH, OR XCZECH. You cannot do a linguistic sort on a BINARY collation sequence, which is used with all languages, except the three previously listed. For more details on linguistic sort, see Section 4.4, "Support for Linguistic Sort" in the Oracle Database Lite Client Guide.

Note:
Only the Mobile Development Kit has the full National Language Support for (Traditional and Simplified) Chinese, Japanese, and Korean (CJK). All other components, including Mobile clients, support CJK without the Traditional Chinese language. However, the Simplified Chinese language is supported.

Figure 3-1 Mobile Client Setup Page

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

Note:
Available clients may differ from what is shown above.
Click the Mobile client for your language and client platform.

Note:
There are two client versions for the Web-to-Go model. The Oracle Lite WEB and the Oracle Lite WEB OC4J. Use Oracle Lite WEB OC4J when you need full J2EE 1.3 compliance. The original Oracle Lite Web client uses the Oracle Lite Servlet engine, which does not support all features for J2EE 1.3. The Oracle Lite WEB OC4J uses the OC4J stack within OracleAS; thus, you have full J2EE 1.3 support. However, you also must create the client according to OC4J/J2EE specifications.
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, you install any of the Oracle Lite Windows Mobile platforms to ActiveSync. Then, when the device is put into the cradle, ActiveSync installs the Oracle Database Lite onto 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 for itself as well as any members that may be associated with the user.
  
  Note:
  After installing a user with administrative privileges, you can add member users to allow multiple users on a Mobile client. The member user has its own username/password, but executes any synchronization and modifications under the user's authority. For information on how to install and use member users, see Section 5.3.3, "Adding New Members and Associating Them With Their User" in the Oracle Database Lite Administration and Deployment Guide.
- 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 3-2 Select Installation Privileges

Description of "Figure 3-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 3-1 for a description of the steps for each platform.

Note:
See Section 3.3, "Configuring for Default Sync When Installing the Client" for directions on how to enable a default synchronization after any client installation on your device.

Table 3-1 Initializing the First Synchronization for Each Mobile Client Platform

Oracle Mobile Client Initial Synchronization Details

Oracle Mobile Client	Initial Synchronization Details
Oracle Lite WEB or Oracle Lite WEB OC4J, both for Web-to-Go support	The synchronization step takes place when you click Next, after executing the `setup.exe`. This prompts you to login to the Mobile client for OC4J or Web-to-Go. If you want to synchronize at another time, do the following: Open a browser to the Mobile client. For example, if you install a Web client with port 8080, point the browser to `http://localhost:8080/webtogo`. Log in with the username/password for the Mobile user. Click Sync on the tabs in the upper right corner.
Oracle Lite 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 Oracle Database Lite is installed on the device, then start the Device Manager Agent on the device by either selecting Oracle DM 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.

Oracle Lite WEB or Oracle Lite WEB OC4J, both for Web-to-Go support

The synchronization step takes place when you click Next, after executing the setup.exe. This prompts you to login to the Mobile client for OC4J or Web-to-Go. If you want to synchronize at another time, do the following:

Open a browser to the Mobile client. For example, if you install a Web client with port 8080, point the browser to http://localhost:8080/webtogo.
Log in with the username/password for the Mobile user.
Click Sync on the tabs in the upper right corner.

Oracle Lite 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 Oracle Database Lite is installed on the device, then start the Device Manager Agent on the device by either selecting Oracle DM 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.

3.2.1 Installing Web-to-Go on Linux

Perform the following to install and run Web-to-Go on Linux.

WARNING:

If you are testing the Oracle Database Lite on Suse Linux, you must do the following before installation:

ln -s /usr/lib/libssl.so.0.9.7 /usr/lib/libssl.so.4
ln -s /usr/lib/libcrypto.so.0.9.7 /usr/lib/libcrypto.so.4

Once the installation is complete, perform your tests and then remove the soft links, as these may cause problems with other programs you have installed on your machine. This instruction is only for testing and should not be a permanent option.

Download the Web-to-Go setup executable by clicking the "Oracle Lite Linux WEB" link on the Mobile Server setup page.
After the download is complete, set execution permissions on the setup executable with chmod 755 setup.
Execute the setup command, as follows:
```
./setup 
```
To start Web-to-Go in the debug mode, do the following:
```
cd $OLITE_HOME/bin
./webtogo -d0
```
To start Web-to-Go in the daemon mode, do the following:
```
cd $OLITE_HOME/bin
./webtogo
```
To kill Web-to-Go, which is in the daemon mode, do the following:
```
cd $OLITE_HOME/bin
./webtogo -k
```

To uninstall Web-to-Go and delete the database files, perform the following:

cd $OLITE_HOME
./uninst

The dmagent is automatically launched in a daemon mode when setup is executed. However if you want to restart it, first kill the current process and then perform the following:

cd $OLITE_HOME/bin
./dmagent

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

Note:

All CAB files on either the Mobile Server or MDK do not include Java, mSQL or utility support. For information on how to install these utilities, see Section 3.2.3, "Installing Tools CAB Files for Java, MSQL, and Utility Support".

An Oracle Database Lite 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 CAB files are named olite.<language>.<platform>.<chipset>.CAB. Rename the CAB file to olite.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 olite.<language>.<platform>.<chipset>.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$/olite.cab</src>
    <des>$APP_DIR$\olite.cab</des>
  </item>
</file>
```
On the Mobile Server, create an INI file that refers to the INF file for this platform. See Section 3.2.2.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.

3.2.2.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_OLITE_STD500.
INF: Provide the name of the INF file.
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 
Oracle Lite WCESTD500 ARMV4I;US 
#
# Windows CE Standard SDK 5.00 ARM V4i
[PLATFORM.Oracle Lite WCESTD500 ARMV4I;US]
TYPE=WINCE_ARMV4I_US_OLITE_STD500
INF=std500.inf
BOOTSTRAP=DeviceInfo
ATTRIBUTES=dmc=auto&update=true&enabled=true

3.2.3 Installing Tools CAB Files for Java, MSQL, and Utility Support

The Tools CAB file provides Java, msql, and utility support on the client devices. If you want to use tools on your Mobile client, then install the tools CAB file. This CAB file is installed as an application on your Mobile client.

The following sections describe the steps to create and publish the tools CAB file as an application for the Mobile client:

Section 3.2.3.1, "Defining the Tools CAB as an Application in Packaging Wizard"
Section 3.2.3.2, "Assigning the Tools CAB to the User"

3.2.3.1 Defining the Tools CAB as an Application in Packaging Wizard

Perform the following to install the Tools CAB, if must be published as an application:

Start the Packaging Wizard.
Select Create New Application Definition. Click OK
Select the platform for the specific CAB—such as Oracle Lite PPC60 ARMV4I: US. Click Next.
Fill in the CAB file details. The following example provides CAB file details for the Oracle Lite PPC60 ARMV4I: US platform.
- Application Name: tools cab ppc60 armv4i
- Virtual Path: /toolscab_ppc60_armv4i
- Description: ppc60 armv4i tools cab
- Local Application Directory: Click Browse. Select the path where the tools CAB file exists.
Click Next. The files are now listed under the specified directory.
Delete the file entries other than those for the tools CAB.
Click Next until you reach the DDL panel.
Click Finish.
Publish the application through one of the following options:
- Select Create Files option to create a JAR file.
- Select Publish the Current Application option on the server.

3.2.3.2 Assigning the Tools CAB to the User

Once published, assign the application containing the Tools CAB to the Mobile client user:

Select the Applications tab in the Mobile Manager.
Click on the Tools CAB file description. In our previous example, this was tools cab ppc60.armv4i.
Select the Access tab.
Select the user or group to which this application should be available for download.
Click Save to save the preferences.

3.3 Configuring for Default Sync When Installing the Client

In the default configuration, all Mobile clients do not automatically synchronize after you install the client. However, you can modify your configuration to automatically sync 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.

3.4 Configuring the Client for Secure Socket Layer (SSL)

As the end user, you can configure the Mobile client for OC4J or Web-to-Go to establish an SSL connection between the Mobile client and the Mobile Server. A complete description of how to configure your Mobile client to use SSL is described in Section 11.4.6, "Client-Side Configuration for Secure Socket Layer (SSL)" in the Oracle Database Lite Administration and Deployment Guide.

3.5 Specifying Whether the Client Uses a Static or Dynamic (DHCP) IP Address

Use the IP_CONFIG parameter in the server webtogo.ora file to specify the method the client uses to retrieve its IP address. Your client device can use either a static IP address or a dynamic (DHCP) method in retrieving an IP address. If you are using DHCP, then you need to set this parameter to DYNAMIC; the default is STATIC.

If you are using DHCP, then the underlying code needs to know to not use the IP address that was used for the previous connection/synchronization. If you are using DHCP and have set this parameter to STATIC, your synchronization may never occur, since it is probably trying to synchronize to an IP address that is no longer valid for this device.

You set this parameter in the server webtogo.ora file, so that the Mobile Server knows if the client is DHCP, then may have a different IP address each time.

For more information, see Section A.2, "WEBTOGO" in the Oracle Database Lite Administration and Deployment Guide.

3.6 Using Offline Instantiation to Distribute Multiple Mobile Clients

You can enable your users to install their client using a distribution method, such as a CD, through the network, or email. To install the Mobile client and perform the first synchronization to retrieve the applications (with the initial data) can be a performance issue. In this case, the administrator pre-creates the Mobile binaries with the user ODB files (includes the applications and data for the user) to the client. The download of this package is faster than having each user perform the first synchronization on their device. Thus, this procedure helps users avoid an expensive performance hit when creating and synchronizing the Mobile client for the first time.

Offline instantiation is a tool that enables an administrator to gather and package the Mobile client binaries and the user applications and data into a single directory. Offline instantiation is part of the Mobile Development Kit, which can be installed only on a Windows platform. Thus, you create all of your user distribution files on a Windows machine and you can only create multiple user distribution files for OC4J, Web-to-Go, Branch Office, Win32, and WinCE Mobile clients. We recommend that you use the same Windows environment where a Mobile server exists to create your distribution files.

See Chapter 10, "Offline Instantiation" in the Oracle Database Lite Administration and Deployment Guide for full instructions on how to use the Offline Instantiation engine to create and deploy multiple clients.