5 Installing Your 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 Mobile clients are as follows:

Note:

On each client device, only one user can be installed for each device; that is, you cannot have multiple users on a single client device. In addition, you can configure only one device for a particular user/Mobile Client combination. That is, you cannot install the same Mobile Client for the same user on more than one device. For example, it is not possible to have two devices both executing a Mobile Client for Web-to-Go for the user JOHN. Server initiated synchronizations, where data changes from the server are automatically synchronized to the device, will not work properly.

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

See Chapter 2, "Managing the Mobile Client" in the Oracle Database Lite Administration and Deployment Guide for instructions on how to perform certain functions on the client. See Chapter 1, "Using the Workspace for Managing the Mobile Server" in the Oracle Database Lite Administration and Deployment Guide for information on how to manage functionality from the Mobile Server.

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

  1. Install the Oracle Database 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 5.2, "Installing the Mobile Client Software" for a full description.

  2. Download the user applications and its associated data.

    Synchronize the Mobile client for the first time. When you sign in with the username/password of the Mobile user who owns the Mobile applications to which this user has access are downloaded. In addition, the data for each application is retrieved.

    Notes:

    The username and password are limited to a maximum of 28 characters.

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

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

5.2 Installing the Mobile Client Software

Before you install the Mobile Client on your device, make sure that there is 1 MB of space available to download the setup.exe. Also, we do not support a configuration scenario where, on a single system, both a Mobile client and the Mobile Development Kit (MDK) is installed.

Note:

If you are installing a Mobile Client for Linux Web-to-Go, follow the instructions provided in Section 5.2.1, "Installing Web-to-Go on Linux" before downloading the setup.exe.

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

  1. 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 5-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.

    NOTE: All displayed CAB files for Windows and WinCE are optimized for size to minimize the footprint on your device; thus, no Java, msql or utility support are provided in these CAB files. If you want Java, msql, or utility support; then, before you install the client software, you must replace the lighter CAB file with the full featured SDK CAB file, as described in Section 5.2.2, "Use SDK CAB Files for Client Install for Java, MSQL, and Utility Support".

    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.

    When you select the language, the collation sequence for the Oracle Lite database is also preconfigured for you. 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.

    Figure 5-1 Mobile Client Setup Page

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

    Note:

    Available clients may differ. See Oracle Database Lite Administration and Deployment Guide for more information.

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

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

  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 username and password for the Mobile user. On each client device, only one user can be installed for each device; that is, you cannot have multiple users on a single client device.

    Note:

    The username and password are limited to a maximum of 28 characters long.

  6. Provide the client directory name where to install the Mobile client.

  7. 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. See Table 5-1 for a description of synchronization for each platform.

    Note:

    See Section 5.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 5-1 Initializing the First Synchronization for Each Mobile Client Platform

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:

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

  2. Log in with the username/password for the Mobile user.

  3. Click Sync on the tabs in the upper right corner.

Oracle Lite PocketPC for WinCE devices

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 executing dmagent.exe, which is in the orace directory.

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.

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

  1. Set the following environment variables:

    • Set OLITE_HOME to where Oracle Database Lite is installed, such as /home/<user>/olite

    • Set JAVA_HOME to the Java installation directory

    • Add the following to the LD_LIBRARY_PATH$JAVA_HOME/jre/lib/i386 $JAVA_HOME/jre/lib/i386/server $OLITE_HOME/bin

    • Add $OLITE_HOME/bin to the PATH

  2. Download the Web-to-Go setup executable by clicking the "Oracle Lite Linux WEB" link on the Mobile Server setup page.

  3. After the download is complete, set execution permissions on the setup executable with chmod 755 setup.

  4. Execute the setup command, as follows:

    ./setup

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

5.2.2 Use SDK CAB Files for Client Install for Java, MSQL, and Utility Support

The Windows and WinCE CAB files that are included, by default, in the client installation setup directory does not include Java, msql, and utility support in order to reduce the footprint on the client devices. If you want to be able to download the full featured SDK CAB files, perform one of the following:

5.2.2.1 Downloading SDK CAB Files for PPC50 ARMV4I and PPC2003 ARMV4

The SDK CAB files are installed with the MDK install.

  1. Copy and rename the CAB file. The CAB files are named olite.<language>.<platform>.<chipset>_sdk.CAB. Rename the CAB file to olite.cab. The SDK CAB files are installed with the MDK in the following directory:

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

    After renaming to olite.cab, copy the SDK CAB file to the appropriate directory depending on the device software and language, as follows:

    • Oracle Lite PPC50 ARMV4I: Copy the olite.cab file to the <ORACLE_HOME>\mobile_oc4j\j2ee\mobileserver\applications\mobileserver\setup\<language>\stdsdk500\armv4i\ directory.

    • Oracle Lite PPC2003 ARMV4: Copy the olite.cab file to the <ORACLE_HOME>\mobile_oc4j\j2ee\mobileserver\applications\mobileserver\setup\<language>\stdsdk500\armv4\ directory.

    You are replacing the smaller CAB files with the SDK CAB files.

  2. On the client, open a new browser that points to the setup page to pull down the platform with the SDK CAB file.

5.2.2.2 Downloading SDK CAB Files for WCESTD500 ARMV4I and WCESTD500 X86

The WCESTD500 SDK CAB files will not show up in the setup UI unless you create a platform for them. For a full description, see Section 7.5.4.3.2, "Register the WCESTD500 SDK CAB Files with Java, msql, and Utility Support" in the Oracle Database Lite Administration and Deployment Guide.

5.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:

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

5.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 12.1.4, "Client-Side Configuration for Secure Socket Layer (SSL)" in the Oracle Database Lite Administration and Deployment Guide.

5.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.1, "WEBTOGO" in the Oracle Database Lite Administration and Deployment Guide.

5.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 8, "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.