Skip Headers

Oracle® Database Lite Administration and Deployment Guide Release 10.3 Part Number E12089-02 |
Home | Book List | Contents | Index | Contact Us

Previous | Next
| View PDF

# 7 Manage Your Devices

When you install your Mobile client software, the Mobile device manager 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 7.1, "Customize the Mobile Client Software Installation for Your Mobile Device"

- Section 7.2, "Configuring Mobile Clients Before Installation"

- Section 7.3, "Managing Devices"

- Section 7.4, "Configuring and Customizing Your Mobile Device Platform"

- Section 7.5, "Configuring Your Mobile Devices"

- Section 7.6, "Sending Commands to Your Mobile Devices"

- Section 7.7, "Managing Device Software Updates"

- Section 7.8, "Using the Device Manager Agent (dmagent) on the Client"

- Section 7.9, "Managing the Network Protocol Between the Device and the Mobile Client Software"

- Section 7.10, "Installation Configuration (INF) File"

- Section 7.11, "Defining Device Manager Commands With the Device Manager OTL Tag Language"

## 7.1 Customize the Mobile Client Software Installation for Your Mobile Device

The Mobile device software for your language and platform is installed when you install the Mobile client on your device.

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 before installation. See Section 7.2, "Configuring Mobile Clients Before Installation" for more information.

- Customize the platform to install additional binaries, applications, and other environment modifications. See Section 7.4, "Configuring and Customizing Your Mobile Device Platform" for more information.

Once installed, you can locally or remotely manage the client using the Device Manager tool. See Section 7.8, "Using the Device Manager Agent (dmagent) on the Client" for more information.

## 7.2 Configuring Mobile Clients Before Installation

When you install the Mobile client on the device, a few configuration files are installed, such as the `webtogo.ora`, `polite.ini` and `odbc.ini` files. However, you can pre-configure some of the parameters destined for the client `webtogo.ora`, `polite.ini` and `odbc.ini` files using either of the following:

- Using the Mobile Manager: Navigate to the Mobile Devices->Administration->Configuration Management page, which enables you to modify the parameters, located in the INF file, corresponding to the Mobile client platform that is to be downloaded to the client.

- Edit the `<ini>` section of the INF file: To edit the INF file directly, see Section 7.10, "Installation Configuration (INF) File".

Note:

Th e `polite.ini` and `odbc.ini` files are available in under `$OLITE_HOME/bin`. You must have write permissions on the directory where these are located to be able to modify them.

1. Navigate to the Mobile Device screen.

2. Click Administration.

3. Click Configuration Management.

4. The parameters destined for the client configuration files are initially set up in different INF files. You can modify some of the parameters in these files. However, this is a very sensitive configuration and should only be done if you fully understand the function of each parameter. Normally, the only time you modify these parameters is from direction from Oracle Support.

   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 parameters in each INI section is displayed. You can only add name value pairs to existing sections.

5. To add name/value pairs to the existing sections, click Add. To modify a parameter, modify it and click Apply. To delete, select the configuration pair and click Delete.

6. To add more sections, you must modify the INF file directly. To modify or add items to the existing sections, you can click Add.

7. A screen is displayed asking for two strings: a name and a value. Enter these items and click OK.

The following sections describe each INF file:

- Section 7.2.1, "Modifying Device Management Parameters for Client Device"

- Section 7.2.2, "Modifying WEBTOGO Parameters for Client Device"

- Section 7.2.3, "Modifying Oracle Lite Mobile Client Win32 Parameters for Client Device"

### 7.2.1 Modifying Device Management Parameters for Client Device

When you select Device Management from the File Name pull down, you can modify the `dmc.inf` file. The following example shows the INI section directly from the `dmc.inf` file:

    <ini>
     <item name="POLITE" section="DMC">
     <item name='USER_NAME'>$USER_NAME$</item>
     <item name='PUSH_PORT'>8521</item>
     <item name='DISABLE_PROMPT'>FALSE</item>
     <item name='UPDATE_DAY'>0</item>
     <item name='UPDATE_TIME'>0</item>
     </item>
    </ini>

Figure 7-1 displays how the Device Management 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.

Note:

Even though it is displayed here, you should not modify the `USER_NAME` field.

Figure 7-1 Adding Name/Value Pairs to Device Management INF File

Description of "Figure 7-1 Adding Name/Value Pairs to Device Management INF File"

Where the parameters are as follows:

Table 7-1 Device Management Parameters in DMC.INF File

Parameter | Description
--- | ---
`PUSH_PORT` | The listening port on the Mobile device for incoming commands from the Mobile Server. By default, the value is 8521. Port listed here is for all Mobile devices; thus, all clients are configured with the identical port number. Also, the server administrator can disable the `PUSH_PORT` completely (for security reasons) by setting the value of `PUSH_PORT` to zero. Do not modify the `PUSH_PORT` value on the client in the `polite.ini` file.
`DISABLE_PROMPT` | The `DISABLE_PROMPT` parameter accepts a `TRUE` or `FALSE` value, which causes the following action: `TRUE`: The device checks for software updates available on the server. If updates are available, these are brought down to the client and installed. `FALSE`: The device checks for software updates available on the server. If updates are available, the option to bring down the updates and install them is displayed to the user, who decides what action to take. If the client chooses to update, then these are brought down to the client and installed.
`UPDATE_DAY` | Day when the Mobiledevice checks for software updates. Used in combination with `UPDATE_TIME`. `UPDATE_DAY` takes 0 - 8 which translates to the following days: Never = 0 Daily = 1 Sunday = 2 Monday = 3 Tuesday = 4 Wednesday = 5 Thursday = 6 Friday = 7 Saturday = 8
`UPDATE_TIME` | Time of day that the Mobile device checks for software updates from the Mobile Server. Used in combination with `UPDATE_DAY`. `UPDATE_TIME` can take values 0 - 23 which translates to the following time: 00:00 = 0 01:00 = 1 12:00 = 12 13:00 = 13 23:00 = 23
`USER_NAME` | Do not modify; automatically retrieves the username from the Mobile Server when downloaded to the client.

