8 Manage Your Devices

When you install your Mobile client software, the Mobile device management client software is automatically installed and, in most cases, bootstrapped. Within the Mobile Manager, the administrator can send commands to remote devices. The next time that the device is available—either through wireless connection or synchronization—the command that you send will execute.

The following sections describe how to manage your devices:

Section 8.1, "Installing the Mobile Client Software on Your Mobile Device"
Section 8.2, "Modifying Environment on Your Mobile Clients During Installation"
Section 8.3, "Viewing Device Information"
Section 8.4, "Configuring and Customizing Your Mobile Device Platform"
Section 8.5, "Configuring Your Mobile Devices"
Section 8.6, "Sending Commands to Your Mobile Devices"
Section 8.7, "Enabling Device Software Updates"
Section 8.8, "Using the Device Management Client GUI to Manage Device on Client-side"
Section 8.9, "Managing the Network Protocol Between the Device and the Mobile Client Software"
Section 8.10, "Installation Configuration (INF) File"
Section 8.11, "Defining Device Manager Commands With the Device Manager OTL Tag Language"

8.1 Installing the Mobile Client Software on Your Mobile Device

The Mobile device software for your language and platform is installed when you install the Mobile client on your device. See Chapter 2, "Installing Mobile Clients" for more information.

You can customize the installation for your Mobile clients by customizing the platform and the setup configuration files for the platform, as follows:

Certain modifications can be made to the Mobile client configuration files during installation. See Section 8.2, "Modifying Environment on Your Mobile Clients During Installation" for more information.
Customize the platform to install additional binaries, applications, and other environment modifications. See Section 8.4, "Configuring and Customizing Your Mobile Device Platform" for more information.

Once installed, you can manage the client using the Oracle Lite Device Manager tool. See Section 8.8, "Using the Device Management Client GUI to Manage Device on Client-side" for more information.

8.2 Modifying Environment on Your Mobile Clients During Installation

The Mobile client installs a few configuration files on your clients. These configuration files are discussed more in the Oracle Database Lite Developer's Guide.However, you can add name/value pairs to the webtogo.ora, POLITE.INI and ODBC.INI files on the client file, which are available in Windows under %WINDIR% directory and in Linux under $OLITE_HOME/bin directory, by modifying the INF file corresponding to the Oracle Database Lite platform that is to be downloaded to the client. You can add the new configuration directly in the <ini> section of the INF file by editing the INF file yourself or you can add them through the Mobile Manager. To edit the INF file directly, see Section 8.10, "Installation Configuration (INF) File".

To edit and add name/value pairs for the webtogo.ora, POLITE.INI, and/or ODBC.INI files, do the following:

Navigate to the Mobile Device screen.
Click Administration.
Click Configuration Management.
Select the INF file from the File Name pull down and click Show. This enables you to modify the INI section in this particular INF file. All of the current assignments are displayed.

For each INF file, the INI section is displayed. You can only add name value pairs to existing sections. For example, the following is the INI section from the webtogo.inf file:
```
<ini>
  <item name="$APP_DIR$\bin\webtogo.ora" section="WEBTOGO">
    <item name="MODE">CLIENT</item>
    <item name="DataDirectory">$APP_DIR$\oldb40</item>
    <item name="PORT" replace="false">$PORT$</item>
    <item name="HTTP_PROXY" replace="false">$HTTP_PROXY$</item>
  </item>
  <item name="$DESKTOP$\Web-to-Go.url" section="InternetShortcut">
     <item name="URL" replace="false">http://localhost:$PORT$/</item>
     <item name="IconFile">$APP_DIR$\bin\webtogo.exe</item>
     <item name="IconIndex">0</item>
  </item>
</ini>
```
There are two sections configured in this INI section: WEBTOGO and InternetShortcut. You can add other sections. The Mobile Manager notes if there are sub-items and will create a heading for the sections. To add more sections, you must modify the INF file directly. To modify or add items to the existing sections, you can click Add. Figure 8-1 displays how the previous INI section is displayed in the Mobile Manager. To add a name/value pair, click Add. To modify a parameter, modify it and click Apply. To delete, select the configuration pair and click Delete.

Figure 8-1 Adding Name/Value Pairs to INF Files

Description of the illustration webinf.gif
To add name/value pairs to the existing sections, click Add.
A screen is displayed asking for two strings: a name and a value. Enter these items and click OK.

8.3 Viewing Device Information

From the Mobile Devices screen, as shown inFigure 8-2, select the device that you want to know more about.

Figure 8-2 Devices Page

Description of the illustration devices.gif

Figure 8-3 shows the specific device page that comes up when you select the device that you are interested in. The Properties screen is the first set of information available.

Figure 8-3 Mobile Device Properties and Information

Description of the illustration deviceinfo.gif

On the Mobile Device Properties screen, you are told the following about the device:

Device Name
Enabled: If the device is enabled. See Section 8.4.2, "Enabling or Disabling All Mobile Devices in a Platform" for more information.
Upgradable: If the device accepts software upgrades. See Section 8.4.3, "Allowing Software Upgrades to All Mobile Devices in a Platform" for more information.
Valid: If the Device Management software is installed and correct. If de-installed, Valid displays No.

Each of the tabs at the top provides more information about the device. Use this information to determine what sort of administration each one needs in order to continue to operate smoothly. You can use this information to tell what needs to be upgraded on each device. The following sections covers each of these tabs.

Section 8.3.1, "Viewing Device Information"
Section 8.3.2, "Viewing Database Information"
Section 8.3.3, "Viewing Software Information"
Section 8.3.4, "Commands"
Section 8.3.5, "Queue"
Section 8.3.6, "Command History"
Section 8.3.7, "Viewing Device Logs"

8.3.1 Viewing Device Information

The Mobile Manager displays general and database information for a chosen device. To view device information, click Device Info. If no information is displayed, click Retrieve Device Information. This sends a command to the device, which is then posted back to this page. Click reload until the information is posted.

In the first section, all of the details about the operating system is provided. You no longer have to go to the machine and type in a command to determine the operating system, its version and the latest service pack applied. This section will provide you with all of this information. In addition, you can see what the host name and IP address is.

The second section details how much memory you have on the device. This includes how much virtual or physical memory are on the device, and how much of that memory is still available.

The third section details the type of processor that is installed on the machine. For example, it describes the type of Intel processor that is installed on your Windows machine. You know exactly when your users must be upgraded to the next version of processor for the capability that they need.

For Windows-based devices only, the fourth section details the version of the JDK that you have installed and where it is installed. You no longer have to ask your users to check which version of JDK that they have installed. For example, in the Oracle Database Lite 10g, if you are using Oracle Application Server (9.0.4), you must be using the JDK 1.4.2. You can view this information for each device and know if the Mobile client software must be upgraded or not. In addition, this section describes the CLASSPATH for the Mobile client environment.

The last section details the amount of storage space that exists and is currently available on each drive.

8.3.2 Viewing Database Information

When you select the Database Info tab, you see all of the information about the Oracle Lite database that is installed on the Mobile client, which uses ODBC.

The first section provides the ODBC driver name, so that you can know which version that is installed on your client. In addition, you can see what DLL is used for the database and the directory.

The second section details each of the user ODB files—that is, the client databases for each application. To validate the file data integrity of the ODB file, select the button next to the ODB file and click Validate.

The third section displays the configuration in raw form in the POLITE.INI file on the client. Each section in the POLITE.INI file is displayed. The purpose of this section is for you to view the sections and parameters in the INI file. The data is shown in raw format.

8.3.3 Viewing Software Information

You can view all of the Oracle Database Lite software that is installed on the Mobile device by clicking Applications, which lists each application, its version, setup time, and location details. If no information is available, click Retrieve Software Information, which sends a command to the device.

Once the information becomes available, which is dependent on when the device reconnects, the platform is listed for the device. Select the platform to see the software information.

8.3.4 Commands

You can send commands to each device by itself or to all devices in a platform to gather information or execute some function. This is described fully in Section 8.6, "Sending Commands to Your Mobile Devices".

8.3.5 Queue

The queue shows any commands that are currently in process. That is, if the device is not currently online, then the command is placed into the queue until the device becomes available. Viewing this queue shows you all of the commands that are queued up waiting for devices.

8.3.6 Command History

This shows all of the commands executed against this device.

8.3.7 Viewing Device Logs

The Mobile Manager displays device logs and synchronization logs from the client device. To view the client device logs, click Device Logs. The Device Logs page lists what activity has occurred on the device. When you click Purge, these logs are removed. To view client device synchronization logs, click Synchronization. This shows only the synchronization requests made by the client.

8.4 Configuring and Customizing Your Mobile Device Platform

As described in Section 2.2, "Installing the Mobile Client Software", you normally install the Mobile client software by choosing the type of Mobile device and the language that you will use. However, you can extend any of these platforms to not only install the Mobile client software for the platform, but also install any of your binaries or applications. The following sections describe how to configure your platform or create and customize a new platform.

