Oracle® Database Lite Developer's Guide Release 10.3 Part Number E12090-02 |
|
|
View PDF |
Symbian support is a relatively new addition to the supported devices in Oracle Database Lite. As such, not all functionality that exists for other devices is available for Symbian devices. Supported functionality includes the client Oracle Lite database, access to the database through ODBC and JDBC and synchronization. However, at this time, no device management is supported.
This chapter helps to describe the supported features and how to use them on Symbian devices. You can read the rest of the Oracle Database Lite documentation for more details on these areas.
Section 9.1, "Installing Oracle Database Lite on Symbian Devices"
Section 9.2, "Developing Applications for Symbian Devices to Use Oracle Database Lite"
Section 9.3, "Using CSQL, ODBC or JDBC to Access Oracle Database Lite"
Section 9.4, "Invoking Synchronization from Applications on Symbian Devices"
The following sections describe the pre-requisites and installation steps for Symbian devices:
Your development environment must include Oracle Database Lite 10g as the encompassing platform. For developing native applications with Oracle Database Lite 10g on a Symbian platform, see the following:
The following devices are supported for the Symbian 7.x platform:
Nokia 6620
Nokia 9500
Motorola M1000
Sony Ericsson P910
The following devices are supported for the Symbian 8.x platform:
Nokia 6630, which is also known in Japan as V702NK
Nokia 6680
The following devices are supported for the Symbian 9.x platform:
Nokia E61
We support Symbian Operating System versions 7.x, 8.x, 9.x, UIQ 2.0, 2.1.
The following are the supported development environments for Symbian 7 or 8:
Microsoft Visual Studio 6.0
Microsoft Visual Studio .Net
The supported development environment for Symbian 9 is Carbide.C++ Version 1.1 or Version 1.2.
We assume that you have a basic Symbian OS development knowledge to develop your application.
Before installing Oracle Database Lite, perform the following:
Installing the SDK:
You must install the SDK for the target device on the development machine. For example, if you are using a Motorola device, go to www.motorola.com
and download the M1000 SDK on the development machine.
To build any application, install the S60 3rd Edition SDK for building and testing on the emulator. In addition, to build for the target device, install the CSL Toolchain (GCCE), which is a plug-in with the S60 3rd Edition SDK. The Toolchain has to be separately installed even though it has been downloaded with the SDK.
Browsing, installation and uninstallation on the target device: Install the target device development suite, which is named as either "PC Suite" or "Desktop suite."
Using command-line prompts on your device: Install eshell.exe
on the device. In addition, we recommend that you purchase a hardware keyboard to connect to your phone to type in the eshell.exe
window.
Using JDBC: JDBC applications use the Multi-User (MU) component to connect to the Oracle Lite database. For Symbian 9, MU requires the Open-C library supplied by Nokia Open-C forum. Install Open-C sis files, such as openc_glib.sis
, openc_ssl.sis
and pips_s60_wp.sis
, on the device.
The following sections describe how to install Oracle Database Lite for the Symbian platform for the development environment or the Symbian device:
Section 9.1.3.1, "Installing Oracle Database Lite for Symbian on the Development PC"
Section 9.1.3.2, "Installing Oracle Database Lite on the Symbian Device"
The following sections describe how to install for each type of Symbian platform:
Within the Oracle Universal Installer, perform the following to install the Symbian Development Kit on the developement PC:
Select Custom.
Select Oracle Database Lite MDK for Symbian 7 & 8.
Enter the directory where you installed the Symbian SDK, which is the same as the EPOCROOT
.
When you complete the installation, the following files are unzipped:
Header files are placed in the epoc32\include\olite
directory.
ARMI (urel) .lib
files are placed in the epoc32\release\armi\urel
directory.
THUMB (urel) .lib
files are place in the epoc32\release\thumb\urel
directory.
WINS (udeb) binaries and .lib
files are copied into the epoc32\release\wins\udeb
directory.
Initial configuration files are copied into the epoc32\wins\c\System\Data
directory.
Samples are copied into the OliteEx
directory.
Within the Oracle Universal Installer, perform the following to install the Symbian Development Kit on the developement PC:
Select Custom.
Select Oracle Database Lite MDK for Symbian 9.
Enter the directory where you installed the Symbian SDK, which is the same as the EPOCROOT
.
When you complete the installation, the following files are unzipped:
Header files are placed in the epoc32\include\olite
directory.
Initial configuration files are copied into the epoc32\winscw\c\System\Data
directory.
Samples are copied into the OliteEx
directory.
The ARMV5 (lib
) .dso
files are placed in the epoc32\release\winscw\udeb
directory.
The WINSCW (udeb
) binaries and .lib
files are placed in the epoc32\release\winscw\udeb
directory.
When you build your application, you need to include the header files and link against the libraries.
Once your application is built and tested, install the application and Oracle Database Lite on the Symbian platform as follows:
For most devices, copy and install the correct SIS olite_core.sis
file to the device using PC Suite, Desktop Suite, or an external memory card. This installs all of the Oracle Database Lite files, including the DLLs and executables.
The following lists the correct SIS file for each platform:
For the Symbian 7 or 8 platform, install the following SIS files:
a. Use the olite_core.sis
file or for the Sony Ericsson P910 device, the olite_core_uiq2.sis
file.
b. If using JDBC, then also install the olite_server.sis
or for the Sony Ericsson P910 device, the olite_server_uiq2.sis
file
For the Symbian 9 platform, install the olite_core.sis
file.
This installs the Oracle Database Lite binaries into the target drive. The default location is the !:\System\Libs\
directory.
Note:
You may chose a different target directory during installation.If the configuration files do not already exist on the device, then the following files are copied into the C:\System\Data\
directory: polite.ini
, odbc.ini
, and olite40.msb
.
For Symbian 7 or 8, you have the option to install the Oracle Database Lite 10g Utility Tools. The Symbian 9 installation automatically installs all tools with the base install.
Note:
These utility tools are command line based programs; thus, you need to install and use theeshell.exe
program to execute them.For most devices, copy the olite_tools.sis
file to the target device using PC Suite, Desktop Suite, or a memory card. If you are using a Sony Ericsson P910, then copy the olite_tools_uiq2x.sis
file.
Install either the olite_tools.sis
file or if using the Sony Ericsson P910 device, the olite_tools_uiq2x.sis
file. This copies the following files into the target directory (which by default is the !:\System\Programs\
directory): CREATEDB.EXE
, REMOVEDB.EXE
, ENCRYPDB.EXE
, DECRYPDB.EXE
, and ODBINFO.EXE
.
Note:
You may chose a different target directory during installation.Install your application.
Symbian applications that need a standard interface and work with multiple database engines can use either the JDBC interface, the ODBC interface or some other interface built on top of ODBC, as follows:
Your application can use ODBC to access the database directly.
To use JDBC, then the application must access the database through the multi-user service for the JDBC connection. Therefore, if you plan to use JDBC, you must also install and configure for the multi-user service.
When you are developing applications for the Symbian environment, you can use the following:
For your development language, you can use C, C++, or Java APIs.
Symbian applications that need a standard interface and work with multiple database engines can use either the JDBC interface, the ODBC interface or some other interface built on top of ODBC.
Your application can use ODBC to access the database directly; however, if you want to use JDBC, then you must access the database using the multi-user service for the JDBC connection.
The following sections describe how to use ODBC or JDBC to access the Oracle Lite database on the Symbian device:
Section 9.3.1, "Using CSQL to Connect to the Database on Symbian"
Section 9.3.2, "Using ODBC to Connect to the Database on Symbian"
Section 9.3.3, "Using JDBC to Connect to the Database on Symbian"
CSQL is a sample application provided in the Oracle Database Lite installation for Symbian. It is an ODBC-based application with which the user can perform SQL operations on the Oracle Lite database. The application can be built for the target device as well as the emulator.
You can configure how CSQL accesses the Oracle Lite database in the polite.ini
and odbc.ini
configuration files.
When you are developing ODBC based applications, perform the following:
Note:
For an example, see the CSQL example for Symbian in the<EPOCROOT>\OliteEx\CoreDB\CSQL
directory.Include sql.h
and sqlext.h
in your source code, as follows:
#include <sql.h> #include <sqlext.h>
Add the include path SYSTEMINCLUDE \epoc32\include\olite
in the .mmp
file.
Add the library LIBRARY olod2040.lib
in the .mmp
file.
Oracle Database Lite uses STDLIB resources. You need to call CloseSTDLIB()
after all database operations to free up resources.
Character data stored in Oracle Database Lite must be in UTF-8 encoding.
If you write APP application, then you might need to convert between UCS and UTF-8 encodings back and forth. For more information, refer the Symbian API reference.
You can use the following two functions to convert between encodings:
Note:
To use these functions, includeutf.h
and link charconv.lib
.CnvUtfConverter::ConvertFromUnicodeToUtf8()
CnvUtfConverter::ConvertToUnicodeFromUtf8()
Oracle Database Lite uses STDLIB
; thus, you must release all resources after you finish any ODBC operations. To release all resources, perform the following:
Add #include <sys/reent.h>
.
Invoke the CloseSTDLIB()
method after each SQLFreeEnv()
call.
On the Symbian platform, only one JDBC connection is supported. You can use a JDBC driver for J2ME CLDC—in a limited capacity—for Java applications to connect and update the database. The CLDC compliant JDBC driver for the Oracle Lite is located in the olitejdbccldc.jar
file. The API documentation is available in the Oracle Lite SDK for Symbian. Otherwise, you can see Section 7.8.1.2, "JDBC Driver for JDBC CLDC" in the Oracle Database Lite Client Guide for more details.
When you use JDBC for connecting to the Oracle Lite database, you have to use the Multi-User listener. Symbian does not support JNI to map the Java request into native code. Therefore, as shown in Figure 9-1, JDBC accesses the Oracle Lite database in client/server mode using a TCP/IP connection. The default TCP/IP port for the Multi-User listener is port 1160 .
Figure 9-1 Java Application on Symbian Accessing Database
Within the main Oracle Database Lite documentation, there is a discussion on how to configure and start the Multi-User service. However, for the Symbian platform, as soon as the SIS file is installed, the Multi-User service automatically starts and receives all incoming requests on port 1160.
The following sections describes how to set up your application to use the synchronization APIs for use on a Symbian device. Also, see Section 4.1, "Synchronization APIs For C or C++ Applications" for information on how to use the C or C++ APIs available to start synchronization programmatically within your application.
Section 9.4.2.1, "Prepare Your Application for Synchronization"
Section 9.4.2.2, "How to Use the Synchronization API for Symbian Devices"
MSync is a sample application provided in the Oracle Lite installation. This can be used to synchronize the Oracle Lite database on the Symbian device with the Mobile Server. Msync is included in the binary for Symbian 9 devices.
Before you can use MSync on the Symbian 9 device, you must configure the following parameters in the msync.ini
configuration file:
USER=
<username>
PASS=
<password>
URL=
<url or IP address>
The msync.ini
file is located on the same drive where you installed Oracle Database Lite.
For example, the following parameters show that the Mobile Server IP address is 192.168.1.2
, the application user is S11U1
, and the password is abcd
.
USER=S11U1 PASS=abcd URL=192.168.1.2
The following sections describe how to invoke synchronization from within the application:
Section 9.4.2.1, "Prepare Your Application for Synchronization"
Section 9.4.2.2, "How to Use the Synchronization API for Symbian Devices"
Note:
For an example, see the mSync example in the<EPOCROOT>\OliteEx\Sync\mSync
directory.Include ocapi.h
in your source code, as follows: #include <ocapi.h>
.
Add the include path SYSTEMINCLUDE \epoc32\include\olite
in your .mmp
file.
Add the library LIBRARY ocapi.lib
in your .mmp
file.
The Synchronization API does not run under the eshell.exe.
For starting synchronization, the application performs the following:
Invoke the ocSessionInit()
method.
Invoke the ocDoSynchronize()
method, which will return before the synchronization completes.
To determine if the synchronization is complete, the GUI application continues to invoke the ocGetLastError()
method. If it returns -1, then synchronization is still executing. With any other value, the synchronization is complete.
Once synchronization completes, then invoke the ocSessionTerm()
method.
For an example, see the msync.cpp
sample code.
The utility tools that are available for Symbian are as follows: csql
, msync
, createdb
, removedb
, encryptdb
, decryptdb
, and odbinfo
.
Note:
Before you can use any utility tools, ensure that they are installed on the device, as described in Section 9.1.3, "Installing Oracle Database Lite". For Symbian 9, all tools are automatically installed.To be able to use the utility tools, see the appropriate section based upon the Symbian platform that you are using:
To use the database utility tools on the emulator, perform the following:
Open a command prompt window.
Change directory to the <EPOCROOT>\epoc32\release\wins\udeb
directory.
Type the tool name with appropriate arguments. See the Oracle Database Lite 10g documentation for more information.
To use the database utility tools on the device, perform the following:
Open eshell.exe
on the device. Consult with the device manufacturer for the eshell.exe
program.
Type the tool name with appropriate arguments. See the Oracle Database Lite 10g documentation for more information.
To use the database utility tools on the emulator or device for Symbian 9, perform the following:
Click the installation folder on the emulator or device and then select the utility icon.
Follow the UI menu and provide the appropriate arguments for the tools.