Note:

You can also modify the `UPDATE_DAY` and `UPDATE_TIME` parameters on the client through the `dmagent` UI. See Section 7.8, "Using the Device Manager Agent (dmagent) on the Client" for details.

### 7.2.2 Modifying WEBTOGO Parameters for Client Device

When you select Web-to-Go from the File Name pull down, you can modify the `webtogo.inf` file that will be installed on the Oracle Lite Mobile clients. The following example shows the INI section directly from the `webtogo.inf` file:

    <ini>
      <item name="$APP_DIR$\bin\webtogo.ora" section="WEBTOGO">
        <item name="JAVA_HOME">c:\jdk1.5</item>
        <item name="MODE">CLIENT</item>
        <item name="Data_Directory">$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>

Note:

Most of the parameters in this section should only be modified if directed by Oracle Support.

There are two sections shown in this INI section: `WEBTOGO` and `InternetShortcut`. You can add other sections. Once added, the Mobile Manager reads them in and displays them accordingly.

Table 7-2 describes the parameters you can modify in the `WEBTOGO` section:

Table 7-2 WEBTOGO parameters for the client device

Parameter name | Description
--- | ---
JAVA_HOME | As described in Section 6.4.6, "Configure JAVA_HOME for Web-to-Go clients" in the Oracle Database Lite Client Guide, this sets the specific Java environment that the Web-to-Go client will use. If you set this in the INF file, you must know the exact location where the Java environment is installed on the client.

Figure 7-2 displays how the Web-to-Go 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 7-2 Modifying Web-to-Go INF File Parameters

Description of "Figure 7-2 Modifying Web-to-Go INF File Parameters"

### 7.2.3 Modifying Oracle Lite Mobile Client Win32 Parameters for Client Device

When you select Oracle Lite Win32 from the File Name pull down, you can modify the `webtogo.inf` file for the Oracle Lite Mobile client. The following example shows the INI section directly from the `webtogo.inf` file:

    <ini>
      <item name="$APP_DIR$\bin\webtogo.ora" section="WEBTOGO">
        <item name="MODE">CLIENT</item>
        <item name="Data_Directory">$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.

Figure 7-3 displays how the Web-to-Go 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 7-3 Modifying Win32 INF File Parameters

Description of "Figure 7-3 Modifying Win32 INF File Parameters"

## 7.3 Managing Devices

From the Mobile Devices screen, as shown in Figure 7-4, you can perform the following:

- Add—Click Add to add a new device.

- View—Select the device to view information about this device.

- Delete—Select the checkbox next to the desired device and click Delete.

Figure 7-4 Devices Page

Description of "Figure 7-4 Devices Page"

Figure 7-5 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 7-5 Mobile Device Properties and Information

Description of "Figure 7-5 Mobile Device Properties and Information"

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

- Device Name

- Enabled: If the device is enabled. See Section 7.4.2, "Enabling or Disabling All Mobile Devices in a Platform" for more information.

- Upgradable: If the device accepts software upgrades. See Section 7.7, "Managing Device Software Updates" for more information.

- Valid: If the Device Manager 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 7.3.1, "Viewing Device Information"

- Section 7.3.2, "Viewing Database Information"

- Section 7.3.3, "Viewing Software Information"

- Section 7.3.4, "Commands"

- Section 7.3.5, "Queue"

- Section 7.3.6, "Command History"

- Section 7.3.7, "Viewing Device Logs"

### 7.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, you must be using the JDK 1.4.2. If you have applied the Oracle Database Lite patch set to the Oracle Database Lite 10g release, you can use JDK 5.0. 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.

### 7.3.2 Viewing Database Information

When you select the Database Info tab, you see all of the information about any Oracle Lite databases installed on the Mobile client.

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 Oracle Lite 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.

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

### 7.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 7.6, "Sending Commands to Your Mobile Devices".

### 7.3.5 Queue

The queue shows any commands that are currently in process. That is, if the device is not currently connected, 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.

### 7.3.6 Command History

This shows all of the commands executed against this device.

### 7.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 the synchronization logs, perform the following:

1. You must first retrieve the synchronization logs by sending the 'Retrieve synchronization log' command to the device.

2. Then view the retrieved client device synchronization logs by clicking Synchronization. This shows only the synchronization requests made by the client.

## 7.4 Configuring and Customizing Your Mobile Device Platform

Oracle Database Lite ships with a number of predefined platforms that you can download and install on your Mobile client device. However, there are some devices that the CAB file is provided within the installation, but which are not registered and available for download within the Mobile Manager. You can register these devices—if necessary—for any needed device platform. After registration, the platform appears on the Mobile Manager setup screen for your Mobile client installations.

A Mobile client platform consists of a CAB file and an Installation Configuration File (INF file) that describes how to install the files.

As described in Section 5.2, "Installing the Mobile Client Software" in the Oracle Database Lite Getting Started Guide, you normally install the Mobile client software by selecting the type of Mobile device and the language in the setup UI. 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 7.4.1, "Modifying Platform Properties for Installation"