Section 8.4.1, "Modifying Platform Properties for Installation"
Section 8.4.2, "Enabling or Disabling All Mobile Devices in a Platform"
Section 8.4.3, "Allowing Software Upgrades to All Mobile Devices in a Platform"
Section 8.4.4, "Extend or Create a Custom Platform"

8.4.1 Modifying Platform Properties for Installation

Before you install a platform on your system, you should ensure that all of the configuration details for the Mobile device setup are what you want. A setup file is used to detail installation details, such as directories, binaries to install, registry to modify, path and CLASSPATH additions, and so on. You can modify the setup INF file that is defaulted for each platform, or you can create your own and point the platform to the new setup INF file.

Generally, you do not want to modify the generic platforms provided for you, in case you need to go back to basics. Thus, you should create your own unique platform by extending one of the provided platforms. This copies the existing platform into a separate platform with your name. Once copied, or extended, modify this platform with your own unique characteristics. For instructions on how to extend one of the provided platforms, see Section 8.4.4, "Extend or Create a Custom Platform".

To modify how the platform is installed, do the following:

Designate the name and path of the setup INF file for your platform by navigating to the Mobile Devices page.

Click Platforms.
Click on the platform for which you are currently modifying the INF file.
Make sure that the correct setup INF file is listed in the Setup INF field.

Note:

If you want to modify this INF file or provide a different INF file, then on the Mobile Server, navigate on the file system to ORACLE_HOME/Mobile/Server/admin/repository/setup/dmc/common to where the setup INF files are located. Open the file that you want to modify or create a new INF file. Add the changes you want for this platform. See Section 8.10, "Installation Configuration (INF) File" for the configuration syntax.

Choose a Bootstrap group command from the list displayed. After the device bootstrap is complete, you can choose a group command to execute when it is completed. For example, choosing the device information command retrieves all of the device information to the Mobile Manager for viewing.
Enable or disable all devices in the platform. If you enable these devices by choosing Yes, then each user can log in, perform updates, synchronize, and perform other duties. If you disable these devices by selecting No, then they can no longer perform work for the user. See Section 8.4.2, "Enabling or Disabling All Mobile Devices in a Platform" for more information.
Set Upgradable to Yes to retrieve all software updates for all devices in the platform. If you want these devices to continue to receive automatic software updates, choose Yes. If you want these devices to stay with the current software versions, choose No. See Section 8.4.3, "Allowing Software Upgrades to All Mobile Devices in a Platform" for more information.

8.4.2 Enabling or Disabling All Mobile Devices in a Platform

You can enable or disable all Mobile devices in a platform. By default, each device in the platform is enabled, which means that the user can synchronize to the database and perform software updates. If you disable the device, then it can no longer perform work for the user. If you wanted to disable a single device—because a user has lost the device or left the company—then you follow the instructions in Section 8.5.1, "Enabling or Disabling a Mobile Device". However, if you want to enable or disable all devices for a platform, then see Section 8.4.1, "Modifying Platform Properties for Installation".

Why would you want to disable all devices in the platform? What if you had created a a customized platform (see Section 8.4.4, "Extend or Create a Custom Platform") for devices that were used for a specific purpose, such as if you had cell phones that were analog only. When you came out with a full digital network, you may not want any of the analog technology to continue to be used. You could choose to send a deinstall command (see Section 8.6, "Sending Commands to Your Mobile Devices") and then disable all of the analog Mobile devices. Since all of them had the same platform, all of them could be disabled at the same time. The user could no longer log in and use the device. They would be forced to upgrade to digital.

8.4.3 Allowing Software Upgrades to All Mobile Devices in a Platform

If you set Upgradable to Yes, then when a new software update comes available—either for the Mobile client software or for any applications installed on the client—then the Mobile device will receive these updates. However, if you want a device to stay with the level of software that is currently installed, then you would change Upgradable to No. See Section 8.5, "Configuring Your Mobile Devices" for where you set whether the software is to be upgraded or not.

8.4.4 Extend or Create a Custom Platform

You can create custom device platforms either by using an existing platform as the template or by enabling a platform.

Only a few of the available platforms are displayed in the Mobile client setup screen. To add a platform that you need, enable the desired platform. See Section 8.4.4.1, "Enable a Platform for Your Mobile Client" for more information.
You can create a new platform by extending one of the existing platforms. This enables you to customize the platform to install additional binaries, applications, or to have specific instructions on modifying the client machine to accommodate your specifications. See Section 8.4.4.2, "Create a Custom Platform By Extending an Existing Platform" for more information.

8.4.4.1 Enable a Platform for Your Mobile Client

Not all of the possible platforms are enabled on the Mobile client setup screen. To enable a platform for your client device, do the following:

On the Mobile Devices screen, click Platforms.
On the Platforms screen in the Search pulldowns, select the language and either Disabled or All and click Go.
Select the platform name that you want to enable.
Enable the device by selecting Yes in the Enable pulldown.
Click OK. The device is now enabled and will be visible in the client setup screen.

8.4.4.2 Create a Custom Platform By Extending an Existing Platform

To create a custom platform, do the following:

Create a new INF file for your extended platform—On the Mobile Server, navigate on the file system to ORACLE_HOME/Mobile/Server/admin/repository/setup/dmc/common to where the setup INF files are located. Create an empty INF file for your new platform. As discussed in Section 8.10, "Installation Configuration (INF) File", when you extend a platform, the INF files that are used for the installation is a concatenation of your platform and every platform that it was extended from—just like how objects extend methods, properties and attributes from each other in an object-oriented language.
On the Mobile Devices screen, click Platforms.
On the Platforms screen, select the platform name and click Extend.
Enter the custom platform name, path, and file name of the blank setup INF file you created in step 1. The setup INF file determines what is installed and how the client machine environment is modified. See Section 8.10, "Installation Configuration (INF) File" for instructions on how to modify the setup INF file after you have completed extending the platform.
Choose a Bootstrap group command from the list displayed. After the device bootstrap is complete, you can choose a group command to execute when it is completed. For example, choosing the device information command retrieves all of the device information to the Mobile Manager for viewing.
Enable or disable the device. If you enable the device by choosing Yes, then the user can log in, perform updates, synchronize, and perform other duties. If you disable the device by selecting No, then it can no longer perform work for the user.
Set Upgradable to Yes to retrieve all software updates for the device. If you want the device to continue to receive automatic software updates for the device, choose Yes. If you want the device to stay with the current software versions, choose No.
Click OK.
After you have extended your platform and given it a unique name, you should modify the setup INF file for this platform.

You are ready to install your customized platform.

8.5 Configuring Your Mobile Devices

Navigate to the Mobile Devices page, as shown in Figure 8-4, and you can modify, delete, and extend any Mobile device.

Figure 8-4 Devices Page

Description of the illustration devices.gif

To modify the configuration of a specific device, select the device and do the following:

The device name is displayed on the first line. You can modify the name of the device to anything that you want. For example, if you have a naming convention for all devices in your organization, modify this field to reflect this convention. The name defaults to the Mobile device platform.
Enable the device by selecting Yes; disable the device by selecting No. See Section 8.5.1, "Enabling or Disabling a Mobile Device" for more information.
Set Upgradable to Yes to retrieve all software updates for the device. If you want the device to continue to receive automatic software updates for the device, choose Yes. If you want the device to stay with the current software versions, choose No. See Section 8.5.2, "Allowing Software Upgrades to the Mobile Device" for more information.
The installed address is displayed in the Address field. If the address is an IP address or a phone number, these may change at some point. You can enter the new addresses in this field.
Choose the Network Provider type. You can choose a different network provider than that with which you chose to install. The default list includes HTTP, WOR_IAS (Wake on Ring with Oracle Application Server), WOR_SMTP (Wake on Ring with SMTP), SMS, or RAPI. If you added another network provider, these custom network providers will also be included in the list.

Note:
To create a network provider, see Section 8.9, "Managing the Network Protocol Between the Device and the Mobile Client Software".

8.5.1 Enabling or Disabling a Mobile Device

You can enable or disable a Mobile device. By default, the device is enabled, which means that the user can log in, perform updates, synchronize, and perform other duties. If you disable the device, then it can no longer perform work for the user. See Section 8.5, "Configuring Your Mobile Devices" for where you enable or disable the device.

Why would you want to disable the device? If the Mobile device was lost or the user is no longer with the company, but did not return the device, then you might choose to send a deinstall command (see Section 8.6, "Sending Commands to Your Mobile Devices") and then disable the device. This way, the software is no longer on the device and even if the user had another copy of the software to reinstall the application, they could no longer log in and retrieve any information from your company.

8.5.2 Allowing Software Upgrades to the Mobile Device

8.6 Sending Commands to Your Mobile Devices

As an administrator, you can create and send commands to any Mobile device. These commands can do a range of functions. The following sections describe how to send existing commands to devices and how to create new commands for your own purposes:

