14 Using Symbian Devices

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. This chapter helps to show what is supported. Use the rest of the documentation for more details on those areas.

14.1 Support Symbian Devices in Oracle Database Lite

When you are developing applications for the Symbian environment, you can use the following:

  • For your development language, you can use either C or C++ APIs.

  • Symbian applications that need a standard interface and work with multiple database engines can use either the Open Database Connectivity (ODBC) interface or some other interface built on top of ODBC.

14.2 Invoke Synchronization from Applications on Symbian Devices

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.

14.2.1 How To Write A Program Using Oracle Database Lite 10g

Note:

For an example, see the CSQL example in the <EPOCROOT>\OliteEx\CoreDB\CSQL directory.

Perform the following to enable database (ODBC) functionality:]

  1. Include sql.h and sqlext.h in your source code, as follows:

    #include <sql.h>
#include <sqlext.h>

  2. Add the include path SYSTEMINCLUDE \epoc32\include\olite in the .mmp file.

  3. Add the library LIBRARY olod2040.lib in the .mmp file.

  4. Oracle Database Lite 10g uses STDLIB resources. You need to call CloseSTDLIB() after all database operations to free up resources.

  5. Character data stored in Oracle Database Lite 10g 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, include utf.h and link charconv.lib.

    • CnvUtfConverter::ConvertFromUnicodeToUtf8()

    • CnvUtfConverter::ConvertToUnicodeFromUtf8()

  6. Oracle Database Lite 10g uses STDLIB; thus, you must release all resources after you finish any ODBC operations. To release all resources, perform the following:

    1. Add #include <sys/reent.h>.

    2. Invoke the CloseSTDLIB() method after each SQLFreeEnv() call.

14.2.2 Prepare Your Application for Synchronization

Note:

For an example, see the mSync example in the <EPOCROOT>\OliteEx\Sync\mSync directory.

  1. Include ocapi.h in your source code, as follows: #include <ocapi.h>.

  2. Add the include path SYSTEMINCLUDE \epoc32\include\olite in your .mmp file.

  3. Add the library LIBRARY ocapi.lib in your .mmp file.

14.2.3 How to Use the Synchronization API for Symbian Devices

The Synchronization API does not run under the eshell.exe. For starting synchronization, the application performs the following:

  1. Invoke the ocSessionInit() method.

  2. Invoke the ocDoSynchronize() method, which will return before the synchronization completes.

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

  4. Once synchronization completes, then invoke the ocSessionTerm() method.

For an example, see the msync.cpp sample code.

14.3 Using a JDBC Driver for J2ME CLDC to Connect to the Database

You can use a JDBC driver for J2ME CLDC—in a limited capacity—for Java applications to connect and update the database. Full details on the JDBC driver for J2ME CLDC, which can be used on Symbian devices is documented in Section 10.8.1.2, "JDBC Driver for J2ME CLDC".

14.4 Use the Utility Tools on Symbian Devices

To use the database utility tools on the emulator, perform the following:

  1. Open a command prompt window.

  2. Change directory to the <EPOCROOT>\epoc32\release\wins\udeb directory.

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

  1. Open eshell.exe on the device. Consult with the device manufacturer for the eshell.exe program.

  2. Type the tool name with appropriate arguments. See the Oracle Database Lite 10g documentation for more information.