- Section 7.4.2, "Enabling or Disabling All Mobile Devices in a Platform"

- Section 7.4.3, "Extend or Create a Custom Platform"

### 7.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 7.4.3, "Extend or Create a Custom Platform".

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

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

   1. Click Platforms.

   2. Click on the platform for which you are currently modifying the INF file.

   3. 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 `$OLITE_HOME``/j2ee/mobileserver/applications/mobileserver/setup/dmc` 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 7.10, "Installation Configuration (INF) File" for the configuration syntax.

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

3. 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 7.4.2, "Enabling or Disabling All Mobile Devices in a Platform" for more information.

4. 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 7.7, "Managing Device Software Updates" for more information on updating software on your device.

### 7.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 7.5.1, "Enabling or Disabling a Mobile Device". However, if you want to enable or disable all devices for a platform, then see Section 7.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 7.4.3, "Extend or Create a Custom Platform") for devices that were used for a specific purpose, such as if you had mobile 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 7.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.

### 7.4.3 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 7.4.3.1, "Enable a Platform for Your Mobile Client" for more information.

- You can extend an existing platform to customize that platform to install additional binaries, applications, or to have specific instructions on modifying the client machine to accommodate your specifications. See Section 7.4.3.2, "Create a Custom Platform By Extending an Existing Platform" for more information.

#### 7.4.3.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:

1. On the Mobile Devices screen, click Platforms.

2. On the Platforms screen in the Search pulldowns, select the language and either Disabled or All and click Go.

3. Select the platform name that you want to enable.

4. Enable the device by selecting Yes in the Enable pulldown.

5. Click OK. The device is now enabled and will be visible in the client setup screen.

#### 7.4.3.2 Create a Custom Platform By Extending an Existing Platform

You may wish to install additional binaries, applications, or to have specific instructions on modifying the client machine when the client platform is downloaded to the device. The INF file contains the "directions" to the client on how the platform is installed.

To create a custom platform from an existing platform, do the following:

1. Create a new INF file for your extended platform—On the Mobile Server, navigate on the file system to `$OLITE_HOME``/j2ee/mobileserver/applications/mobileserver/setup/dmc` to where the setup INF files are located. Create an empty INF file for your new platform. As discussed in Section 7.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.

2. On the Mobile Devices screen, click Platforms.

3. On the Platforms screen, select the platform name and click Extend.

4. 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 7.10, "Installation Configuration (INF) File" for instructions on how to modify the setup INF file after you have completed extending the platform.

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

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

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

8. Click OK.

9. After you have extended your platform and given it a unique name, you should modify the setup INF file for this platform.

The client can now install your customized platform from the setup UI.

## 7.5 Configuring Your Mobile Devices

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

Figure 7-6 Devices Page

Description of "Figure 7-6 Devices Page"

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

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

2. Enable the device by selecting Yes; disable the device by selecting No. See Section 7.5.1, "Enabling or Disabling a Mobile Device" for more information.

3. 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 7.7, "Managing Device Software Updates" for more information.

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

5. 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_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 7.9, "Managing the Network Protocol Between the Device and the Mobile Client Software".

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

## 7.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 7.6.1, "Scheduling or Sending Commands"

- Section 7.6.2, "Modifying Existing Commands"

- Section 7.6.3, "Creating New Commands"

- Section 7.6.4, "Creating Group Commands"

- Section 7.6.5, "Enabling or Disabling Mobile Device Commands"

- Section 7.6.6, "Viewing the Mobile Device Command History"

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

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

Note:

If a WinCE device is not physically connected to the Mobile Server, then the device manager commands are not sent immediately. Instead, all commands are queued up. The client device receives these commands when connected to the Mobile Server and polls the command queue.

The default frequency to pull commands is 1800 seconds, which can be configured through the options section of the Device Manager Agent (`dmagent.exe`) located on the client.

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

##### 7.6.1.1.1 Description of Existing Commands

The following are the commands that you can use to control your device:

- Retrieve Device Information—retrieves hardware and software information from the device. For Oracle Lite Mobile clients, the command also retrieves Oracle Lite database file names and their sizes. The retrieved information may be viewed by clicking on 'Device Info' and 'Database Info' pages.

- Install Application—Send this command to force the device to install an application. In order for this command to work, the following conditions must be met:

  - The application must be published correctly to the Mobile Server.

  - The application platform must match the device platform.

  - The user must have access to the application.

  If the application already is installed on the client and an update is available, this command forces an update for the client.

- Retrieve Software Information—Retrieves information regarding Oracle Database Lite and Oracle Database Lite applications. Retrieved information is displayed on 'Software Info' page.

- Stop Device Manager Client—Sends a stop signal to the device manager client. Once the client is stopped, it will not receive any more commands from the server. User must either start the Device Manager agent explicitly (`dmagent.exe`) or invoke 'Check For Update' program in order to restart the device manager client.

- Retrieve synchronization log—Retrieves the data synchronization log from the client. The retrieved information is displayed in 'Device Log->Synchronization' page.

- Synchronize databases—Synchronize all the databases that are 'synchronizable'. This command does not retrieve the synchronization log.

- Retrieve a file from the device—Force the device to upload a file. By default, this command will retrieve the file from Mobile client's HOME directory. If you want to retrieve an arbitrary file, you must provide the full path name of the file. The retrieved file is stored in the Mobile Server's repository and may be viewed by clicking on the hyper-link on the 'Command History' status column. The physical location of the file in the server is `<ORACLE_HOME>``\mobile_oc4j\j2ee\mobileserver\applications\mobileserver\devmgr\<USER_NAME>\<DEVICE_ID>`