Section 8.6.1, "Scheduling or Sending Commands"
Section 8.6.2, "Modifying Existing Commands"
Section 8.6.3, "Creating New Commands"
Section 8.6.4, "Creating Group Commands"
Section 8.6.5, "Enabling or Disabling Mobile Device Commands"
Section 8.6.6, "Viewing the Mobile Device Command History"

8.6.1 Scheduling or Sending Commands

You can send or schedule a command to be sent from the Mobile Manager. Navigate to the Mobile Devices page.

8.6.1.1 Sending Commands

You can send commands to devices that are installed and registered with the Mobile Manager. You can send these commands from several places.

Sending a command to a single device—To send a command to a single device, select the device from the list displayed on the Mobile Devices page. Select Commands. Under the Send Commands section, choose the command—as designated by the description—and click Send Now. The Mobile Manager seeks your confirmation and then displays a confirmation message.

If the command requires arguments, then the Mobile Manager displays an argument collection page. For example, the Upload File command requires a file name as an argument. To send the command to the device, click Yes.
Sending a command to all devices of the same platform type—To send a command to all devices of a certain platform, click Platform off of the Mobile Devices page. Click the select button next to the desired platform, select the command from the command pull-down list, and click Send Command.

For information on how to create a command, see Section 8.6.3, "Creating New Commands".

8.6.1.2 Scheduling Commands

You can schedule a command to execute at a later time or at certain intervals. Select the device to which you want this command to be directed. Select Commands. Perform the following:

Click Schedule. The Schedule Command page appears.
As shown in Figure 8-5, configure the following:
- The name and descriptor are unique identifiers. You can modify them to your own unique identifiers.
- Choose the command that you want to schedule from the Parameter Command pull-down list.
- Check the Enabled box to enable or disable the command. If disabled, the command cannot be executed.
- Check Save to History if you want to keep a log of when this is executed and the results, which are printed to the Command History screen.
- Choose from the Priority pull-down list if this is to be high, medium, or low priority. This determines in what order the scheduled commands are executed.
- Enter any expected parameter values, separated by semi-colons, in the Extra Parameter field. For example, if you chose the Synchronize databases command and you wanted a fast refresh, you would enter 'fast' in the Extra parameter field.
  
  Note:
  You cannot use fast refresh synchronization with high priority restricting predicate.
Figure 8-5 The General Section of the Command Scheduler

Description of the illustration gensched.gif
As Figure 8-6 shows, enter the timing that the command is to execute. Choose when it is to start, when it will expire (if it does not execute within a certain time frame), how often it will repeat, and a date and time that it will repeat until.

Figure 8-6 Timing Section of the Command Scheduler

Description of the illustration schedule.gif
Click Apply. The Mobile Manager displays a confirmation message.

8.6.2 Modifying Existing Commands

To view the available commands, select the Mobile Devices tab on the Mobile Manager. Navigate to the Administration page and click the Command Management link. As Figure 8-7 displays, the Command Management page appears.

Figure 8-7 Command Management Page

Description of the illustration comman.gif

Using the Command Management page, you can modify existing device commands and create new device commands. To modify existing commands, do the following:

Click the required Command Name link. The Properties page for this command appears.
Enter the command name, description, and syntax in the corresponding fields. For more information on modifying these fields, see Section 8.6.3, "Creating New Commands".
To check the accuracy of the command syntax, click Syntax Check button. If no errors are found, the Mobile Manager displays a confirmation message.
Click Apply. The Mobile Manager displays a confirmation message.

8.6.2.1 Adding Parameters to Mobile Device Commands

You must configure the command to prompt for expected input parameters. For example, the Synchronize command requires that you define what type of refresh you want: fast, force, or push.

You can specify any parameters by modifying the command, as follows:

Click the required Command Name link. The Properties page for this command appears.
Add the parameter name and values, as follows:
- The parameter name—This is the name specified in the OTL script.
- A short description—The description is what is displayed when the user is prompted for the value of the parameter.
- The display name—This is the description for each value. For example, the Synchronize databases command has three possible values: fast, force or push. However, the display values to describe each of these actual values is Fast Refresh, Force Refresh, and Push Only. These values are separated by a semi-colon, as follows: Fast Refresh;Force Refresh;Push Only.
  
  Note:
  You cannot use fast refresh synchronization with high priority restricting predicate.
- The default values for this parameter—Enter one or more potential values for this parameter, if applicable. For example, the Synchronize databases command values would be fast;force;push. These values are separated by semi-colons and in the same order as the display name. If you do not have definitive values, leave blank and the user will enter their own value.

8.6.3 Creating New Commands

You can create commands using the OTL scripting language, as described in Section 8.11, "Defining Device Manager Commands With the Device Manager OTL Tag Language". These commands are then used to perform activity on the Mobile devices, but controlled by the administrator within the Mobile Manager.

You can create a command with a single or multiple OTL script commands. Each is created in a different manner, as described in the following sections:

To create new commands, click Create Command. Enter a unique Command ID, Command String, and Description in the corresponding fields. Click the Create button. The Mobile Manager displays a confirmation message.

To create a command that has several lines, you must perform the following:

Create a file with an .otl extension with the OTL commands in it. Place this file in the ORACLE_HOMEmobile_oc4j\j2ee\mobileserver\applications\mobileserver\setup\dmc\otl directory.
With any editor, add all OTL commands that you want executed within the file. See Section 8.11, "Defining Device Manager Commands With the Device Manager OTL Tag Language" for a full description of the OTL scripting language.
Within Mobile Manager, navigate to the Command Management page.
Click Create Command.
In the Name field, pick a short name to identify the command within Mobile Manager.
In the Command field, put the name of the OTL file, without the .otl extension.
In the Description field, type in a sentence describing accurately the purpose of the command.
Click OK.
Back on the Command Management screen, select the command that you just created.
Click Syntax Check to ensure that you entered in your OTL commands correctly.
Click Apply.
If you ask the user to enter parameters, then add the parameter definitions. See Section 8.6.2.1, "Adding Parameters to Mobile Device Commands" for a full description.
Push the OTL script to device.

You have now successfully created a new command. You can now execute this command against your Mobile devices. See Section 8.6.1, "Scheduling or Sending Commands" for information on how to execute the command.

8.6.4 Creating Group Commands

To create group commands, do the following:

Click Create Group. The Create Group Command page appears.
Enter a unique Command Name, which will be used to identify the grouping.
Enter a description.
Select the set of existing commands that you want to execute together. The Command Weight feature controls the order in which the commands are executed. For example, a command with Weight 1 is executed first and a command with Weight 2 is executed next. Users must specify a weight for all the commands for the chosen group command.
Click Add. The Mobile Manager displays a confirmation message.

8.6.5 Enabling or Disabling Mobile Device Commands

By default, all commands are enabled, which means that you can execute the command. If you want to disable a command, so that it can no longer be executed, do the following:

From the Mobile Devices page, click Administration.
Choose Command Management.
Select the command that you want to enable or disable.
Select either Yes for enable or No for disable on the Enabled pull-down.
Click Apply.

8.6.6 Viewing the Mobile Device Command History

To view the Device Command History, click the Command History link from the single Mobile device screen. The Command History page lists a history of commands that were implemented for the chosen device. You can delete a single historical message by clicking the select box next to the message and clicking Delete. To delete all messages, click Purge.

8.6.7 Examples of Mobile Commands

The following are examples of commands that you can send to your Mobile device:

To create a command that configures for automatic encryption of a local Oracle Lite database, see Section 6.4.2, "Configuring on the Server for Automatic Encryption of Local Snapshots".
To trigger a synchronization on the client, see Section 2.2.1, "Configuring for Default Sync When Installing the Client".

8.7 Enabling Device Software Updates

This section describes how to enable software updates and patches for your devices. It should be located in Chapter 10 in the Oracle Database Lite Administration and Deployment Guide.

Section 8.7.1, "Enabling Major Software Updates for Your Device"
Section 8.7.2, "Applying Patches or Minor Updates"
Section 8.7.3, "Controlling Device Software Updates"

8.7.1 Enabling Major Software Updates for Your Device

In order to facilitate a major software update, the corresponding INF file must be modified to reflect the new version number. Mobile Server relies on the application version number to determine if the client software is out-of-sync.

To update your software, perform the following:

In the software INF file, the administrator modifies the version number for the application to the current version, as follows.
```
<setup name="Application Name" version="1.2.3">
```
The client user synchronizes with Mobile Server. Alternatively, the client user can invoke update.exe to check for the latest version of the software.

When the client user synchronizes, Mobile Server compares the client application software version number against the version number in the INF file. If the version numbers are different, Mobile Server compares the 'Last Modified Time' of all of the client application files against the server application files to determine the changes and then sends the modified files to the client device.

8.7.2 Applying Patches or Minor Updates

In order to apply specific patches to an existing installation for your application, the application developer creates an INF file with the patch attribute and copies it to the correct platform patch directory, each of which is located in the ORACLE_HOME\j2ee\home\applications\mobileserver\setup\dmc directory in the Mobile Server.

