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. 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 initial synchronization download to the Mobile client.
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 or Shared CD 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 with the initial data can be a performance issue. In this case, the administrator can pre-create either just the Mobile binaries or the Mobile binaries with the user ODB files (includes the data for the user) for 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 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.
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 4.1, "Preparing the Device for a Mobile Application" and Section 4.2, "Installing the Mobile Client" in the Oracle Database Lite Getting Started Guide.
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 (Windows Mobile) 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 oli.ini file.
Finally, download the client binaries from the Mobile Server by successfully synchronizing the Mobile client with the Mobile Server. Using the msync.exe application (or either of the OC4J or Web-to-Go clients), 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 the client data (ODB 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 is 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.
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 Mobile Server Repository.
JDBC_URL=jdbc:oracle:thin:@myhost.us.oracle.com:1521:oid
Configure the Mobile Server administration schema name and password for the Mobile Server Repository.
SCHEMA=MOBILEADMIN_SCHEMA PASSWORD=MOBILEADMIN_PASSWORD
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
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
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
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
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>.
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
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
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. 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 Windows Mobile # 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:Ensure that the JDK version is 1.4 or later.
Ensure that the mobile devices for each user that will be a part of the OLI are NOT disabled.
Edit the oli.ini file. The OLI engine uses two repository tables that store information related to resuming OLI tasks during interruptions or failures. These tables are C$OLI_CLIENTS and C$OLI_SETUP.
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.
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 OC4J or 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.
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.
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.
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 binaries.
The deployment process for WinCE clients are different from those of native Win32 clients and Web-to-Go clients. 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 platform or Web-to-Go clients, 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 clients, 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 WinCE device.
Perform a synchronization.
OLI enables an administrator to prepare a CD for each user, which contains the Mobile client binaries and the user's data in ODB files. This process creates one package, or one CD, for each user and may have the following drawbacks:
When there are a large number of users, the OLI process may be slow, resource intensive and error-prone.
When most of the initial data is the same for all users and in read-only lookup tables, generating separate CDs is not necessary.
Once a CD is used, the CD cannot be re-used for re-installation in cases like Mobile client corruption. If you try to re-use a CD, then a complete refresh may be triggered.
In shared CD mode, a generic CD is produced that contains the Mobile client binaries and shared data. The shared CD can be used and re-used by all users. Users need to specify the appropriate username and password during installation. The first synchronization after the install will bring down user-specific data and new shared data.
Follow the same directions as if you were creating the multiple packages, with the following differences:
Set the Instance Parameter MAGIC_CHECK to NONSHARED. The MAGIC_CHECK parameter enables you to control the magic number checking of publication items. If magic check is enabled for a publication item and there is a mismatch between server and client magic numbers, the publication item receives a complete refresh.
When you set this to NONSHARED, then the magic check is enabled only for non-shared publication items. See Section 5.5, "Configuring Data Synchronization For Farm or Single Mobile Server" on where the Instance parameters are modified in the Mobile Manager. See the full description of the MAGIC_CHECK parameter in Section A.7, "[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.