- Validate Database—For Oracle Lite Mobile clients, validates the Oracle Lite database and uploads the results to the Mobile Server. The result may be viewed by visiting 'Command History' page and clicking on the status column.

- Synchronize and Delete Databases—For Oracle Lite Mobile clients only. Triggers data synchronization. Deletes all the Oracle Lite databases except '`CONSROOT`' after the synchronization has been completed.

- Modify Configuration—Modify configuration settings in `POLITE.INI` files. For Oracle Lite Mobile clients, you can modify configuration settings in `ODBC.INI` files.

- Update Device Manager Client—Force the device manager client to update the OTL script files. The common use of this command is to propagate the OTL script files copied to the Mobile Server's script directory.

- De-install Oracle Database Lite—Remotely de-install Oracle Database Lite on the client device.

- Reset Password—Reset the client side password to match the new password on the server side. This command DOES NOT change the password. In order to use the command, the Administrator must change the user's password in Mobile Server and later send the command to the device to reset its stored password. Also, the device must be immediately reachable from the Server. See Section 6.4.3, "Reset the Mobile User Password" in the Oracle Database Lite Client Guide for details.

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

1. Click Schedule. The Schedule Command page appears.

2. As shown in Figure 7-7, 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.

     Note:

     You can only use fast refresh with a high priority restricting predicate. If you use any other type of refresh, the high priority restricting predicate is ignored.

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

     If you use complete refresh, it erases all of the data on the client and brings down the snapshot from the server. This is only a problem if you have not specified the publication as updateable. An updateable publication enables all new data entered in the client to be uploaded to the back-end Oracle server.

   Figure 7-7 The General Section of the Command Scheduler

   Description of "Figure 7-7 The General Section of the Command Scheduler"

3. As Figure 7-8 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 7-8 Timing Section of the Command Scheduler

   Description of "Figure 7-8 Timing Section of the Command Scheduler"

4. Click Apply. The Mobile Manager displays a confirmation message.

### 7.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 7-9 displays, the Command Management page appears.

Figure 7-9 Command Management Page

Description of "Figure 7-9 Command Management Page"

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

1. Click the required Command Name link. The Properties page for this command appears.

2. Enter the command name, description, and syntax in the corresponding fields. For more information on modifying these fields, see Section 7.6.3, "Creating New Commands".

3. To check the accuracy of the command syntax, click Syntax Check button. If no errors are found, the Mobile Manager displays a confirmation message.

4. Click Apply. The Mobile Manager displays a confirmation message.

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

1. Click the required Command Name link. The Properties page for this command appears.

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

     If you use complete refresh, it erases all of the data on the client and brings down the snapshot from the server. This is only a problem if you have not specified the publication as updateable. An updateable publication enables all new data entered in the client to be uploaded to the back-end Oracle server.

     You can only use fast refresh with a high priority restricting predicate. If you use any other type of refresh, the high priority restricting predicate is ignored.

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

### 7.6.3 Creating New Commands

You can create commands using the OTL scripting language, as described in Section 7.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:

1. Create a file with an `.otl` extension with the OTL commands in it. Place this file in the `ORACLE_HOME``\mobile_oc4j\j2ee\mobileserver\applications\mobileserver\setup\dmc\otl` directory.

2. With any editor, add all OTL commands that you want executed within the file. See Section 7.11, "Defining Device Manager Commands With the Device Manager OTL Tag Language" for a full description of the OTL scripting language.

3. Within Mobile Manager, navigate to the Command Management page.

4. Click Create Command.

5. In the Name field, pick a short name to identify the command within Mobile Manager.

6. In the Command field, put the name of the OTL file, without the `.otl` extension.

7. In the Description field, type in a sentence describing accurately the purpose of the command.

8. Click OK.

9. Back on the Command Management screen, select the command that you just created.

10. If you ask the user to enter parameters, then add the parameter definitions. See Section 7.6.2.1, "Adding Parameters to Mobile Device Commands" for a full description.

11. Click Apply.

12. You have now successfully created a new command. After you send the command to the device, you can execute this command against your Mobile device. See Section 7.6.1, "Scheduling or Sending Commands" for information on how to send the command to the device.

### 7.6.4 Creating Group Commands

To create group commands, do the following:

1. Click Create Group. The Create Group Command page appears.

2. Enter a unique Command Name, which will be used to identify the grouping.

3. Enter a description.

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

   Note:

   If you provide similar weights to more than one command, the commands with the same weight are executed in the sequence in which they are listed on the GUI, which is alphabetical.

5. Click Add. The Mobile Manager displays a confirmation message.

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

1. From the Mobile Devices page, click Administration.

2. Choose Command Management.

3. Select the command that you want to enable or disable.

4. Select either Yes for enable or No for disable on the Enabled pull-down.

5. Click Apply.

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

### 7.6.7 Examples of Mobile Commands

You can create commands that performs on the client. The following are examples of commands that you could send to your Mobile device:

- A command that configures for automatic encryption of a local Oracle Lite database, see Section 5.10, "Encrypting the Oracle Lite Database".

- A command that triggers a synchronization on the client, see Section 5.3, "Configuring for Default Sync When Installing the Client" in the Oracle Database Lite Getting Started Guide.

## 7.7 Managing Device Software Updates

This section describes how to enable and initiate software updates and patches for your devices.

- Section 7.7.1, "Configuring the Device to Receive Required Software Updates"

- Section 7.7.2, "Configuring Application Software for Automatic Update"

- Section 7.7.3, "Initiate Updates of Oracle Database Lite Software from the Client"