The following application INF file defines the patch element as myFirstApp for applying a patch to "Application Name" software:

<setup name="Application Name" version="1.2.3">
     <property>
        ...
        <patch>myFirstApp</patch>
    </property>
    ...
</setup>

The value in the patch element is a user-defined name. This will be the name of the directory into which the updates for the application are copied. In this example, the updates for "Application Name" are copied into the myFirstApp directory.

Note:

Be careful to have a unique patch directory name for each application. If you have the same directory name in the patch element, then all applications with that patch directory name receive the updates placed there.

In order to update a patch with the olobj40.dll, update the patch INF file as follows:

<setup name="Application Name" version="1.2.3" id='1001'>
   <install>
     <action msg_i='$FILE_I$' msg_u='$FILE_U$'>file</action>
       <file>
         <item>
           <src>/common/win32/olobj40.dll</src>
           <des>$APP_DIR$\bin\olobj40.dll</des>
         </item>
       </file>
   </install>
</setup>

Note:

For a full description of INF files and the elements within them, see the "10.3.2 Installation Configuration (INF) File" section in the Oracle Database Lite Administration and Deployment Guide.

There are two mandatory attributes in a patch INF file, as follows:

The INF file contains a version number, which is the same as the application version number. In the above example, the version number (10.0.0.0.0) tells DMS that the patch is meant for the application version 10.0.0.0.0.
The INF file must have an ID, which is used for determining patch dependencies. This ID can be any number you choose.

If you do have dependencies among patches, then you use the dependency element to indicate these dependencies. For example, the previous patch for olobj40.dll was configured with the ID of 1001. The following INF file configures another patch with ID of 1002. This patch defines a dependency on the patch for olobj40.dll by configuring the ID number of 1001 in the dependency element.

<setup name="Oracle Lite WIN32" version="10.0.0.0.0" id='1002'>
  <property>
    <dependency>1001</dependency>
  </property>
</setup>

Update the patch, as follows:

The administrator copies the patch INF files to the patch directory.
The administrator copies the new application files to the application directory.
The client user synchronizes with Mobile Server. Alternatively, the client user can invoke update.exe to check for the latest version of the software.

The Mobile Server checks for patches and sends all new patches to the client device.

8.7.3 Controlling Device Software Updates

The administrator can control what software updates occur either through modifying the Upgradable switch in the Mobile Manager or by programmatically defining what types of updates can occur. There are two types of software update that you can control, as detailed in the following sections:

Section 8.7.3.1, "Enabling Software Updates for the Oracle Lite Platform"
Section 8.7.3.2, "Updating Application Software On Each Client"

8.7.3.1 Enabling Software Updates for the Oracle Lite Platform

You can disable the Oracle Database Lite platform updates for the devices through one of two methods:

Setting Upgradable to No—Change the value of Upgradable in the Mobile Manager GUI to No, as follows:
1. Select the Mobile Devices tab in Mobile Manager.
2. Select the Platform tab to display all Oracle Lite Platforms.
3. Click Oracle Lite WIN32 platform to display its properties.
4. Change the value of Upgradable to No. Click OK.
Setting the UPDATE_SOFTWARE attribute in the Resource Manager to false. This has to be set programmatically on the Resource Manager object, as follows:
```
rs.setAttribute (ResourceConst.UPDATE_SOFTWARE, "false");
```

If you want to disable any application updates, but continue to allow Oracle Database Lite platform updates, then set the UPDATE_SOFTWARE_APPS attribute to false.

For example, to set the UPDATE_SOFTWARE_APPS attribute to false, do the following:

rs.setAttribute (ResourceConst.UPDATE_SOFTWARE_APPS, "false");

For a full example of how to set the Resource Manager attributes, see ORACLE_HOME\Mobile\Server\samples\devmgr\java\AppUpdate.java.

8.7.3.2 Updating Application Software On Each Client

You can control whether a new version of an application software is downloaded on each client. Modify the update policy attribute of the user in one of the following ways:

On the user page in the Mobile Manager, set the Software Update pulldown to the appropriate update that you want, as follows:
- All updates—Include major and minor updates.
- Major—The devices attached to this user receives only major software updates. This is the default.
- Minor—The devices attached to this user receives only minor software updates.
- Disable updates—The devices attached to this user does not receive any software updates.
In addition, you can specify the date that the update occurs.
Set the UPDATE_SOFTWARE_APPS policy attribute of the User object to one of the following values to specify what type of update that the client can receive:
- Major—The devices attached to this user receives only major software updates. This is the default.
- Minor—The devices attached to this user receives only minor software updates.
- False—The devices attached to this user does not receive any software updates.
```
user.setPolicy (ResourceConst.UPDATE_SOFTWARE_APPS, "Minor");
```
For a full example of how to set the Resource Manager attributes, see ORACLE_HOME\Mobile\Server\samples\devmgr\java\UserPolicy.java.

Example 8-1 Upgrading Devices Attached to a Specific User

Each user owns one or more devices. You can configure it so certain users do not receive the latest update. The default is that all devices attached to a user receive current updates.

For example, you have two users: John and Tom. You want John's devices to stay at the current version, which is Oracle Database Lite Win32 version 10.0.0.0.0; however, you want Tom's devices to upgrade to the new version, which is Oracle Database Lite Win32 version 10.1.0.0.0. Configure each user's devices, as follows:

For John, configure the update.software.apps attribute to Minor.
For Tom, configure the update.software.apps attribute to Major.

8.8 Using the Device Management Client GUI to Manage Device on Client-side

On any client—except for the Palm clients—you can manage the Mobile device client software, as shown in Figure 8-8.

Figure 8-8 Using the Oracle Lite Device Manager to Manage Your Device

Description of the illustration dmagent.gif

To bring up the Device Manager GUI, choose Oracle Lite Device Manager from the Oracle Database Lite Programs list. The main screen provides information about the following: platform with type of platform, language, and version, the owner/user of this device, the name of the device, and the URL of where the device is installed.

Click Version to see the version number of all Oracle Database Lite software DLLs.
Click Options, which brings up Figure 8-9, to configure the following:
- Enable Pull: If the server cannot connect to the client, any commands sent to the client are placed into the Device Manager command queue. These commands are sent to the client when one of two things occurs:
  - The client synchronizes.
  - A "Pull" is initiated from the client. When you check the Enable Pull checkbox, the device management client automatically polls the Device command queue for any commands for this user. The frequency is the number of seconds to wait between each pull.
- Retry Count: If you have created your own Device Command, this count specifies the number of times that the command is executed, if it fails to execute. If it still fails after retrying, the command is deleted. This count also applies to failed synchronization attempts. The commands are retried with the same frequency interval that is set for the Enable Pull command. A command can fail to execute if there is an error within the command or if there is no connection between the client and the server.
- Check for Update: Select the day and time that you want the device management client to automatically poll for updates. This also occurs anytime you start a synchronization. So, this is useful if you never synchronize with the Mobile Server.
- Proxy Server: If you have a proxy server between the Mobile client and Mobile Server, enter the address and port here.
Figure 8-9 Device Client Manager Options

Description of the illustration dmaoptions.gif
Click Hide to place the Oracle Lite Device Manager in the Windows System Tray.

8.9 Managing the Network Protocol Between the Device and the Mobile Client Software

The Network Management page is where the administrator defines the properties of an installed network provider or register new network providers. A network provider is the protocol that the Mobile client uses to communicate between itself and the Mobile device. The Mobile client software, which is often installed on a Windows system, sends commands to the Mobile device over this protocol. Often, you have a device, such as WinCE or Palm, that interacts with the Mobile client installed on a Windows system.

This network provider definition describes what you have already installed as the protocol between the Mobile client and the device. The frequently-used network providers are as follows:

HTTP—If you use HTTP, you will provide an HTTP URL in the Address field. You cannot use HTTPS between the Device Manager and the Mobile device.

Note:
HTTP may not work if the device does not have a direct IP conection to the Mobile Server.
RAPI—Remote API used by the ActiveSync API, which only supports Pocket PC class devices. These devices connect directly to the computer that is executing the Mobile Server.
- RAPI does not work on LINUX or UNIX-based systems.
- When using RAPI on a Windows machine, install and configure ActiveSync 3.7.1.
- Set CEUTIL.DLL and RAPI.DLL in the %WINDIR%\System32 directory.
- In addition, if your Mobile Server uses Oracle Application Server as its middle-tier solution, set %WINDIR%\System32 in the application server path.
Wake on Ring—If you have a cell phone as a Mobile device, then you would have a network protocol where the cell phone receives incoming data. Thus, the address is a phone number for the cell phone. The cell phone is "woken" when incoming commands are initiated from the Mobile Manager. There are two types of Wake on Ring:
- WOR_SMTP: Wake on Ring over SMTP.
- WOR_IAS: Wake on Ring over Oracle Application Server.
SMS—Short Messaging Service.

To modify or create a new network provider, navigate to the Devices page, click Administration, and click Network Management. The Network Management page lists existing network providers. Select any of these providers to see their properties, which consists of the following:

Java class name: The name of the JAVA class that implements the Network protocol, such as HTTP.Meta data: Any user defined string that is required as input by the JAVA class during the initialization.

To define a new network protocol, do the following:

Create a Network Provider class using Java. This class must implement the oracle.lite.provider.NetworkProvider interface.
Register the Network Provider through the Mobile Manager on the Network Management page, as follows:
1. Click Create on the Network Management page.
2. Input the network provider name, Java class name, and Meta data.
3. Click OK.

8.10 Installation Configuration (INF) File

The Installation Configuration file contains all the instructions required to install or de-install client software and its format is based on XML. The INF file contains a set of actions and each action may have multiple items.

When you extend a platform, the INF files that are used for the installation is a concatenation of your platform and every platform that it was extended from—just like how objects extend methods, properties and attributes from each other in an object-oriented language. For example, the Branch Office INF file is extended from the Web-to-Go INF file. Thus, when you install Branch Office, the Mobile Server concatenates instructions for the installation from both the Branch Office and Web-to-Go INF files. Any modifications added to the Web-to-Go INF file since the extension will still apply to the installation as both INF files are read at installation time. When you view the configuration information on Mobile Manager, the type field describes all of the platforms that this INF file extends from.

As Table 8-1 describes, the supported keywords start with a '$' character and ends with a '$' symbol.

Table 8-1 Software Management Client Keyword Description

Keyword	Description
$APP_DIR$	Application directory of the application
$APP_NAME$	Application name
$OS_DIR$	Operating system directory
$OS_TYPE$	Operating system type, which can be one of the following: WIN32, WINCE, LINUX, PALM.
$OS_VER$	Operating system version. For example, NT, 95, XP, 3.0, and so on.
$OS_LANG$	Language or Location name, which can be US for English or JA for Japanese.
$DESKTOP$	Folder name of the Windows desktop.
$CPU$	Device processor type. For example, x86, ARM, XSCALE, MIPS, and so on.
$HOST_NAME$	Host name of the client device.
$USER_NAME$	User name
$HTTP_PROXY$	HTTP Proxy Server URL, if any.
$SERVER_URL$	Oracle Mobile Server URL.

8.10.1 Setup Information

All Software Management actions are enclosed within the SETUP XML tag. The SETUP consists of a set of PROPERTIES, INITIALIZATION, INCLUSION of other INF files and INSTALLATION actions. All the four items must be child elements of the SETUP element. A sample INF file is given below.

<setup name="Oracle Lite" version="1.0.0.0">
<property>…. </property>
        <init>…</init>
        <include>…</include>
        <install> …..</install>
</setup>

Setup may have the following attributes specified as XML tag attributes.

NAME - Application name (Mandatory).
VERSION - Application version number (Mandatory).
PACKAGE - Package Type, which can only be cab to specify a Windows CAB format.

8.10.2 Properties

All of the SETUP properties must be the child element of the PROPERTY tag. Setup may have following properties.

STORAGE - Estimated disk (storage) space (in MB) required for an application.

<storage>5</storage>
MEMORY - Minimum amount of system memory in MB. Required.

<memory>5</memory>
LOCATION - Location or directory name of the application. You can specify the location for the application in one of the following ways:
- Default directory. If you do not specify anything or specify <location></location>, then the directory defaults to mobileclient, which is created on the drive with the largest available free space. The user is always prompted to either accept the default or enter the directory that they wish.
- Absolute directory. Define the absolute path where the application is to be installed. The following installs the application in the c:\abc directory:
```
<location>c:\abc</location>
```
- Specify a default directory name. The directory will be created on the drive with the largest available free space. In addition, the user is always prompted to be able to alter the directory into which the application is installed. The following example defines the default directory as abc:
```
<location default='abc'></location>
```
- Define a default directory and an absolute directory. You can specify an absolute directory, where the drive may not exist. If the drive does not exist, then a prompt appears with the default directory, where the user can accept he default or provide another. The following defines the absolute directory of e:\abc, which if the E drive does not exist, then the default directory of abc is created on the drive with the most available free space:
```
<location default='abc'>e:\abc</location>
```
- Specify the platform(s) that this application is installed upon. You can define, with the type attribute, what platforms this application is to be installed on or not installed on. The platforms that you can specify are WIN32, LINUX, and WINCE.
  - To install only on WIN32, do the following:
```
<location default='abc' type='WIN32'></location>
```
  - To install on all platforms, except WIN32, do the following:
```
<location default='abc' type=!'WIN32'></location>
```
  - To install on either WIN32 or WINCE, do the following:
```
<location default='abc' type='WIN32|WINCE'></location>
```
PROMPT - You can have a window pop-up with a prompt if one of the files that you need to install is currently being used. If the user inputs Yes, then the other instances using that file are terminated. For example, if other executables are using the ologj40.dll when you are installing the client, the prompt "Would you like to terminate the Oracle Lite Application?" is provided to the user.

<prompt><item type='WINCE' file='olobj40.dll'/>Would you like to terminate the Oracle Lite Application?</prompt>

The following is an example of the setup section in the INF file:
```
<setup name="Oracle Lite" version="1.0.0.0">
<property>
        <storage>4</storage>
        <memory>12</memory>
        <location>d:\tmp\a</location>
        <prompt>
            <item'>Would you like to install App1?</item>
            <item file='olobj40.dll'>Would you like to close                        Oracle Lite Applications?></item>
        </prompt>
</property>
```

8.10.3 Initialization

Initialization includes setting keywords that you can use when installing your application; the Oracle Database Lite installation keywords are described in Table 8-1. Specify a keyword for your application installation in the type parameter and its value in the name parameter. The following defines a WIN32 keyword with a value of $APP_DIR$/bin.

<init> <item type='WIN32' name='DMC_DIR'>$APP_DIR$/bin</item> </init>

8.10.4 Including Other INF Files

The following syntax allows an INF file to include other INF files:

<include>/dmc/common/webtogo.inf</include>

The value of this tag can be an application name or a fully qualified INF file name. If the value is an application name, the DMS includes the INF file of the application.

8.10.5 INSTALL Element

This section lists all the installation steps necessary to perform Software Installation. Each of the steps (actions) must correspond to another child entry or tag. Each action element has a set of ITEMS and two optional caption strings. The caption string is displayed on the SMC user interface. For example,

<action msg_i='Creating directories' msg_u='Removing directories'>directory</action>

When the SMC interprets the above tag, it looks for a child element by the name directory and processes all the child items of this element. At this stage, the Device Manager UI indicates that directories are being created. If you have a child element without a corresponding action element, it will not be executed. The action elements force the invocation of the child elements.

Table 8-2 describes INSTALL actions that are supported by the SMC.

Table 8-2 INSTALL Actions Supported by the SMC

Action	Description
`directory`	Lists all directories to be created.
`file`	Lists all the files to be copied.
`env`	Lists all the environment variables to be added to the Operating System.
`registry`	Registry keys and values to be added to the Windows Registry.
`odbc`	ODBC driver and DSN to be created.
`java`	JRE to be installed in the computer.
`link`	Folder links to be created. For example, desktop, menu, and so on.
`ini`	INI (configuration files) to be updated.
`register`	DLL (or COM objects) to be registered with Windows.
`execute`	Executable files to be launched during the installation process.
`finish`	Installation completion messages.

8.11 Defining Device Manager Commands With the Device Manager OTL Tag Language

You can send a command from the Mobile Server to any device. To create these commands, use the Device Manager Tag Language, which is described in the following sections:

Section 8.11.1, "Device Manager Tag Language Data Types"
Section 8.11.2, "Operators That You Can Use With the Device Manager Tag Language"
Section 8.11.3, "Syntax for the Device Manager Tag Language"
Section 8.11.4, "Conditional Statements"
Section 8.11.5, "Define Custom Functions"
Section 8.11.6, "Manage the Database Connection"
Section 8.11.7, "Global Classes"
Section 8.11.8, "Importing Another OTL Page"
Section 8.11.9, "Installing an Application From a Server"
Section 8.11.10, "Specifying a Schema File"
Section 8.11.11, "Error Handling"
Section 8.11.12, "Sample Device Manager Commands Using the Tag Language"

8.11.1 Device Manager Tag Language Data Types

The allowed data types for the device manager are as follows:

8.11.1.1 Character

The Character object represents a UNICODE character. It is a primitive data type with no public methods. However, this data type supports implicit conversion methods, such as toString().

8.11.1.2 Number

The Number data type represents either an integer, a double (float), or a large number.

8.11.1.3 Integer

The Integer object represents a four byte signed value. It is a primitive data type with no public methods.

8.11.1.4 Long

The Long object represents an eight byte signed value. It is a primitive data type with no public methods.

8.11.1.5 Double

The Double object represents a signed double (float) value. It is a primitive data type with no public methods.

8.11.1.6 Boolean

The Boolean object has only two possible values of true or false. It is a primitive data type with no public methods.

