The Offline Instantiation (OLI) utility enables Mobile administrators to prepare a package that includes the Mobile client software and initial data for every Mobile user in batch mode. In offline mode, this package can be used to set up a Mobile client with user-specific initial data within Oracle Database Lite. This procedure helps users avoid an expensive online synchronization process as part of the first time Mobile client setup procedure.
The following sections discuss the Offline Instantiation feature.
Section 9.1, "Using Offline Instantiation to Distribute Multiple Mobile clients"
Section 9.2, "Setting Up the Mobile Server Host and Mobile Development Kit Host"
Section 9.3, "Downloading the Client Binaries Into the Client Root Directory"
Section 9.6, "Using the OLI Engine to Create and Package the Client Distribution File"
Section 9.7, "Deploying Client Distribution Files on Client Machines"
Section 9.8, "Creating a Single Package for Users That Share Data"
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 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.
When you have multiple users who use the same application, you set up a distribution for each user through the following steps:
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.
On the Windows machine where the Mobile Development Kit is installed, perform a normal client installation and synchronization for one of your users as a template for the client distribution. Choose the platform and language that are appropriate for the Mobile clients that you are creating, except for the WinCE platform. To set up the Mobile client on the WinCE (PocketPC) device, choose the Oracle Lite WIN32. For steps on creating a Mobile client, see Section 2.1, "Preparing the Device for a Mobile Application" and Section 2.2, "Installing the Mobile Client Software".
Download the Mobile client binaries—without the application or user data—in a unique directory. See Section 9.3, "Downloading the Client Binaries Into the Client Root Directory" for directions.
Configure the oli.ini
file to tell the offline instantiation batch tool how to create the client distribution packages. See Section 9.5, "Configure How OLI Creates the Client Distribution Packages With the OLI Configuration File" for directions.
Use the offline instantiation tool (OLI) to create and package the final client distribution packages for each user. See Section 9.6, "Using the OLI Engine to Create and Package the Client Distribution File" for directions.
Distribute the client distribution packages to each user to install on their client device. See Section 9.7, "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.
Install the Mobile Server and Mobile Development Kit.
Start the Mobile Server.
Create the requisite clients, publications, and subscriptions on the Mobile Server. Subsequent operations, such as Mobile Client installation and OLI command execution, 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
To download the Mobile client binaries into the Mobile client root directory, the administrator performs the following:
Download setup.exe
from the Mobile Server setup page, which is available at the following URL:
http://<mobile_server>:<port>/webtogo/setup
Choose the appropriate Oracle Database Lite Mobile client. For example, choose Oracle Lite Branch Office for Branch Office applications, Oracle Lite WEB for Web applications, Oracle Lite WEB BC4J for Web applications that use BC4J, and the Oracle Lite WIN32 for WinCE (Pocket PC) and Win32 applications.
You use the same setup.exe
that installs a client, but instead, install the client into a directory that will be used as a template for all of the clients you will be distributing.
Run the setup.exe
using the distribution (-d
) flag as follows.
C:\CDSETUP\setup.exe -d
Note: This program creates asetup.exe icon in the same folder to which you downloaded the executable. Running this without the -d flag, by double-clicking the icon, for instance, performs a normal setup of the client on your machine. The -d option must be used to create the necessary files for an offline install. |
Enter your user name and password.
The Choose Directory screen prompts you for a destination directory where you want to create the client bundles. Ensure that you create a new destination directory other than the directory in which the setup.exe
file resides. The appropriate files are copied to the destination directory.
The install directory specified during this process is defined as MOBILECLIENT_CD_ROOT
in the OLI configuration file (oli.ini
). Once the client directory is established, the configuration file should be updated accordingly. All client databases will be instantiated in this directory. Hence, it is important to ensure adequate disk space availability.
Note: Ensure that theMOBILECLIENT_CD_ROOT distribution directory is different from the MOBILECLIENT_ROOT directory.
See Section 9.5, "Configure How OLI Creates the Client Distribution Packages With the OLI Configuration File" for information on the elements in the |
Finally, download the cilent binaries from the Mobile Server by successfully synchronizing the Mobile client with the Mobile Server. Using the msync.exe
application (or the Web-to-Go client if it is the designated platform), initiate the synchronization process for one of the subscribing clients. It may be necessary to uninstall the existing Mobile client before running the Mobile client setup.exe
. Synchronizing before offline instantiation accomplishes two things: the synchronization process validates the setup and downloads any application files that are associated with the subscription that should be included in the client bundle.
Note: This only downloads the binaries for the Mobile client. The user data and applications are installed with the OLI process, as defined in Section 9.7, "Deploying Client Distribution Files on Client Machines". |
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. In the file oli.ini
, this directory is called OLI_CDS_ROOT
.
See Section 9.5, "Configure How OLI Creates the Client Distribution Packages With the OLI Configuration File" for information on the elements in the oli.ini
file.
Note: Ensure that this directory is different fromMOBILECLIENT_CD_ROOT and MOBILECLIENT_ROOT . |
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.
MOBILE_SERVER
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
USE_SSL
If you are going to use SSL, set to YES. Default is NO.
USE_SSL=NO
JDBC_URL
Configure the JDBC URL to the Mobile Server Repository.
JDBC_URL=jdbc:oracle:thin:@myhost.us.oracle.com:1521:oid
SCHEMA and PASSWORD
Configure the Mobile Server administration schema name and password for the Mobile Server Repository.
SCHEMA=MOBILEADMIN_SCHEMA PASSWORD=MOBILEADMIN_PASSWORD
MAKEODB_METHOD
The MAKEODB_METHOD
parameter defines how the client Oracle Lite databases are populated. The default and more performant option is JDBC
, which transfers the data for all clients from the repository over a JDBC connection. Otherwise, you can configure SYNC
, which uses the client-server synchronization for each individual client to generate the Oracle Lite databases.
MAKEODB_METHOD=JDBC
OLITE_JDBC_DRIVER
The OLITE_JDBC_DRIVER
parameter defines the JDBC driver type for the connections to Olite client databases. Valid values are NATIVE
and ODBC
.
NATIVE
: The default; use the Oracle Database Lite native driver.
ODBC
: use the SUN JDBC-ODBC bridge.
OLITE_JDBC_DRIVER=NATIVE
MOBILECLIENT_ROOT
OLI needs to know where you installed the template Mobile client. This is the client that you installed in Section 9.3, "Downloading the Client Binaries Into the Client Root Directory". This Mobile client is for a user that is identical to all of the other users that will use this distribution. Thus, OLI uses this Mobile client as the template for how to build the distribution.
MOBILECLIENT_ROOT=C:\MOBILECLIENT
MOBILECLIENT_CD_ROOT
OLI needs to know where you installed the Mobile client binaries when you executed setup -d
. Configure the directory that you specified in Section 9.3, "Downloading the Client Binaries Into the Client Root Directory". OLI packages these binaries with the same configuration as designated by the Mobile client installed in the MOBILECLIENT_ROOT
directory for each user defined in the USERS
section.
MOBILECLIENT_CD_ROOT=C:\MOBILECLIENT_CD
SHARED_CD_MODE
If set to YES, then only one generic client CD is generated and placed in the <OLI_CDS_ROOT>/Shared_CD
. This CD only contains shared data. If set to NO, then each user has its own package created under the <OLI_CDS_ROOT>/<username>
.
OLI_CDS_ROOT
This is the final directory where OLI places all of the client distribution packages for each user. From this directory, you can distribute the packages to each user.
OLI_CDS_ROOT=C:\OLI_CDS
DEVICE_TYPE
This specifies the type of device to which the client distribution packages are installed. You cannot install the packages to multiple platforms. Instead, choose one of the following:
WIN32
: Windows 32
WTG
: Web-to-Go client, Branch Office
WCE
: Windows CE (PocketPC)
DEVICE_TYPE=WIN32
THREADS
You can specify the number of threads OLI can use to process all of the users listed in the OLI.INI
file. The more threads you allow, the more users can be processed concurrently.
The USERS
section defines the users and their passwords. For each user, OLI creates a client distribution package that contains the Mobile client binaries as well as the user applications and data. The clients must have been created on the Mobile Server, as described in Section 9.1, "Using Offline Instantiation to Distribute Multiple Mobile clients". On each line, put the username 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 10g Lite Offline Instantiation Configuration File # Copyright © 1997-2004 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] # # 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:oid SCHEMA=MOBILEADMIN_SCHEMA PASSWORD=MOBILEADMIN_PASSWORD # # The method used to populate client databases. Valid values are "SYNC" and "JDBC". # "SYNC": use client-server synchronization to generate ODBs. # "JDBC": use JDBC to transfer data from server repository to client. # If clients subscribe to same data for some tables, "JDBC" is faster since they are # transferred only once for all clients. # MAKEODB_METHOD=JDBC # # The JDBC driver type for the connections to Olite client databases. Valid values are "NATIVE" and "ODBC". # "NATIVE": use Olite native driver. # "ODBC": use SUN JDBC-ODBC bridge. # OLITE_JDBC_DRIVER=NATIVE # # The destination directory for the Olite Mobile client installation. # This is the directory when you run "setup.exe" without any options. # MOBILECLIENT_ROOT=C:\MOBILECLIENT # # The directory of the Olite Mobile client installation package. # This is the destination directory when you run "setup.exe" with an option "-d". # MOBILECLIENT_CD_ROOT=C:\MOBILECLIENT_CD # If set to YES only one generic client CD is generated and place in # <OLI_CDS_ROOT>/Shared_CD. This CD only contains shared data. If set to NO, # each user has its own package created under <OLI_CDS_ROOT>/<USERNAME>. # SHARED_CD_MODE=NO # # The Directory where OLI puts the client instantiation packages. # Under this directory, each instantiated client will have a sub directory # which can be copied to a CD to be used for Mobile client installation # on the client machine. Client ODBs are included. # OLI_CDS_ROOT=C:\OLI_CDS # # The device type of the targeted Mobile client machines. # Use "WIN32" for win32 native, # use "WTG" for webtogo client deployments and # use "WCE" for pocket pc # DEVICE_TYPE=WIN32 # # The number of clients to be processed concurrently # THREADS=1 # # 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 MANAGERCONSC3 MANAGERCONSC4 MANAGERCONSC5 MANAGERCONSC6 MANAGERCONSC7 MANAGERCONSC8 MANAGERCONSC9 MANAGERCONSC10 MANAGERCONSC11 MANAGERCONSC12 MANAGERCONSC13 MANAGERCONSC14 MANAGERCONSC15 MANAGERCONSC16 MANAGERCONSC17 MANAGERCONSC18 MANAGERCONSC19 MANAGERCONSC20 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 9.5, "Configure How OLI Creates the Client Distribution Packages With the OLI Configuration File". 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.
Note: Before launching the OLI engine, you must do the following:
|
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.
Note: Shut down the Web-to-Go client prior to executing theoli.bat file. |
This action displays the following usage information. NOTE: You execute only ONE of the following commands at a time: makeodb
, package
, cleanup
, or check status
. 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 [-d] [-i] [-g] [makeodb] [package] [cleanup] [check status] -g Debug mode
The command options for oli.bat
are as follows:
-d
: If your oli.ini
configuration file (see Section 9.5, "Configure How OLI Creates the Client Distribution Packages With the OLI Configuration File") is not in the default directory, specify where it is located with this flag.
-i
: If you renamed the oli.ini
file to another name, specify the name with this option.
-g
: Turn on debugging.
To carry out OLI tasks, re-execute the command using the appropriate switches and arguments.
To build the client installation package, perform the following:
Section 9.6.1, "Create and Populate Client Database Files with the MAKEODB Command"
Section 9.6.3, "Clean Up the OLI Tables Before Executing OLI for Another Distribution"
Note: Before executing themakeodb and package commands on WinCE or Win32 devices, ensure that you set the DEVICE_TYPE parameter to WCE , WTG , or Win32 in the oli.ini file. |
Creates and populates the client Oracle Lite database 'odb' files. 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] makeodb
The initial status of a client is RESET
. After the first client is processed successfully by makeodb
, then 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
.
You can see the state of the client distribution files by executing the checkstatus
command (see Section 9.6.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. Each client package is written to a subdirectory of the client name under the directory defined in the OLI_CDS_ROOT
section in the oli.ini
file.
Usage
oli.bat [-g] package
After a client package is successfully processed, its status is changed to PACKAGED
. You can see the state of the client distribution files by executing the checkstatus
command (see Section 9.6.4, "Check the Status of OLI Clients").
The cleanup
command cleans the OLI tables. The cleanup
command re-creates the OLI tables. Execute this command before executing OLI for another distribution. Do not execute this command without a need to start again.
Usage
oli.bat [-g] cleanup
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 and the user applications and data.
The deployment process for WinCE applications are different from those of native Win32 applications and Web-to-Go applications. The following sections describe how the user would install the distribution files on these devices:
Section 9.7.1, "Deploy Win32 Native or Web-to-Go Client Distribution Package"
Section 9.7.2, "Deploy WinCE PocketPC Client Distribution Package"
To deploy on client devices for native Win32 applications or Web-to-Go applications, perform the following steps.
After a successful server side OFF_LINE 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
.
To deploy on PocketPC client devices for WinCE applications, perform the following steps.
Install the Mobile client for Windows CE onto the CE device.
After a successful server-side OFF_LINE INSTANTIATION
process, each client contains a package in the directory, which is specified by the parameter 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. Copy the client package to the ORACLE_HOME
directory of the Pocket PC device.
Perform a synchronization.
Instead of creating a separate package for each user, with its own data, you can create a single package for users that share data. Then, once installed, the user can log on and retrieve any data that is unique to the user.
Follow the same directions as if you were creating the multiple packages, with the following differences:
In the Mobile Server configuration, configure the MAGIC_CHECK
parameter in the Data Synchronization Instance parameters. See Section 6.3, "Configuring Data Synchronization" on where the Instance parameters are modified in the Mobile Manager. Modify the MAGIC_CHECK
parameter to be NONSHARED
. See the description of the MAGIC_CHECK
parameter in Section B.6, "[CONSOLIDATOR]".
Configure only a single username in the list of users at the end of the oli.ini
file. See Section 9.5, "Configure How OLI Creates the Client Distribution Packages With the OLI Configuration File" for an example.
Configure the SHARED_CD_MODE
element in the oli.ini
file to YES
. See Section 9.5, "Configure How OLI Creates the Client Distribution Packages With the OLI Configuration File" for an example.
After you complete the packaging of the offline instantiation by executing the oli.bat
package command (see Section 9.6, "Using the OLI Engine to Create and Package the Client Distribution File"), then copy the contents of the <OLI_CDS_ROOT>/SHARED_CD
directory onto a CD.
Place the CD into the CD drive of the client device, change directory to the CD and execute the following:
Note: 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. |
setup.exe setup.inf <username> <password>
After you have finished installing all of your clients and have performed the first synchronization for each of them, change the MAGIC_CHECK
parameter in the Data Synchronization Instance parameter bakc to the default of ALL
.