### 7.7.1 Configuring the Device to Receive Required Software Updates

If you configure for automatic software updates, 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 disallow automatic updates.

There are two types of software updates that you can control, as detailed in the following sections:

- Section 7.7.1.1, "Allowing Automatic Software Updates for the Oracle Database Lite Platform"

- Section 7.7.1.2, "Updating Application Software On Each Client"

#### 7.7.1.1 Allowing Automatic Software Updates for the Oracle Database Lite Platform

You can configure if Oracle Database Lite is to automatically allow software updates for the devices through one of two methods:

- Set `Upgradable` to `Yes/No`—The `Upgradable` field enables you to configure for automatic software updates, so that 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 set Upgradable to No.

  See Section 7.5, "Configuring Your Mobile Devices" for details on how to modify the Upgradable field within the Mobile Manager GUI.

  Note:

  Do not set your device to No until after the first synchronization. The device must be configured as upgradable for the first synchronization.

  Change the value of `Upgradable` in the Mobile Manager GUI to Yes to enable and No to disable, as follows:

  1. Select the Mobile Devices tab in Mobile Manager.

  2. Select the Platform tab to display all Oracle Database Lite Platforms.

  3. Click Oracle Lite WIN32 platform to display its properties.

  4. Change the value of `Upgradable` to `Yes/No`. Click OK.

- Set the `UPDATE_SOFTWARE` attribute in the Resource Manager to `true/false`. This has to be set programmatically on the Resource Manager object, as follows:

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

If you want to enable/disable any application updates, but continue to allow Oracle Database Lite platform updates, then set the `UPDATE_SOFTWARE_APPS` attribute to `true/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`.

#### 7.7.1.2 Updating Application Software On Each Client

You can control whether a new version of an application software is downloaded on each client and which users receive the latest update. The default configuration is for all devices attached to a user to 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 Lite Win32 version 10.0.0.0.0; however, you want Tom's devices to upgrade to the new version, which is Oracle 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`.

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, which is denoted by the version number. Any modification of the version in the first or second position is a major update. For example, any version that changes from 10.0.0 to 10.1.0 or 11.0 is a major update. This is the default.

  - Minor—The devices attached to this user receives only minor software updates. This includes only patch releases. For example, if the client software is version 10.0.0, then modifications only apply to the third position or later constitutes a patch update. This would include the version numbers 10.0.1 or 10.0.0.1. It would not include the 10.1.0 which would be a major update.

  - 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. For example, if the version shows a major release, then this device receives the update. This is the default.

  - `Minor`—The devices attached to this user receives only minor software updates. For example, if the version shows only a minor patch release, then this device receives the update. However, if the software released is a major version upgrade, then this is not applied.

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

#### 7.7.1.3 Rolling Out Updates With Controlled Upgrade

If you want to roll out software updates in a staggered fashion to a subset of your users at a time, you can use the controlled update. A controlled update enables the following:

- You can deploy the latest software or patches to a set of users to limit the impact of your IT team handling multiple responses from affected users.

- You can deploy the latest software or patches to a set of users for testing purposes, while keeping the majority of the users on an older version of the software.

To perform a controlled update, perform the following within Mobile Manager:

1. Create a group with all of the users that you want to receive the update.

2. Edit the group and set the update policy for the group to All, Major, Minor or Disable.

Alternatively, you can use the APIs and perform the following:

1. Create a group with the `MobileResourceManager.createGroup` method.

2. Set the group update policy with the following method, where the value can be “`major`,” “`minor`,” or “`false`.”

       group.setPolicy(ResourceConst.UPDATE_SOFTWARE, “major”);

3. Add all users to be within the group with the `MobileResourceManager.addUsersToGroup` method.

### 7.7.2 Configuring Application Software for Automatic Update

In order for the Mobile Server and the device to know if an application software is to be updated, you need to configure the INF file to detail the current version. This version is checked against what is currently installed on the client, which then enables the Mobile Server and the device management to decide whether an automatic software update is necessary.

The following sections describe how to configure your application software for automatic update:

- Section 7.7.2.1, "Configuring Major Software Updates for Download"

- Section 7.7.2.2, "Configuring Patches or Minor Updates for Download"

#### 7.7.2.1 Configuring Major Software Updates for Download

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:

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

2. Initiate a synchronization. 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.

   Alternatively, the client user can invoke `update.exe` to check for the latest version of the software. See Section 7.7.3, "Initiate Updates of Oracle Database Lite Software from the Client" for more details on the update tool.

#### 7.7.2.2 Configuring Patches or Minor Updates for Download

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 Section 7.10, "Installation Configuration (INF) File".

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:

1. The administrator copies the patch `INF` files to the patch directory.

2. The administrator copies the new application files to the application directory.

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.

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

### 7.7.3 Initiate Updates of Oracle Database Lite Software from the Client

You can initiate a request for software updates from the Mobile Server by executing the Update tool, as shown in Figure 7-10. To execute, choose Update from the Oracle Database Lite Programs list or enter `update` on the command line.

For each type of client, the update tool acts as follows:

- The mSync tool automatically launches this tool if and only if a software update is available.

- For Oracle Lite Mobile clients only:

  - Web-to-Go clients prompt the user in a Web page if an update is available.

  - For Branch Office clients and applications that use the synchronization APIs, this tool is not automatically executed. Instead, if you want to launch the update tool to check for software updates, then explicitly enter `update` on the command line.

Figure 7-10 Updating Mobile Client Software

Description of "Figure 7-10 Updating Mobile Client Software"