8.11.1.7 String

The String object represents a series of NULL terminated characters. The String data type represents all of the literal strings in OTL. They are immutable and has the following public methods:

Length ( )

Returns the number of characters in the string.

SubString (Integer start, Integer end)

Creates a sub-string from a String object. Provide the start and the end of the index and it returns the sub-string—beginning at the start value and stopping at the end value.

Trim ( )

Trim a string to remove white spaces from both ends of the string.

IndexOf (Character ch) or IndexOf (String str)

Find the index of a character or a substring within the string. Provide the character or substring inside the string to search for and the index of the first occurrence of the character or substring is returned.

LastIndexOf (Character ch) or LastIndexOf (String str)

Find the index of the last occurrence of a character or a substring within the string. Provide the character or substring inside the string to search for and the index of the last occurrence of the character or substring is returned.

EqualsIgnoreCase (String str)

Compares two strings, without comparing the case of the characters within the string. On one string, execute this method and provide the string to compare it to within the input parameter. True or false is returned.

StartsWith (String str)

Check if the string starts with the provided sub-string. True or false is returned.

EndsWith (String str)

Check if the string ends with the provided sub-string. True or false is returned.

ParseNumber ( )

Parse the string and create a number. This method succeeds only if the string represents a valid number. A number object is either an Integer, Double, or Long. For example, if the content of the String is '12', then this method returns an Integer of 12.

Replace (String in, String repl)

Replace a substring with another, as follows:

<c:set var='str' value='${str.Replace ("123,"345")}'/>

ToUpperCase ( )

Converts characters in the string to upper case.

ToLowerCase ( )

Converts characters in the string to lower case.

Tokenize (Character sep)

Tokenize the string into sub-strings, each separated by a character separator. The input parameter is the character that is to be used as the character separator. The output is an Enumeration object. For example, the following OTL script separates numbers by separating a string everytime it encounters a semi-colon:

<c:set var="str" value="1;2;3;4"/>
<c:foreach var="tok" items="${str.Tokenize (';')}">
 Token = <c:out value="${r}"/>
</c:foreach>

8.11.1.8 Array

The OTL Array object can hold a set of other objects. An array can hold dissimilar objects and can grow automatically as more objects are added. All of the array objects have a global scope.

Sort (Boolean ascend)

Sort the content of the array using a Quick Sort algorithm. The array must be single dimensional. Returns the Sort order.

Length ( )

Returns the size of the array.

Compact ( )

Removes all of the NULL objects from the array.

Copy (Integer from, Integer count)

Copy a number of elements within the array to another array. Give the place in the index to start the copy in the from parameter and the number of elements to copy in the count parameter. An array containing these copied elements is returned.

Insert (Integer index, Object o)

Insert the element provided in Object o into the spot designated by the index parameter.

Remove (Integer index)

Remove the element in the array at the location of the index parameter.

8.11.1.9 Date Methods

Use System.Date to create a Date object, which contains the date and time. The following are other methods that pertain to dates:

GetYear ( )
GetMonth ( )
GetDay ( )
Format (String format)
IsLeapYear ( )

GetYear ( )

Retrieve the year out of the Date object.

GetMonth ( )

Retrieve the month represented by an integer from 1 to 12 out of the Date object.

GetDay ( )

Retrieve the day of the week where Sunday is 0 to Saturday, which is 6, out of the Date object.

Format (String format)

Format the date as described by the format string, which can be either dd/mm/yyyy or mm/dd/yyyy.

IsLeapYear ( )

Check if the year of the date is a leap year or not. Returns true if it is a leap year; false if not.

8.11.1.10 Time Methods

A Time object represents Time value. A Date object always contains a Time object. You can also create a Time object using the System.Time function. In addition, the following methods pertain to time:

GetHour ( )
GetMinute ( )
GetSecond ( )
Format (String format)
To12Hour( )

GetHour ( )

Retrieve the hour out of the Time object.

GetMinute ( )

Retrieve the minute out of the Time object.

GetSecond ( )

Retrieve the second out of the Time object.

Format (String format)

Format the Time object using the provided format string. The format string should either be hh:mm:ss or hh:mm.

To12Hour( )

Convert the Time object to a 12 hour format instead of a 24 hour format.

8.11.1.11 Enumeration

Contains a list of objects. Some of the object types that can be contained in the Enumeration object is a SQL result set, a String Tokenizer, or Request Parameter names.

Count ( )

Counts the number of elements in the Enumeration object. Returns the number of elements.

Next ( )

Accesses the next element in the Enumeration object.

8.11.1.12 File

An object of this type can be used to access contents of a file in the file system. You must use the OpenFile function to open an existing file (a System function). OTL does not allow creation of new files or modification of existing files.

Exists ( )

True is returned if the file exists in the file system.

Open ( )

Open the file for reading. Throws an exception if the file does not exist.

ReadLine ( )

Returns a string from the open file. It reads a line from the file that is terminated by a \r\n.

8.11.2 Operators That You Can Use With the Device Manager Tag Language

You can use operators for calculations on certain objects, as

Table 8-3 Device Manager Tag Language Operators

Operator	Description
`+`	Use can add numbers within Integer, Long, or Double objects. If applied to a String, the strings are concatenated.
`-`	Subtract numbers contained in Integer, Long, or Double objects. Subtract dates or time.
`*`	Multiply numbers contained in Integer, Long, or Double objects.
`/`	Divide numbers contained in Integer, Long, Double, or Character objects.
`%`	A mod operator applied against Integer, Long, Double, or Character objects.

8.11.3 Syntax for the Device Manager Tag Language

OTL supports all regular scripting language syntax rules, such as Assignment, Conditional Constructs, and Sub Routines.

8.11.3.1 Initialization Statements

You can define primitive data types or arrays using the following:

Defining primitive data types: Use the SET syntax to define a new variable in OTL. SET can also be used as an Assignment statement.
```
<c:set var="a" value="1"/>
<c:set var="b" value="String variable"/>
<c:set var="c" value="${a}"/>
```
Defining an array: Use the SET syntax to define the array, which can hold any type of object, including mixed types.
```
<c:set var="arr1" value="${{"aa", "bb", "cc"}}"/>
<c:set var="arr2" incex="0" value="10"/>
<c:set var="arr3" value="${{}}"/>
```
The first array, arr1, is initialized with the values provided. The second array, arr2, is initialized with the number 10 at index 0. The third array, arr3, creates an empty array. When values are assigned to an existing array, the array is expanded, as necessary.

The following example expands the array, arr1, to size 11. All of the values from index 3 to 9 is set to NULL.
```
<c:set value="${arr1.insert(10, "dd")}"/>
```
If there already was an object at location 10, then the object is replaced with the new object, "dd". To insert a new object at index 10 and keep existing data, use the Insert method, as follows:
```
<c:set value="${arr1.insert(10, "dd")}"/>
```

8.11.3.2 Assignment Statements

SET and SQL are two distinct assignment syntax statements.

SET supports normal operations, such as arithmetic operations. Normal arithmetic operations can be used on most of the primitive data types, as well as other objects. OTL converts data types appropriately when arithmetic operations are applied to objects.
SQL executes SQL statements on a database connection, which results in a SQLRESULTSET object.

<c:set var="a" value="1"/>
<c:set var="a" value="${a + 2}"/> 
<c:set var="b" value="${"1" + 2}"/>
<c:set var="dt" value="${System.Date ("01-01-2004")}"/>
<c:set var="dt" value="${dt + 1}"/>

In this example, a is first assigned the value of 1. Then, two is added to a, which brings the value to three. The value of b is initialized to 12 and dt is initialized to the date of Jan. 1, 2004. Lastly, a 1 is added to dt, bringing the date value to 01-01-2004.

8.11.3.2.1 Creating a SQL Result Set

Use the SQL syntax to create a SQL Result. SQL syntax is similar to the SET syntax. The following example assigns a SQL statement to the rs variable.

<c:sql var="rs" value="select table_name from all_tables"/>

8.11.3.2.2 Print Value to the Output Stream

Use the OUT syntax to print a value to the output stream object, as follows:

<c:out value="${a}"/>

8.11.4 Conditional Statements

OTL supports the following four types of conditional statements:

If-Else
While
Foreach
Choose

Each statement must end with the appropriate end tags. Conditional operators, such as &&, ||, ==, >, >=, <, <=, and != are supported by OTL. However, implicit boolean conditions are not allowed, such as if (value).

8.11.4.1 If-Else Conditional Statement

The if-else conditional statement enables you to execute a block of statements depending upon a condition. ELSEIF statements are not supported.

<c:if test="${a == 1 && b == 2}">
 ...
c:else/>
 ...
</c:if>

8.11.4.2 While Conditional Statement

The while statement enables you to execute a block of statements repeatedly until the condition check fails.

<c:while test="${a == 1}">
 ...
</c:while>

8.11.4.3 Foreach Conditional Statement

