The Offline Instantiation (OLI) utility enables mobile administrators to prepare a batch package that includes the mobile client software and initial data for every mobile user. The OLI package can be used to set up a mobile client with user-specific initial data. This procedure helps users avoid an expensive initial synchronization download to the mobile client.
The following sections discuss the Offline Instantiation feature.
Section 8.1, "Using Offline Instantiation to Distribute Multiple Mobile Clients"
Section 8.2, "Setting Up the Mobile Server Host and Mobile Development Kit Host"
Section 8.3, "Downloading the Mobile Client SETUP Executable"
Section 8.5, "Using the OLI Engine to Create and Package the Client Distribution File"
Section 8.6, "Deploying Client Distribution Files on Client Machines"
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 with the initial data can be a performance issue. In this case, the administrator can pre-create either just the mobile client binaries or the mobile client binaries with the user database files, including the user data. 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 into a single directory. Offline instantiation is part of the Mobile Development Kit and is only supported on a Windows platform. We recommend that you use the same Windows environment where a mobile server exists to create your distribution files.
When you have multiple users who use the same application, you set up a distribution for each user through the following steps:
Create application: Using the Mobile Manager on the mobile server, the administrator sets up the application and the users for the mobile client distribution, as follows:
Using the Mobile Manager on the mobile server, the administrator publishes the applications that are to be installed on the mobile clients.
The administrator creates all of the users for the mobile clients.
The administrator grants access for these users to the applications that are to be downloaded for the distribution.
Download the setup.exe file: On the Windows machine where the Mobile Development Kit is installed, download the mobile client binary (setup.exe) from Mobile Manager. Choose the Windows platform and language that are appropriate for the mobile clients that you are creating.
Configure the oli.ini file: Configure the oli.ini file to tell the offline instantiation batch tool how to create the client distribution packages. See Section 8.4, "Configure How OLI Creates the Client Distribution Packages With the OLI Configuration File" for directions.
Execute the OLI utility: Use the offline instantiation tool (OLI) to create and package the final client distribution packages for each user. See Section 8.5, "Using the OLI Engine to Create and Package the Client Distribution File" for directions.
Distribute the package: Distribute the client distribution packages to each user to install on their client device. See Section 8.6, "Deploying Client Distribution Files on Client Machines" for directions.
To set up the mobile server host and the Mobile Development Kit (MDK) host, perform the following steps:
Note:
Do not install a mobile client on the same machine as the Mobile Development Kit where OLI will be executed. If a mobile client is present, uninstall it before running OLI.Install the mobile server and Mobile Development Kit.
The disk where Mobile Development Kit is installed must have sufficient free space as this is the staging area where all client binaries and database files are created before they are copied to the final package. The free space should exceed the total data to be packaged for all clients combined plus 200 MB. For example, if you want to package 50 clients where each uses 20 MB of data, then you need at least 1.2 GB of free space (50 x 20 MB + 200 MB = 1.2 GB).
Start the mobile server.
Create the appropriate users, publications, and subscriptions on the mobile server. Subsequent operations are carried out on the MDK host. The MDK host contains a sample OLI configuration file named oli.ini and the OLI batch file named oli.bat at the following location:
ORACLE_HOME\Mobile\Sdk\bin
On the Windows machine where the Mobile Development Kit is installed, download setup.exe into an empty directory—such as C:\olisetup—from the mobile server setup page. The setup.exe can be downloaded from the following URL:
http://<mobile_server>:<port>/mobile/setup
From the Setup UI, choose the appropriate mobile client. The full path where you install the setup.exe must be specified in the SETUP_PATH parameter in the OLI.INI file. Refer to Section 8.4.1, "SETUP" for more information on this parameter.
The offline instantiation tool, OLI, reads the oli.ini file to determine how many users, the names of those users, the location of the mobile client binaries, and so on. Before you use the offline instantiation tool, make sure that you set up these parameters correctly.
The offline instantiation tool and configuration file is located in the Mobile Development Kit, under ORACLE_HOME\Mobile\Sdk\bin\. Thus, make sure that you have installed the Mobile Development Kit.
The following describes how to configure the OLI.INI file:
The SETUP section contains the general configuration for OLI to create the client packages.
Define the absolute location where you downloaded the client setup.exe, as described in Section 8.3, "Downloading the Mobile Client SETUP Executable".
SETUP_PATH=C:\olisetup\setup.exe
Provide the mobile server host and port that the mobile clients will connect to for synchronization. You can supply a host name or an IP address. The default port number is 80. Sync server must be running when OLI is launched.
MOBILE_SERVER=myhost.us.oracle.com:80
If you are going to use SSL, set to YES. Default is NO.
USE_SSL=NO
Configure the JDBC URL to the Oracle database or Oracle RAC database where the mobile server repository exists. For example, the following is for an Oracle database whose host, port and SID are myhost.us.oracle.com, 1521 and orcl.
JDBC_URL=jdbc:oracle:thin:@myhost.us.oracle.com:1521:orcl
If the repository exists in an Oracle RAC database, then the JDBC URL for an Oracle RAC database can have more than one address in it for multiple Oracle databases in the cluster and follows this URL structure:
jdbc:oracle:thin:@(DESCRIPTION= (ADDRESS_LIST= (ADDRESS=(PROTOCOL=TCP)(HOST=PRIMARY_NODE_HOSTNAME)(PORT=1521)) (ADDRESS=(PROTOCOL=TCP)(HOST=SECONDARY_NODE_HOSTNAME)(PORT=1521)) ) (CONNECT_DATA=(SERVICE_NAME=DATABASE_SERVICENAME)))
Configure the mobile server administration schema name and password for the mobile server repository.
SCHEMA=MOBILEADMIN_SCHEMA PASSWORD=MOBILEADMIN_PASSWORD
The OLI package directory is a location where all the individual client packages are placed during the offline instantiation process. This directory must be located on a drive with adequate free disk space for all client databases. Configure this directory in the OLI_CDS_ROOT directory.
From this final directory—where OLI places all of the client distribution packages for each user—you can distribute the packages to each user.
OLI_CDS_ROOT=C:\OLI_CDS
This specifies the type of device to which the client distribution packages are installed. You cannot install the packages to multiple platforms. Provide device platform strings. Platform types are created by identifying the language and the mobile client database as follows:
Note:
Currently, only Windows platforms are supported.
WIN32_X86_<LANGUAGE>_<DB>
The components of each of section for the device can be as follows:
Table 8-1 Device type platform components
| Component | Options |
|---|---|
|
|
JA, ES, KO, DE, US, FR, IT, ZHS, PTB |
|
|
BDB, SQLite |
For example, a US Berkeley DB Mobile Client device type is as follows:
DEVICE_TYPE=WIN32_X86_US_BDB
The USERS section defines the users and their passwords. For each user, OLI creates a client distribution package that contains the mobile client binaries. The clients must have been created on the mobile server, as described in Section 8.1, "Using Offline Instantiation to Distribute Multiple Mobile Clients". On each line, put the user name and password, as follows:
[USERS] CONSC1 MANAGER CONSC2 MANAGER
For each user, a client distribution package is created.
The following sample configuration file is available on the MDK host at ORACLE_HOME\Mobile\Sdk\bin\
######################################################################### # # OLI.INI # Oracle Database Mobile Server Offline Instantiation Configuration File # Copyright © 1997-2011 Oracle Corporation. # All Rights Reserved. # ######################################################################### # # There are two sections whose names are enclosed in square # brackets: [SETUP] and [CLIENTS]. # Lines starting with a "#", ";", "--" or "//" are comments. # # # Site specific parameters. # The format for this section is <PARAMETER> = <VALUE> # [SETUP] # Absolute path of setup downloaded from mobile server # SETUP_PATH=C:\olisetup\setup.exe # # The mobile server name or IP. If on a port other than 80, append ":<port>". # Sync server need be running when OLI is launched. # MOBILE_SERVER=hostname.domain:80 # # If the mobile server port specified above is secure, set "USE_SSL" to "YES". # Otherwise, use "NO". # USE_SSL=NO # # The mobile server database repository JDBC URL, mobileadmin schema and password # JDBC_URL=jdbc:oracle:thin:@hostname.domain:1521:orcl SCHEMA=MOBILEADMIN_SCHEMA PASSWORD=MOBILEADMIN_PASSWORD # Each user has its own package created under <OLI_CDS_ROOT>/<USERNAME>. # OLI_CDS_ROOT=C:\OLI_CDS # # The device type of the targeted mobile client machines. # DEVICE_TYPE=WIN32_X86_US_BDB # # List of clients to be instantiated. The clients must have been created # on the Mobile Server. # The format for this section is <CLIENTID> <PASSWORD> # Passwords are required # [USERS] CONSC1 MANAGER CONSC2 MANAGER CONSC3 MANAGER
The OLI engine reads the file oli.ini in the current directory for information related to configuration settings. Before launching the OLI engine, you must edit the oli.ini file, as described in Section 8.4, "Configure How OLI Creates the Client Distribution Packages With the OLI Configuration File". The OLI engine uses two repository tables— C$OLI_CLIENTS and C$OLI_SETUP—that store information related to resuming OLI tasks during interruptions or failures.
The OLI engine provides commands that enable you to create and populate the client database files, create packages for mobile clients, and cleanup OLI tables. As a normal practice, execute them in the given order.
The OLI engine relies on a few Java classes and native libraries. To make the Java libraries and native libraries accessible to the OLI engine, the software contains a batch file named oli.bat, in which the necessary environment variables are set. Using the oli.bat file is recommended instead of directly using the Java class used by OLI, oracle.lite.sync.OLI_Win32.
To launch the OLI engine using the Command Prompt window, locate the directory ORACLE_HOME\Mobile\Sdk\bin and execute the oli.bat file at the Command Line.
This action displays the following usage information.
Note:
You execute only ONE of the following commands at a time:makedb, package, cleanup, or checkstatus. Do NOT execute oli.bat with more than one of these commands. You will notice that the instructions show how to create the offline instantiation packages by executing oli.bat several times—once for each command.Usage ----- oli.bat [-g] [makedb] [package] [cleanup] [checkstatus]
The -g command option for oli.bat turns on debugging.
Note:
Before executing themakedb or package command on WinCE or Win32 devices, ensure that you set the DEVICE_TYPE parameter in the oli.ini file.To carry out OLI tasks, re-execute the command using the appropriate switches and arguments.
The following sections describe how to build the client installation package:
Section 8.5.1, "Create and Populate Client Database Files with the MAKEDB Command"
Section 8.5.3, "Clean Up the OLI Tables Before Executing OLI for Another Distribution"
Creates and populates the client database files with the makedb command. For each user defined in the [USERS] section of the oli.ini file, OLI creates the client database files for subscribed publications.
Usage
oli.bat [-g] makedb
You can see the state of the client distribution files by executing the checkstatus command (see Section 8.5.4, "Check the Status of OLI Clients").
After creating the client database file, execute the package command, which packages up the client database file and the mobile client binaries for each user defined in the [USERS] section in the oli.ini file.
Note:
During execution of this command, some setup dialogs will display to show information on the installation or download activities. This is part of the packaging and therefore should not be disturbed in any way even if it takes a few minutes.Each client package is written to a subdirectory of the client; the subdirectory is defined in the OLI_CDS_ROOT parameter in the oli.ini file.
oli.bat [-g] package
After a client package is successfully processed, its status is changed to PACKAGE. You can see the state of the client distribution files by executing the checkstatus command (see Section 8.5.4, "Check the Status of OLI Clients").
The cleanup command cleans the OLI tables. The cleanup command purges the OLI tables. Execute this command before executing OLI for another distribution. There is no need to execute cleanup if you are not going to execute OLI for another distribution.
oli.bat [-g] cleanup
Check the status of OLI clients with the checkstatus command. The initial status of a client is RESET. After the first client is processed successfully by makedb, its status changes from RESET to SLUG. After all of the other clients are replicated using the first client, their status changes from RESET to ODBMADE. Finally, when the OLI engine packages the client information into a directory, the status changes to PACKAGE.
oli.bat checkstatus
Once you have the client packages ready, you can distribute them to your users either by putting the distribution files on a CD for them or by giving the user access to the distribution files over the network or through email. Whether you use the CD or provide your users access to the distribution directory, the client must have network access to the mobile server. When using OLI to register the client, the connection is used to propagate the initial synchronization of data.
When you finish packaging the users using the OLI command, a directory is created in the OLI_CDS_ROOT directory for each user. In each subdirectory, the distribution files, with a setup.exe, is written. The user can execute the setup.exe directly from this subdirectory over a network, you can zip up all of these files and send the ZIP file to the user over email, or you can copy all of the files to a CD for each user. Once the user has access to the distribution files, the user executes the setup.exe to install the mobile client binaries.
To deploy on native Win32 client devices, perform the following steps.
After a successful server side Offline Instantiation process, each client is provided with a one-click installable package in the directory specified by the parameter named OLI_CDS_ROOT in the oli.ini file. The client sub-directory (package) is named after the client name. Provide each user with the client distribution package; for example, copy the client package to the client machine.
On the client device, perform the following:
If you have a mobile client installed, uninstall the existing software.
From the client distribution package, run setup.exe.