When updates are located, you can select items that you do not want to update and click Remove. When all updates are satisfactory, click Install. When you are finished, click Exit.

If you check the Disable Auto Update checkbox, then the next time you execute mSync, this tool is not automatically executed. You can also disable automatic updates from the Mobile Manager. See Section 7.7.1.1, "Allowing Automatic Software Updates for the Oracle Database Lite Platform" for more information.

## 7.8 Using the Device Manager Agent (dmagent) on the Client

On any client, you can manage the Mobile device client software and commands sent to the device from the Mobile Server, as shown in Figure 7-11.

Figure 7-11 Using the Oracle Database Lite Device Manager to Manage Your Device

Description of "Figure 7-11 Using the Oracle Database Lite Device Manager to Manage Your Device"

To bring up the Device Manager Agent GUI, choose Oracle Database Lite Device Manager from the Oracle Database Lite Programs list or execute `dmagent`. 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 7-12, 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 manager 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 manager 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.

    This specifies around the time of day to initiate the update tool, which checks for software updates for the client. The actual time depends on when the device manager checks for queued commands. See Section 7.7.3, "Initiate Updates of Oracle Database Lite Software from the Client" for more details on the update tool.

  - Proxy Server: If you have a proxy server between the Mobile client and Mobile Server, enter the address and port here.

  Figure 7-12 Device Client Manager Options

  Description of "Figure 7-12 Device Client Manager Options"

- Click Hide to place the Oracle Database Lite Device Manager in the Windows System Tray.

## 7.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, 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 WinCE 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 mobile phone as a Mobile device, then you would have a network protocol where the mobile phone receives incoming data. Thus, the address is a phone number for the mobile phone. The mobile phone is "woken" when incoming commands are initiated from the Mobile Manager. You can have the Wake on Ring over SMTP—WOR_SMTP:

- 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 classname: The name of the Java class that implements the Network protocol, such as HTTP, SMS, EMAIL, and so on.Metadata: Any user defined string that is required as input by the Java class during the initialization. See Section 11.6.1.5.3, "Proxy Configuration for the Mobile Server" for an example of how to configure the metadata for the HTTP protocol.

To define a new network protocol, do the following:

1. Create a `NetworkProvider` class using Java. This class must implement the `oracle.lite.provider.NetworkProvider` interface.

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

   3. Click OK.

## 7.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 from which this INF file extends.

Note:

The server-side INF files that you can modify for the client platform are located in the `$ORACLE_HOME``\mobile_oc4j\j2ee\mobileserver\applications\mobileserver\setup\dmc` directory.

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

Table 7-3 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.
`$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, 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.

The following sections describe the INF file:

- Section 7.10.1, "Setup Information"

- Section 7.10.2, "Properties"

- Section 7.10.3, "Initialization"

- Section 7.10.4, "Including Other INF Files"

- Section 7.10.5, "INSTALL Element"

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

1. NAME - Application name (Mandatory).

2. VERSION - Application version number (Mandatory).

3. PACKAGE - Package Type, which can only be `cab` to specify a Windows CAB format.

### 7.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>`

- `USERS`—Optional setting that defines under what privileges to install the Mobile client. Also, if not configured in the INF file, then a prompt will appear in the installation to ask under what privileges to install the client.

  The `prompt` attribute describes if the screen prompt for asking under what privileges to install the Mobile client should be displayed. The `prompt` attribute defaults to true. Setting the `prompt` attribute to false eliminates this screen from displaying during client installation.

  The two options for user install privilege are as follows:

  - Install for all users: This requires an administrator to install as it provides access to the main user and all members on the device. The following is an example of how to set this privilege:

        <users prompt='false'>All</users>

  - Install for single user: This requires only the user privilege as only a single user is using the application and device. The following is an example of how to set this privilege:

        <users prompt='false'>Current</users>

    Note:

    If any other word is provided for the `<USERS>` setting, then it will default to `prompt='true'` and the user will be prompted for the user privilege.

  The presence of the `<users>` section will not have any effect if the user is installed on WinCE, Linux, a Branch Office installation, which automatically requires the administration privilege, or the user is a member, which is by default not an administration privilege.

- `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 `olobj40.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>
              <users prompt='false'>Current</users>
              <prompt>
                  <item>Would you like to install App1?</item>
                  <item file='olobj40.dll'>Would you like to close                        Oracle Lite Applications?></item>
              </prompt>
      </property>

### 7.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 7-3. 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>

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

### 7.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 7-4 describes INSTALL actions that are supported by the SMC.

