| Oracle® Database Lite Administration and Deployment Guide Release 10.3 Part Number E12089-02 |
|
|
View PDF |
| Oracle® Database Lite Administration and Deployment Guide Release 10.3 Part Number E12089-02 |
|
|
View PDF |
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.4, "Configuring and Customizing Your Mobile Device Platform"
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.11, "Defining Device Manager Commands With the Device Manager OTL Tag Language"
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.
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:
The
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.Navigate to the Mobile Device screen.
Click Administration.
Click Configuration Management.
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.
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.
To add more sections, you must modify the INF file directly. To modify or add items to the existing sections, you can click Add.
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"
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 theUSER_NAME field.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
Note:
You can also modify theUPDATE_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.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 |
|---|---|
|
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
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
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-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
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.
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.
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.
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.
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".
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.
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:
You must first retrieve the synchronization logs by sending the 'Retrieve synchronization log' command to the device.
Then view the retrieved client device synchronization logs by clicking Synchronization. This shows only the synchronization requests made by the client.
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"
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:
Designate the name and path of the setup INF file for your platform by navigating to the Mobile Devices page.
Click Platforms.
Click on the platform for which you are currently modifying the INF file.
Make sure that the correct setup INF file is listed in the Setup INF field.
Note:
If you want to modify this INF file or provide a different INF file, then on the Mobile Server, navigate on the file system to
$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.Choose a Bootstrap group command from the list displayed. After the device bootstrap is complete, you can choose a group command to execute when it is completed. For example, choosing the device information command retrieves all of the device information to the Mobile Manager for viewing.
Enable or disable all devices in the platform. If you enable these devices by choosing Yes, then each user can log in, perform updates, synchronize, and perform other duties. If you disable these devices by selecting No, then they can no longer perform work for the user. See Section 7.4.2, "Enabling or Disabling All Mobile Devices in a Platform" for more information.
Set Upgradable to Yes to retrieve all software updates for all devices in the platform. If you want these devices to continue to receive automatic software updates, choose Yes. If you want these devices to stay with the current software versions, choose No. See Section 7.7, "Managing Device Software Updates" for more information on updating software on your device.
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.
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.
Not all of the possible platforms are enabled on the Mobile client setup screen. To enable a platform for your client device, do the following:
On the Mobile Devices screen, click Platforms.
On the Platforms screen in the Search pulldowns, select the language and either Disabled or All and click Go.
Select the platform name that you want to enable.
Enable the device by selecting Yes in the Enable pulldown.
Click OK. The device is now enabled and will be visible in the client setup screen.
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:
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.
On the Mobile Devices screen, click Platforms.
On the Platforms screen, select the platform name and click Extend.
Enter the custom platform name, path, and file name of the blank setup INF file you created in step 1. The setup INF file determines what is installed and how the client machine environment is modified. See Section 7.10, "Installation Configuration (INF) File" for instructions on how to modify the setup INF file after you have completed extending the platform.
Choose a Bootstrap group command from the list displayed. After the device bootstrap is complete, you can choose a group command to execute when it is completed. For example, choosing the device information command retrieves all of the device information to the Mobile Manager for viewing.
Enable or disable the device. If you enable the device by choosing Yes, then the user can log in, perform updates, synchronize, and perform other duties. If you disable the device by selecting No, then it can no longer perform work for the user.
Set Upgradable to Yes to retrieve all software updates for the device. If you want the device to continue to receive automatic software updates for the device, choose Yes. If you want the device to stay with the current software versions, choose No.
Click OK.
After you have extended your platform and given it a unique name, you should modify the setup INF file for this platform.
The client can now install your customized platform from the setup UI.
Navigate to the Mobile Devices page, as shown in Figure 7-6, and you can modify, delete, and extend any Mobile device.
To modify the configuration of a specific device, select the device and do the following:
The device name is displayed on the first line. You can modify the name of the device to anything that you want. For example, if you have a naming convention for all devices in your organization, modify this field to reflect this convention. The name defaults to the Mobile device platform.
Enable the device by selecting Yes; disable the device by selecting No. See Section 7.5.1, "Enabling or Disabling a Mobile Device" for more information.
Set Upgradable to Yes to retrieve all software updates for the device. If you want the device to continue to receive automatic software updates for the device, choose Yes. If you want the device to stay with the current software versions, choose No. See Section 7.7, "Managing Device Software Updates" for more information.
The installed address is displayed in the Address field. If the address is an IP address or a phone number, these may change at some point. You can enter the new addresses in this field.
Choose the Network Provider type. You can choose a different network provider than that with which you chose to install. The default list includes HTTP, WOR_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".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.
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:
You can send or schedule a command to be sent from the Mobile Manager. Navigate to the Mobile Devices page.
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".
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.
You can schedule a command to execute at a later time or at certain intervals. Select the device to which you want this command to be directed. Select Commands. Perform the following:
Click Schedule. The Schedule Command page appears.
As shown in Figure 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
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
Click Apply. The Mobile Manager displays a confirmation message.
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.
Using the Command Management page, you can modify existing device commands and create new device commands. To modify existing commands, do the following:
Click the required Command Name link. The Properties page for this command appears.
Enter the command name, description, and syntax in the corresponding fields. For more information on modifying these fields, see Section 7.6.3, "Creating New Commands".
To check the accuracy of the command syntax, click Syntax Check button. If no errors are found, the Mobile Manager displays a confirmation message.
Click Apply. The Mobile Manager displays a confirmation message.
You must configure the command to prompt for expected input parameters. For example, the Synchronize command requires that you define what type of refresh you want: fast, force, or push.
You can specify any parameters by modifying the command, as follows:
Click the required Command Name link. The Properties page for this command appears.
Add the parameter name and values, as follows:
The parameter name—This is the name specified in the OTL script.
A short description—The description is what is displayed when the user is prompted for the value of the parameter.
The display name—This is the description for each value. For example, the Synchronize databases command has three possible values: fast, force or push. However, the display values to describe each of these actual values is Fast Refresh, Force Refresh, and Push Only. These values are separated by a semi-colon, as follows: Fast Refresh;Force Refresh;Push Only.
Note:
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.
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:
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.
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.
Within Mobile Manager, navigate to the Command Management page.
Click Create Command.
In the Name field, pick a short name to identify the command within Mobile Manager.
In the Command field, put the name of the OTL file, without the .otl extension.
In the Description field, type in a sentence describing accurately the purpose of the command.
Click OK.
Back on the Command Management screen, select the command that you just created.
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.
Click Apply.
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.
To create group commands, do the following:
Click Create Group. The Create Group Command page appears.
Enter a unique Command Name, which will be used to identify the grouping.
Enter a description.
Select the set of existing commands that you want to execute together. The Command Weight feature controls the order in which the commands are executed. For example, a command with Weight 1 is executed first and a command with Weight 2 is executed next. Users must specify a weight for all the commands for the chosen group command.
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.Click Add. The Mobile Manager displays a confirmation message.
By default, all commands are enabled, which means that you can execute the command. If you want to disable a command, so that it can no longer be executed, do the following:
From the Mobile Devices page, click Administration.
Choose Command Management.
Select the command that you want to enable or disable.
Select either Yes for enable or No for disable on the Enabled pull-down.
Click Apply.
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.
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.
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"
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"
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:
Select the Mobile Devices tab in Mobile Manager.
Select the Platform tab to display all Oracle Database Lite Platforms.
Click Oracle Lite WIN32 platform to display its properties.
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.
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.
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:
Create a group with all of the users that you want to receive the update.
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:
Create a group with the MobileResourceManager.createGroup method.
Set the group update policy with the following method, where the value can be “major,” “minor,” or “false.”
group.setPolicy(ResourceConst.UPDATE_SOFTWARE, “major”);
Add all users to be within the group with the MobileResourceManager.addUsersToGroup method.
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"
In order to facilitate a major software update, the corresponding INF file must be modified to reflect the new version number. Mobile Server relies on the application version number to determine if the client software is out-of-sync.
To update your software, perform the following:
In the software INF file, the administrator modifies the version number for the application to the current version, as follows.
<setup name="Application Name" version="1.2.3">
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.
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 thepatch 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:
The administrator copies the patch INF files to the patch directory.
The administrator copies the new application files to the application directory.
The client user synchronizes with Mobile Server. Alternatively, the client user can invoke update.exe to check for the latest version of the software.
The Mobile Server checks for patches and sends all new patches to the client device.
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
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.
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
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
Click Hide to place the Oracle Database Lite Device Manager in the Windows System Tray.
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:
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:
Create a NetworkProvider class using Java. This class must implement the oracle.lite.provider.NetworkProvider interface.
Register the network provider through the Mobile Manager on the Network Management page, as follows:
Click Create on the Network Management page.
Input the network provider name, Java class name, and metadata.
Click OK.
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 |
|---|---|
|
|
Application directory of the application |
|
|
Application name |
|
|
Operating system directory |
|
|
Operating system type, which can be one of the following: WIN32, WINCE, LINUX. |
|
|
Operating system version. For example, NT, 95, XP, 3.0, and so on. |
|
|
Language or Location name, which can be US for English or JA for Japanese. |
|
|
Folder name of the Windows desktop. |
|
|
Device processor type. For example, x86, ARM, MIPS, and so on. |
|
|
Host name of the client device. |
|
|
User name |
|
|
HTTP Proxy Server URL, if any. |
|
|
Oracle Mobile Server URL. |
The following sections describe the INF file:
All Software Management actions are enclosed within the SETUP XML tag. The SETUP consists of a set of PROPERTIES, INITIALIZATION, INCLUSION of other INF files and INSTALLATION actions. All the four items must be child elements of the SETUP element. A sample INF file is given below.
<setup name="Oracle Lite" version="1.0.0.0">
<property>…. </property>
<init>…</init>
<include>…</include>
<install> …..</install>
</setup>
Setup may have the following attributes specified as XML tag attributes.
NAME - Application name (Mandatory).
VERSION - Application version number (Mandatory).
PACKAGE - Package Type, which can only be cab to specify a Windows CAB format.
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>
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>
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.
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 |
|---|---|
|
|
Lists all directories to be created. |
|
|
Lists all the files to be copied. |
|
|
Lists all the environment variables to be added to the Operating System. |
|
|
Registry keys and values to be added to the Windows Registry. |
|
|
ODBC driver and DSN to be created. |
|
|
JRE to be installed in the computer. |
|
|
Folder links to be created. For example, desktop, menu, and so on. |
|
|
INI (configuration files) to be updated. |
|
|
DLLs to be registered with Windows. |
|
|
Executable files to be launched during the installation process. |
|
|
Installation completion messages. |
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.
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".
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.
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.
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>
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>
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>
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.
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>
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.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.10, "Sample Device Manager Commands Using the Tag Language"
The allowed data types for the device manager are as follows:
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().
The Number data type represents either an integer, a double (float), or a large number.
The Integer object represents a four byte signed value. It is a primitive data type with no public methods.
The Long object represents an eight byte signed value. It is a primitive data type with no public methods.
The Double object represents a signed double (float) value. It is a primitive data type with no public methods.
The Boolean object has only two possible values of true or false. It is a primitive data type with no public methods.
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>
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.
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.
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.
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.
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.
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. |
OTL supports all regular scripting language syntax rules, such as Assignment, Conditional Constructs, and Sub Routines.
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")}"/>
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.
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"/>
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).
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>
The while statement enables you to execute a block of statements repeatedly until the condition check fails.
<c:while test="${a == 1}">
...
</c:while>
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>
Break from a loop with the break statement.
<c:foreach var="row" items="${rs}">
<c:if test="${row[0] == "1"}">
<c:break/>
</c:foreach>
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>
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}"/>
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.
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""/>
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.
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.4, "Get, Set, or Remove Session Attributes"
You can retrieve the existing HTTP request parameters and HTTP Session values, as follows:
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".
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.
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.
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).
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.
Use the System.GetURL() method for retrieving the request URL.
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.
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.
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.
Encodes the provided string.
System.URLEncode (String value)
Returns the given string as a URL encoded string.
Use System.OpenFile (String name) to open the file provided in the method parameter. Returns the File object.
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>
The device manager methods are accessed using DeviceManager.FunctionName syntax. These functions can only be used by trusted OTL scripts.
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);
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>
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/>
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")}"/>
|
 Copyright © 1997, 2010, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|