The foreach conditional statement enables to you enumerate built-in enumeration objects, such as SQL Result Set and Vectors. Also, this statement is used to execute a block of statements repeatedly by stepping through a STEP value.

<c:foreach var="row" items="${rs}">
 <c:out value="${row[0]}"/>
</c:foreach>

Then use the break statement to exit the loop:

<c:foreach var="row" items="${rs}">
 <c:if test="${row[0] begin="1" end="${count}" step="3">
   <c:out value="${row}"/>
</c:foreach>

8.11.4.4 Break Statement

Break from a loop with the break statement.

<c:foreach var="row" items="${rs}">
 <c:if test="${row[0] == "1"}">
   <c:break/>
</c:foreach>

8.11.4.5 Choose Statement

The choose statement supports a mutually exclusive conditional execution, where only one of a number of possible actions is executed. The following example executes one of the when blocks depending on value:

<c:choose>
  <c:when test="${value < 20}">
    <c:out value="Greater than 20"/>
  </c:when>

  <c:when test="${value == 20}">
    <c:out value="Equal to 20"/>
  </c:when>

  <c:otherwise>
    <c:out value="Less than 20"/>
  </c:otherwise>
</c:choose>

8.11.5 Define Custom Functions

You can define custom functions. These functions have a global scope from the point of definition, which means that they can access all global variables within the same OTL page. All variables defined within a function have local scope, except for the Array data type.

In the following example, the par1, par2, par3, and local variables have local scope. Any modifications to these variables are not relected in other parts of the script. If you want to return more than one object from a function, use the System.SetAttribute and System.GetAttribute methods.

<c:func var="PrintData" params="par1, par2, par3">
  <c:out value="${par1}"/>
  <c:set var="local" value="${par1}"/>
  <c:return value="${par2 + par1}"/>
</c:func>

<c:set var="a" value="${PrintData ("Function Call", 1, 2)}"/>
<c:out value="${a}"/>

8.11.6 Manage the Database Connection

You can use database to specify the database connection information used to establish a connection for the application or to disconnect from the database. Only one connection for each application is allowed in the OTL engine.

8.11.6.1 Specify Database Connection Information for an Application

Specify the database connection information used to establish a connection for the application. There is only one connection for each application

<c:database username="SYSTEM" password="P" DSN="POLITE""/>

8.11.6.2 Disconnect from the Database

At then of executing against the database, if you want to disconnect, then issue the following:

c:database action="disconnect"/>

8.11.7 Global Classes

The device manager OTL engine contains two predefined global classes, which are available to any script that access operating system and device manager information.

Section 8.11.7.1, "Methods of the System Class": Use to access operating system information.
Section 8.11.7.2, "Methods of the DeviceManager Class": Use to access device manager information.

8.11.7.1 Methods of the System Class

You can use the following system functions in your device manager command:

Section 8.11.7.1.1, "Retrieve HTTP Request Parameters and Session Values"
Section 8.11.7.1.2, "Create a Date Object"
Section 8.11.7.1.3, "Create a Time Object"
Section 8.11.7.1.4, "Get, Set, or Remove Session Attributes"
Section 8.11.7.1.5, "Retrieving Parameter Name or Value"
Section 8.11.7.1.6, "Retrieving the Request URL"
Section 8.11.7.1.7, "Retrieving the Last Error Message"
Section 8.11.7.1.8, "Retrieving System Memory Information"
Section 8.11.7.1.9, "Retrieving Storage Information"
Section 8.11.7.1.10, "URL Encoding a String"
Section 8.11.7.1.11, "Opening a File"
Section 8.11.7.1.12, "Synchronizing Databases"

8.11.7.1.1 Retrieve HTTP Request Parameters and Session Values

You can retrieve the existing HTTP request parameters and HTTP Session values, as follows:

Retrieve HTTP Request Parameters
Retrieve HTTP Session Attributes

Retrieve HTTP Request Parameters

You can retrieve all of the HTTP request parameters, such as the URL and Form parameters. To retrieve a specific parameter value, prefix the parameter name with a colon—such as :param_name—or use the GetParameterValue function. All of the parameter values are preprocessed and the URLs are decoded by the tag language for you.

For example, if a URL is c://my_app/index.html?my-Par=abcde, then you can retrieve the parameter value in either of the following ways:

<c:out value="${my_par} />

or you can use the GetParameterValues function to retrieve all of the input parameters and then use GetParameterValue function to retrieve the value of each individual parameter, as follows:

<c:set var="rs" value="${System.GetParameterNames()}" />
<c:foreach var="r" items="${rs}">
 <BR>Parameter Name = <c:out value="${r} />
 Parameter Value = <c:out value="$System.GetParmaeterValue (r)}" />
</c:foreach>

For more information on GetParameterValues and GetParameterValue, see Section 8.11.7.1.5, "Retrieving Parameter Name or Value".

Retrieve HTTP Session Attributes

You can retrieve and store session attributes by prefixing the parameter name with a colon (:name) or through the Session get and set functions.

<c:set var="dummy" value="${System.SetAttribute ("NAME", "VALUE")}"/>
<c:set var="val1 value="${System.GetAttribute ("NAME")}"/>
<c:set var="val2 value="$(:NAME}"/>

As you can see, val1 demonstrates how to retrieve the value using the GetAttribute function and val2 demonstrates how to retrieve the value using :NAME. Substitute the actual HTTP session parameter name for NAME.

For more information on get and set attribute functions, see Section 8.11.7.1.4, "Get, Set, or Remove Session Attributes".

8.11.7.1.2 Create a Date Object

Create a Date object with the current time using System.Date(). Create a Date object with a predefined date value using System.Date(String date), where date is a date string.

8.11.7.1.3 Create a Time Object

Create a Time object with the current time using System.Time(). Create a Time object with a predefined time value using System.Time(String time), where time is a time string.

8.11.7.1.4 Get, Set, or Remove Session Attributes

You can get, set, or remove Session attributes. To set an attribute in the application session, use System.SetAttribute (String name, Object value). Each attribute has a unique name and value. To get the attribute value, use System.GetAttribute (String name). To remove the attribute, use System.RemoveAttribute (String name).

8.11.7.1.5 Retrieving Parameter Name or Value

You can retrieve all of the parameters that are provided through the GetParameterNames method, which returns all parameters in an Enumeration object. Given a parameter name, you can retrieve the value through the System.GetParameterValue(String name) method.

Retrieve all parameters into the params variable, as follows:

<c:set var="params" value="${System.GetParameterNames()}" />

Then, once you have retrieved the parameters, you can parse through them using a for loop, as follows:

<c:foreach var="parm" items="${params}">
 <BR>Parameter Name = <c:out value="${parm} />
 Parameter Value = <c:out value="$System.GetParameterValue (parm)}" />
</c:foreach>

Each parameter is read into the parm variable and the name is retrieved using value="${parm}. The value is retrieved with the System.GetParameterValue method.

8.11.7.1.6 Retrieving the Request URL

Use the System.GetURL() method for retrieving the request URL.

8.11.7.1.7 Retrieving the Last Error Message

Use the System.GetError method for retrieving the last error message. If any of the command statements resulted in an error, such as a database error while executing a SQL statement, retrieve the error using this method.

8.11.7.1.8 Retrieving System Memory Information

Use GetMemoryInfo method to retrieve the device memory information. The following parameters are supported by this function:

0 - Retrieve free memory (virtual)
1 - Retrieve total memory (virtual)
2 - Retrieve free memory (physical)
3 - Retrieve total memory (physical)

System.GetMemoryInfo (Integer type)—Given a value between 0 and 3, returns a Long value containing the requested memory information.

8.11.7.1.9 Retrieving Storage Information

Use System.GetStorageInfo to retrieve device storage information. The return value sent back is in KB.

0 - Retrieve free storage
1 - Retrieve total storage

The second parameter must be a drive name or a directory name. If the function is invoked without parameters, then the function retrieves the free storage space in the root directory.

System.GetStorageInfo(Integer type, String drive)—returns a Long value containing storage information.

8.11.7.1.10 URL Encoding a String

Encodes the provided string.

System.URLEncode (String value)

Returns the given string as a URL encoded string.

8.11.7.1.11 Opening a File

Use System.OpenFile (String name) to open the file provided in the method parameter. Returns the File object.

8.11.7.1.12 Synchronizing Databases

Use the System.CreateSyncClient method to create a Synchronization client object. Call the Synchronization.Synchronize method to synchronize. Retrieve any error messages using the System.GetError method.

<c:set var="sync " value="${System.CreateSyncClient()}"/>
<c:set value="${sync.SetUserName ("S11U1")}"/>
<c:set value="${sync.SetPassword ("manager")}"/>
<c:set value="${sync.SetServerURL ("http://localhost")}"/>
<c:set value="${sync.SetProxyInfo ("www-proxy:80")}"/>
<c:set var='ret' value="${sync.Synchronize()}"/>
<c:if test="${ret != 0}">
   <BR>Synchronization error = <c:out value="${System.GetError()}"/>
</c:if>