Table 7-4 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` | DLLs to be registered with Windows.
`execute` | Executable files to be launched during the installation process.
`finish` | Installation completion messages.

#### 7.10.5.1 DIRECTORY Section

The directory element contains names of all the directories to be created during the installation process. Entries in this section are fully qualified directory names. For example,

    <directory>
        <item>$APP_DIR$\oldb40</item>
        <item>$APP_DIR$\crm</item>
    </directory>

The SMC creates `OLDB40` and `CRM` directories in the `ROOT` of the application directory.

#### 7.10.5.2 FILE Section

The file element lists all the files to be copied during the software installation process. Each item contains a target file name and source file name. The source file name must be unique. We do not support copying the same source file to multiple destination files.

    <file>
       <item>
            <src> win32/crm/crm.dll </src>
            <des>$APP_DIR$\crm\crm.dll </des>
       </item>
    </file>

If you want to copy a source file multiple times, you cannot just define the source file and then configure for it to be copied to multiple destinations. Instead, you must manually copy the source file to another filename and then configure it as follows:

    <file>
      <item>
            <src> win32/crm/crm.dll </src>
            <des>$APP_DIR$\crm\crm1.dll </des>
       </item>
       <item>
            <src> win32/crm/crm2.dll </src>
            <des>$APP_DIR$\crm\crm2.dll </des>
       </item>
    </file>

Where `crm.dll` and `crm2.dll` are the same source file.

The file element also supports inflation of JAR and ZIP files. To inflate a file, use the `inflate='true'` attribute along with the item tag. In the following example, the `inflate` tag copies the `client.jar`. Once copied, the `abc.jar` file is inflated into the `$APP_DIR$/bin` directory.

    <file>
        <item inflate='true'>
            <src>/common/win32/client.jar</src>
            <des>$APP_DIR$\bin\abc.jar</des>
        </item>
    </file>

If you want to install the ODBC 3.5 DLL for Window Mobile clients, add the following in the `win32.inf` file:

    <item>
      <src>/common/win32/olod3540.dll</src>
      <des>$APP_DIR$\bin\olod3540.dll</des>
    </item>
    <item>
      <src>/common/win32/olad3540.dll</src>
      <des>$APP_DIR$\bin\olad3540.dll</des>
    </item>

To register the ODBC 3.5 DLL on the Mobile client, follow the instructions in Section 7.10.5.5, "ODBC Section".

#### 7.10.5.3 ENV Section

The env element contains all environment variables to be added to a Windows NT registry. This modifies only the User environment in Windows NT systems.

    <env>
       <item name='PATH'>$APP_DIR$\WEBTOGO</item>
    </env >

The above example appends the `application_root\webtogo` directory to the `PATH` environment variable.

#### 7.10.5.4 REGISTRY Section

The registry element modifies or removes Windows Registry values. All the entries in this section must be a fully qualified registry key name. Sub key names and values must be specified as a sub section. For example,

    <registry>
                <item>
                    <key>HKEY_CURRENT_USER\Software\Oracle\Test</key>
                    <item name="Count" type="DWORD">400</item>
                    <item name="Test" type="STRING">ABCDE</item>
                </item>
            </registry>

The SMC adds the Windows Registry key named `Test` in the directory named `HKEY_CURRENT_USER\Software\Oracle` and creates a String value named `Test` and a DWORD value named `Count` inside the key. If the same script is used in `UNINSTALL` mode, the SMC removes the key from the Registry.

#### 7.10.5.5 ODBC Section

This section creates/registers the ODBC 2.0 driver and DSNs in the client device. For example,

    <odbc>
      <item name="driver:Oracle Lite 40 ODBC Driver" dll='$APP_DIR$\bin\olod2040.dll'>
       <version>02.00</version>
       <admin>$APP_DIR$\bin\olad2040.dll</admin>
      </item>
      <item name="driver:Oracle Lite 40 ODBC Driver (Client)"
             dll='$APP_DIR$\bin\olcl2040.dll'>
       <version>02.00</version>
       <admin>$APP_DIR$\bin\olclad2040.dll</admin>
      </item>
      <item name="dsn:POLITE" driver='Oracle Lite 40 ODBC Driver'
              dll='$APP_DIR$\bin\olod2040.dll'>
       <Data_Directory>$APP_DIR$\OLDB40</Data_Directory>
      </item>
     </odbc>

To register the ODBC 3.5 DLL, that is installed in Section 7.10.5.2, "FILE Section", add the following to the same INF file that the FILE items are added:

    <item name="driver:Oracle Lite 40 ODBC Driver (3.51)"
                dll='$APP_DIR$\bin\olod3540.dll'>
      <version>03.51</version>
      <admin>$APP_DIR$\bin\olad3540.dll</admin>
    </item>

#### 7.10.5.6 JAVA Section

The `JAVA` element lists the JRE file name and the expected JAVA version. If the expected JAVA version is greater than the version that is already existing in the computer, the SMC installs a new JRE, which is downloaded from the Mobile Server.

Note:

The Web-to-Go client will use the latest Java version installed. See Section 6.4.6, "Configure JAVA_HOME for Web-to-Go clients" in the Oracle Database Lite Client Guide,, on how to configure Web-to-Go to use a specific Java version that may not be the latest.

    <java version="1.3.1">
                <item>
                    <jre>webtogo\j2re-1_3_1_01-win.exe</jre>
                    <iss>webtogo\jre_setup.iss</iss>
                </item>
            </java>

#### 7.10.5.7 LINK Section

The `LINK` element creates a symbolic link on the client system, such as a UNIX soft link or a Windows program link (or Program menu item). Each entry must have a name, a program file name and a folder name, which describe where you want to put the symbolic link and the file path.

The following example creates a symbolic link on a UNIX platform to `libolite40.so.1` in `$ADD_DIR/bin` directory, which points to `$APP_DIR$/bin/libolite40.so`.

    <link>
                <item name='libolite40.so.1'>
                    <folder>$ADD_DIR/bin</folder>
                    <file>$APP_DIR$/bin/libolite40.so/file>
                </item>
            </link>

For Windows platforms, you can also optionally set the current working directory with the `<directory>` tag and the default arguments can be set using the `<arg>` tag. The following example creates a Windows program link to `Oracle Web-to-Go.lnk`, where the `.lnk` is automatically appended, in the `Startup` folder for the `webtogo.exe` file, which is located in the `$APP_DIR\bin` directory.

    <link>
                <item name='Oracle Web-to-Go'>
                    <folder>Startup</folder>
                    <file>$APP_DIR$\bin\webtogo.exe</file>
                    <directory>$APP_DIR\bin</directory>
                </item>
            </link>

#### 7.10.5.8 INI Section

The INI section creates entries in the INI (configuration) files. Each item must have an INI file name and a set of values to be added to a section. For example, the following adds paramters for the `POLITE.INI` file and modifies the `SQLITE.DATA_DIRECTORY` parameter in the SQLite Mobile client `OSE.INI` file:

    <ini>
                <item name="POLITE.INI" section="All Databases">
                        <item name="DATABASE_ID">200</item>
                        <item name="NLS_LANGUAGE">ENGLISH</item>
                </item>
            </ini>
            <ini>
                <item name='$APP_DIR$\sqlite\OSE.INI' section='#'>
                    <item name="SQLITE.DATA_DIRECTORY">$APP_DIR$\sqlite</item>
                </item>
            </ini>

If you want to replace an existing item in the INI file, just provide the name and value, such as follows:

    <item name="Data_Directory">c:\mobileclient</item>

The replace attribute defaults to true; thus `Data_Directory` is modified—whether it already exists or not in the INI file—to be `c:\mobileclient`. However, if you do not want to overwrite any existing value, but want only to add `Data_Directory` if it does not exist, then set the `replace` attribute to false. The following example only adds `Data_Directory` with `c:\mobileclient` if `Data_Directory` is not currently configured in the INI file. If it is configured, the value is not replaced.

    <item name="Data_Directory' replace="false">c:\mobileclient</item>

The default value for the `replace` attribute is true; thus, if you want to replace the value, then set the `replace` attribute to false.

#### 7.10.5.9 EXECUTE Section

The `EXECUTE` element lists all the programs to be executed during the installation process. Each item must have a program name, wait period, and program arguments. The wait value defines how long the installer waits until it moves on to the next action. The wait value can be either an event name, multiple event names, or time specified in seconds. If the value is seconds, then the installer waits that many seconds and then moves on to the next action. However, if the wait value is an event name(s), then the installer waits for the executable (in this case, the `webtogo.exe`) to post that event, before the installer moves on to the next action. For example,

    <execute>
        <item>
         <file>$APP_DIR$\webtogo\webtogo.exe</file>
         <args>-h</args>
         <wait>WebToGoSetupExit/WebToGoSetupStop</wait>
        </item>
     </execute>

#### 7.10.5.10 REGISTER Section

The `REGISTER` element lists all DLLs to be registered with the Windows Operating System. For example,

    <register >
                <item>$APP_DIR$\webtogo\msync_com.dll</item>
            </register>

## 7.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 7.11.1, "Device Manager Tag Language Data Types"

- Section 7.11.2, "Operators That You Can Use With the Device Manager Tag Language"

- Section 7.11.3, "Syntax for the Device Manager Tag Language"

- Section 7.11.4, "Conditional Statements"

- Section 7.11.5, "Define Custom Functions"

- Section 7.11.6, "Manage the Database Connection"

- Section 7.11.7, "Global Classes"

- Section 7.11.8, "Importing Another OTL Page"

- Section 7.11.9, "Error Handling"

- Section 7.11.10, "Sample Device Manager Commands Using the Tag Language"

### 7.11.1 Device Manager Tag Language Data Types

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

#### 7.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()`.

