Oracle® Database Lite Developer's Guide
10g (10.0.0) Part No. B13788-01 |
|
![]() Previous |
![]() Next |
This document discusses building Oracle Database Lite 10g applications for Palm devices. Oracle Database Lite 10g for Palm OS supports Simple Object Database Access (SODA) and Open Database Connectivity (ODBC) as programming interfaces. This document also describes how to build and run Oracle Database Lite 10g applications using Metrowerks CodeWarrior 9. It includes the following topics:
Section 7.1, "Installing Oracle Database Lite Runtime on the Device"
Section 7.2, "Uninstalling or Replacing Oracle Database Lite Runtime"
Section 7.3, "Running Oracle Database Lite on Palm OS Emulator"
Section 7.4, "Running Oracle Database Lite on Palm OS Simulator"
Section 7.9, "Packaging your Application with Oracle Database Lite Runtime"
You need to install the Runtime\olSetup.prc
on the device to run Oracle Database Lite applications. If you are installing on the emulator, click olSetup icon in the "Oracle Lite" program group, If you are installing on the device using HotSync, olSetup will be run automatically.
Note that a sync with mobile server will replace Oracle Database Lite runtime on the device with whatever is installed on the server. Choose "Ignore apps" option in synchronization settings to suppress this behavior.
The file tutorial.html walks you through building a small application for Palm. The file is located in the following directory:
&fmv624;\Mobile\Sdk\Palm\doc\tutorial.html
The top-level list of the Palm-specific documentation which contains the links from which you can access these various documents (including the tutorial and the SODA API Reference) is located in the following directory:
&fmv625;\Mobile\Sdk\Palm\doc\index.html
Oracle Database Lite Runtime includes deLite, an application that can be used for the following tasks:
Remove all Oracle Database Lite, but leave applications and shared libraries in place. This option can be used if an Oracle Database Lite became corrupted (the application crashes or displays invalid data). Do a sync to restore the user's data to a device.
Remove both Oracle Database Lite Runtime and the databases. Use this option if you no longer need Oracle Database Lite on the device or before manually installing a new version.
Uninstall Oracle Database Lite and then install an up to date version from the specified mobile server (by default, the same one used for sync. This can be used to reset the device to known version of Oracle Database Lite or upgrade from a version prior to 5.0.2.9.0, that doesn't support automatic upgrade.
To install Oracle Database Lite runtime on the PalmOS emulator, choose "Install application/database" from the right-click menu and select olSetup.prc in mobile client or mobile SDK directory. Run olSetup once to install the Oracle Database Lite runtime. Now go to emulator debug options and make sure "MemMgr semaphore" and "Proscribed function calls" checkboxes are cleared. Oracle Database Lite runtime uses these features properly and the emulator warnings for these conditions should be disabled or ignored.
Go to Preferences and check "Redirect NetLib calls to Host TCP/IP". This will allow you to synchronize with the Mobile Server using the emulator.
Oracle Database Lite works properly on PalmOS 5.x devices, however the debug version of the PalmOS Simulator crashes when running olSetup because of a bug in the simulator. The release version of the simulator works properly.
Oracle Database Lite comes with several libraries that do not directly provide database functionality, but are used by the rest of the runtime. Follow the following steps to add these libraries to your project:
Replace the CodeWarrior with cwStartup.lib (or cwStartup4B.lib if using 4 byte integers). Make sure the library is in the first segment. Add pslm_app.lib to the first segment as well. See pslm.html for an explanation.
Add libc_stub.lib and olstd.lib to any segment of your application.
Include olstd.h in your source files
If your PilotMain is started with a launch code that allows access to global variables, call psCLibrary.open(true) before using Oracle Database Lite.
Use Constructor to generate a PREF resource and set stack size of your application to 8K.
Oracle Database Lite interfaces may change between versions. To avoid compatibility problems, Oracle Database Lite shared libraries will return errors if the application is not linked with the matching version of the stub library. When upgrading Oracle Lite runtime, you need to re-link your application with the new stubs.
These steps allow access to Oracle Database Lite C library, which provides many of the ANSI C functions which are otherwise missing from the PalmOS platform. Examine libc.h for a list. olstd.h defines C++ classes such as a hash table, which are documented as a part of SODA.
Libc.h defines standard I/O functions such as printf for debugging purposes. To see the output, run "java BigBrother" on the same PC that is running Palm emulator or "java BigBrother <IP Address>" to capture output from a PalmOS device connected through PPP. Note that the program will be blocked when it tries to use printf until the listener is connected.
To use SODA, add the following libraries to your project: olSDT.lib
, okapi_stub.lib
, soda1.lib
and soda2.lib
. Include 'soda.h
' in the source files.
The SODA documents are located in the following directory.
&fmv646;\Sdk\soda\index.html
To use SODA Forms, include all the SODA libraries and also add sodaform.lib
and sodares.rsrc
into your application. The later file contains UI resources used by SODA Forms. Avoid using resource ids above 30000 for your own resources to prevent conflicts.
Include "sodaform.h
" in your source files.
The file sodaforms.htm discusses SODA Forms, a library for rapid development of data entry applications on Palm. The file is located in the following directory.
&fmv647;\Mobile\Sdk\Palm\doc\index.html
To use ODBC (actually a subset of standard ODBC that we support on Palm), include "odbc.h
" and link with odbc_stub.lib
.
The file olSetup.prc is the Oracle Database Lite installer which extracts a number of .prc files when synchronized with a device or run on the emulator. It is possible to make a version of olSetup with additional applications by modifying and running makesetup.bat in the Sdk/setup directory.
The next step is to remove "olSetup application" in ORACLE_HOME
\Mobile\sdk\Palm\sdk\setup
directory from the Mobile Server and publish another application with the new version of olSetup.prc as one of the deployed files. The following events will happen on the next sync:
Any changes to data will be first pushed to the server.
Oracle Database Lite libraries and databases will be uninstalled from the device.
New Oracle Database Lite runtime (and any applications you added) will be installed from olSetup.prc
A full synchronization will be done with the server to restore the databases.
This process will upgrade the version of Oracle Database Lite on the device and avoid any database compatibility problems.
In addition to adding your application, you might want to customize Oracle Database Lite runtime itself. The following changes can be made in makesetup.bat:
Table 7-1
Change | Effect |
---|---|
Add olEncryptTransport.prc | Enable AES encryption of data during synchronization. Note that this does not work with external authentication on the server side. |
Remove olLibCrypto.prc | Disable AES encryption altogether, including database encryption. |
Remove olCompressTransport.prc | Disable compression during sync. Can be useful on devices with very little memory |
Remove odbc.prc | If you are only using SODA |
Remove msql.prc | You may not need this tool on end-user devices |
Substitute okapi.prc from Sdk\setup directory with okapi.prc from Sdk\setup\card subdirectory (copy okapi.prc from Sdk\setup\card one level up) and rerun makesetup.bat | Will create olSetup.prc for the storage card version of Oracle Database Lite. Enables you to use the storage card on palm device to store Oracle Database Lite databases instead of main memory. This will greatly relax the limits on the database size (will be limited only by storage card size). Olite databases will be located in OLDB directory of the storage card. Since storage card support constitutes different Olite installation, we do not currently support accessing both storage card and in-memory databases from the same application. |
For detailed information on the Palm Shared Library Manager (PSLM), refer Chapter 8, "Palm Shared Library Manager (PSLM)".