8.11.7.2 Methods of the DeviceManager Class

The device manager methods are accessed using DeviceManager.FunctionName syntax. These functions can only be used by trusted OTL scripts.

DeviceManager.UploadFile (File file, String URL)
DeviceManager.GetServerURL ( )
DeviceManager.GetBinaryDir ( )
DeviceManager.GetUserName ( )
DeviceManager.CreateRequest (String cmd)
DeviceManager.GetRegistry (String key, String name)
DeviceManager.SetRegistry (String key, String name, String value)
DeviceManager.LogMessage (String handler, String name, String message)

DeviceManager.UploadFile (File file, String URL)

Use UploadFile method to upload a file to the Mobile Server, which contains the device management server. In order to use this method, you must first successfully use System.OpenFile on the file in question.

Given a File object and a URL, returns true if the upload is successful.

DeviceManager.GetServerURL ( )

Returns the URL of the Mobile Server.

<c:set var='url' value='${DeviceManager.GetServerURL()}'/>

DeviceManager.GetBinaryDir ( )

Returns the full path of the binary directory of Oracle Database Lite client.

<c:set var='dir' value='${DeviceManager.GetBinaryDir()}'/>

DeviceManager.GetUserName ( )

Returns the Oracle Lite username

<c:set var='user' value='${DeviceManager.GetUserName()}'/>

DeviceManager.CreateRequest (String cmd)

Create a Device Management request (or command) and notify Device Management Agent to process it. Command string must have corresponding OTL script file in the client device.

The following example demonstrates notifying the DM Agent to process and OTL script of the name: sync.otl.

<c:set value='${DeviceManager.CreateCommand ("sync")}'/>

DeviceManager.GetRegistry (String key, String name)

Retrieve a value from the Oracle Lite configuration file (POLITE.INI). All the values are retrieved as String. The following example retrieves the value for DATA_DIRECTORY configured in the POLITE.INI file.

<c:set var='val' value='${DeviceManager.GetRegistry ("All Databases", "DATA_DIRECTORY")}'/>

DeviceManager.SetRegistry (String key, String name, String value)

Set a new configuration value in the Oracle Lite configuration file (POLITE.INI). The following example sets a new value for DATA_DIRECTORY.

<c:set value='${DeviceManager.SetRegistry ("All Databases", "DATA_DIRECTORY", "C:\TEMP")}'/>

DeviceManager.LogMessage (String handler, String name, String message)

Log a message in the Device Manager logging system. The Device Management client uploads all logged messages to the Oracle Lite Mobile Server.

<c:set value='${DeviceManager.LogMessage (0, "My Log", "Log message..."}'/>

Applications may use this method to send data to the server. In order to accomplish this, you must create a handler on the server to process the client message. Once created, you must register this handler in the Mobile Server. If your application is written in C/C++, JAVA or Visual Basic, you may use corresponding native APIs to log any message. For a C/C++ application, use the following:

dmLogMessage (const TCHAR* handler, const TCHAR* name, const TCHAR* message);

In order to use the above API, you must dynamically load the OMCAPI.DLL library and extract the function pointers. The following sample code demonstrates how to log a message:

typedef void (*dm_Initialize)();
typedef void (*dm_Destroy)();
typedef void (*dm_LogMessage) (LPCTSTR, LPCTSTR, LPCTSTR);
HMODULE hMod = ::LoadLibrary (TEXT ("omcapi.dll"));
if (hMod)
{
  dm_Initialize init =           (dm_Initialize)::GetProcAddress (hMod, TEXT ("dmInitialize"));
  dm_Destroy    dest = (dm_Destroy)::GetProcAddress (hMod, TEXT ("dmDestroy"));
  dm_LogMessage log  =           (dm_LogMessage)::GetProcAddress (hMod, TEXT ("dmLogMessage"));
  if (init && dest && log)
  {
    (*init)();
    (*log) (TEXT ("MY_HANDLER"), TEXT ("MY LOG"), TEXT ("My Message"));
    (*dest) ();
   }
   ::FreeLibrary (hMod);
}

If you want to use the Java API, then set WEBTOGO.JAR, which is part of 'Oracle Lite WEB' client. The following code sample demonstrates how to log a message with Java APIs:

import oracle.lite.dm.ClientAPI;
public class MyLog
{
  public static void main (String[] args)
  {
    ClientAPI.initialize();
    ClientAPI.logMessage ("MY_HANDLER", "MY LOG", "My Message");
    ClientAPI.destroy();
  }
}

On the server-side, a message handler must be developed and registered. A message handler is a Java class that implements the oracle.lite.provider.MessageListener interface. See the Javadoc for more information on the MessageListener interface. The following is an example of a message handler:

import oracle.lite.resource.Device;
import oracle.lite.provider.MessageListener;
import oracle.lite.provider.MessageData;
public class MyMessage implements MessageListener
{
  public void initialize (String metaData) throws Exception {}
  public void destroy() throws Exception {}
  public void service (Device device, String name, MessageData data)            throws Exception
  {
    // Process 'My Message'
   }
}

Once the message handler is implemented and compiled, copy the JAR file to <ORACLE_HOME>\Mobile\class directory. Then, execute the following SQL script to register your message handler implementation:

msql mobileadmin/manager@jdbc:oracle:thin:@<mobile_server_db>:<port>:<sid>
insert into dm$all_providers values ('MY_HANDLER', 'MESSAGE', 'MyMessage', NULL);

8.11.8 Importing Another OTL Page

Use the import statement to include a page into the current page. All URL parameters are available to scripts in the imported page, as well as in the current page below the point of inclusion.

<c:import url="url_of_the_include_page"/>

Specify URL parameters using the HTTP format with the ? or the <c:param> tag, as shown below:

<c:import url="URL?abc=def">
  <c:param name="name1" value="value1"/>
  <c:param name="name2"> value2 </c:param>
</c:import>

8.11.9 Installing an Application From a Server

You can install a new application in an Oracle mobile client by downloading all of the files specified in the download statement, as shown below, and then register the application with the mobile client.

<c:install name="Sample App" url="/sample1/home.htm" icon="/sample1/icon.gif"
        server="http://server_name:8081/download" enable='Y' version="1.0.0.2">
   <c:download name="home.htm" url="app/home.htm" value="10202020"/>
</c:install>

8.11.10 Specifying a Schema File

If you cannot establish a connection to the database or find the table designated when executing a sql statement, then OTL finds a schema statement to locate the OTL script that creates the table and establishes the database connection. The following schema statement establishes that the OTL file is /app1/schema.otl.

<c:schema url="/app1/schema.otl"/>

If a table is missing in the database while processing a <c:sql> statement, then the OTL engine retrieves the schema file and processes it. The schema file should have script to create the missing table, such as the create table statement.

8.11.11 Error Handling

You can throw and catch exceptions within any OTL script. The only restriction is that you can only have at most one catch block. The throw script terminates the current script processing and jumps to the catch block. If a page contains a single throw tag and no catch tag, then the script stops upon reaching the throw tag.

<c:throw value='1'/>
...
<c:catch var='ex'/>
...
</c:catch/>

8.11.12 Sample Device Manager Commands Using the Tag Language

Retrieve current date and time:

<c:set var="d" value="${System.Date()}"/>
<c:out value="Date = ${d}"/>
<br><c:out value="Time = ${d.Time()}"/>

Perform Date arithmetic by first retrieving the date, then adding or subtracting 2 days from it. The last two lines changes the date to either be 2 days from now or 2 days ago.

<c:set var="d"  value="${System.Date()}"/>
<c:set var="d2" value="${d + 2}"/>
<c:set var="d3" value="${d - 2}"/>
Date + 2 = <c:out value="${d2}"/>
<br>Date - 2 = <c:out value="${d3}"/>

Formatting date and time by retrieving the time using the Date or Time methods, and then applying a format. For the date, apply either day/month/year or month/day/year with the Format method. For time, you can choose the format of hours:minutes.

<c:set var="d"  value="${System.Date()}"/>
Date (dd/mm/yyyy) = <c:out value="${d.Format ("dd/mm/yyyy")}"/>
Date (mm/dd/yyyy) = <c:out value="${d.Format ("mm/dd/yyyy")}"/>
<c:set var="t" value="${System.Time()}"/>
Time (hh:mm) = <c:out value="${t.Format ('hh:mm')}"/>

You can apply the names of the month or day to a date by using GetMonth and GetDay, as follows:

<c:set var="month" value="${{"Jan", "Feb", "Mar", "Apr", "May", "Jun", 
            "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"}}"/>
<c:set var="day" value="${{"Sunday", "Monday", "Tuesday", "Wednessday", 
            "Thursday", "Friday", "Saturday"}}"/>
<c:out value="${month[d.GetMonth() - 1]}"/>
<c:out value="${day[d.GetDay()]}"/>

Retrieve the day and add two days to it:

<c:set var="d" value="${d + 2}"/>

Set the date to 02-20-2004.

<c:set var="d" value="${date ("02-20-2002")}"/>