#### 7.11.1.2 Number

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

#### 7.11.1.3 Integer

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

#### 7.11.1.4 Long

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

#### 7.11.1.5 Double

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

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

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

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

#### 7.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 ( )

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.

#### 7.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 ( )

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.

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

#### 7.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`.

### 7.11.2 Operators That You Can Use With the Device Manager Tag Language

You can use operators for calculations on certain objects, as

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

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

#### 7.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")}"/>

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

##### 7.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"/>

##### 7.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}"/>

### 7.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)`.

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

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

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

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

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

### 7.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}"/>

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

#### 7.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""/>

#### 7.11.6.2 Disconnect from the Database

To disconnect from the database, then issue the following:

    <c:database action="disconnect"/>

### 7.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 7.11.7.1, "Methods of the System Class": Use to access operating system information.

- Section 7.11.7.2, "Methods of the DeviceManager Class": Use to access device manager information.

#### 7.11.7.1 Methods of the System Class

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

- Section 7.11.7.1.1, "Retrieve HTTP Request Parameters and Session Values"

- Section 7.11.7.1.2, "Create a Date Object"

- Section 7.11.7.1.3, "Create a Time Object"

- Section 7.11.7.1.4, "Get, Set, or Remove Session Attributes"

- Section 7.11.7.1.5, "Retrieving Parameter Name or Value"

- Section 7.11.7.1.6, "Retrieving the Request URL"

- Section 7.11.7.1.7, "Retrieving the Last Error Message"

- Section 7.11.7.1.8, "Retrieving System Memory Information"

- Section 7.11.7.1.9, "Retrieving Storage Information"

- Section 7.11.7.1.10, "URL Encoding a String"

- Section 7.11.7.1.11, "Opening a File"

- Section 7.11.7.1.12, "Synchronizing Databases"

##### 7.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 7.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 7.11.7.1.4, "Get, Set, or Remove Session Attributes".

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

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

##### 7.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)`.

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

##### 7.11.7.1.6 Retrieving the Request URL

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

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

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

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

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

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

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

#### 7.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 manager 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 Database Lite username

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

DeviceManager.CreateRequest (String cmd)

Create a Device Manager request (or command) and notify Device Manager 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 Database 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 Database 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 Manager client uploads all logged messages to the 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);

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

### 7.11.9 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/>

### 7.11.10 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")}"/>