5
Database Programming for EPOC

This document discusses Oracle Lite database programming for EPOC devices. Topics include:

• Development Interfaces

• Developing Applications for the EPOC Platform

5.1 Development Interfaces

To develop Oracle Lite database applications, you can use the JDBC, ODBC or OKAPI interface.

Figure 5-1 Development Interfaces

5.1.1 JDBC

The Java Database Connectivity (JDBC) interface specifies a set of Java classes that provide an ODBC-like interface to SQL databases for Java applications. JDBC, part of the JDK (Java Developer's Kit) core, provides an object interface to relational databases. Oracle Lite supports JDBC 2.0 through an Oracle Lite, Type-2 JDBC driver that interprets the JDBC calls and passes them to Oracle Lite.

There is a sample JDBC application called AptData. See Section 5.2.3.3, "Creating the AptData JDBC Application" for information on compiling this example.

For more information on JDBC and Oracle Lite, see the Oracle Lite Java Developer's Guide.

5.1.2 ODBC

Open Database Connectivity (ODBC) is a call-level interface for accessing SQL databases. Developed by Microsoft, ODBC specifies a set of functions for connecting to databases, executing SQL statements, and retrieving query results. ODBC is a widely used specification supported by most database vendors, and provides the most portability.

The Mobile Development Kit for EPOC supports the complete ODBC 2.0 interface, with the exception of functions related to Java stored procedures. See the ODBC 2.0 documentation for more information on the ODBC interface.

5.1.3 Oracle Lite Object Kernel API (OKAPI)

The Oracle Lite Object Kernel API (OKAPI) is a C++ language interface that gives applications direct access to the Oracle Lite object kernel. You can use the OKAPI interface to develop Oracle9i Lite applications that make the most efficient use of limited system resources. Because applications that use OKAPI access the object kernel directly, they execute faster and use fewer resources than applications that access other interfaces.

The OKAPI library supports most common operations, including transactions, queries, inserts, updates, and deletes. See the Oracle9i Lite Object Kernel API Reference for complete Oracle Lite OKAPI information.

5.1.4 Mobile Sync API

The Mobile Sync API allows an application to initiate and monitor synchronization with a database from a client device rather than requiring that it be started from the Mobile Server. The default transport mechanism is HTTP, but other forms of transport can be specified if they are available.

Mobile Sync consists of five function calls and a control structure.

5.1.4.1 ocSessionInit

Initialize the synchronization environment.

Syntax

int ocSessionInit( ocEnv *env );

Parameters

Env

Pointer to an ocEnv structure buffer to hold the return synchronization environment.

Comments

This call initializes the ocEnv structure and restores any user settings that are saved in the last ocSaveUserInfo() call. ocEnv structure is passed as a parameter, and should be initialized by the caller. If the caller wants to overwrite the user preference information after the ocSessionInit() call, that can be done by calling ocSaveUserInfo().

5.1.4.2 ocSessionTerm

Free and cleanup synchronization environment.

Syntax

int ocSessionTerm( ocEnv *env );

Parameters

Env

Pointer to the environment structure returned by ocSessionInit.

Comments

De-initializes all the structures and memory created by the ocSessionInit() call. They should always be called in pair.

5.1.4.3 ocSaveUserInfo

Saves user settings.

Syntax

int ocSaveUserInfo( ocEnv *env );

Parameters

Env

Pointer to the synchronization environment.

Comments

This saves or overwrites the user settings into a file or database on the client side. The following information provided in the environment structure is saved:

• Username

• Password

• SavePassword

• NewPassword

• Priority

• Secure

• PushOnly

• SyncApps

• SyncNewPublication

For usage of these fields, please refer to the section Section 5.1.5, "Mobile Sync API Data Structures".

5.1.4.4 ocDoSynchroize

Starts the synchronization process.

Syntax

int ocDoSynchronize( ocEnv *env );

Parameters

Env

Pointer to the synchronization environment.

Comments

This starts the synchronization cycle. A round trip synchronization is activated if syncDirection is 0 (default). If syncDirection is 1, only upload (send) is performed. If syncDirection is 2, only download (receive) is performed. Performing an upload only synchronization is useful if client device does not want to download data from the server.

5.1.4.5 ocSetTableSyncFlag

Update the table flags for Selective Sync.

Syntax

ocSetTableSyncFlag(ocEnv *env, const char* publication_name, 
const char* table_name, short sync_flag)

Parameters

Env

Pointer to the synchronization environment.

publication_name

Used on CreatePublication(), which is part of the Mobile Server Admin API. See the Oracle9i Lite Consolidator Admin API Specification for more information.

If publication_name is NULL, sync_flag apply for all items in the publication.

table_name

This string is same as client_name_template of CreatePublication(). In OKAPI case, it is database_name + '.' + store, where store is CreatePublicationItem()'s third parameter. See the Oracle9i Lite Consolidator Admin API Specification for more information on CreatePublication() and CreatePublicationItem().

sync_flag

If 1 do synchronize, If 0 do not synchronize. Sync_flag is not stored persistently. Each time before ocDoSynchronize() you need to call ocSetTableSyncFlag().

Comments

This function allows the client applications to select the way specific tables are synchronized.

Set sync_flag for each table or each publication. If sync_flag = 0, the table is not synchronized.

5.1.5 Mobile Sync API Data Structures

5.1.5.1 ocEnv

ocEnv is the data structure used by all the Mobile Sync functions to hold internal memory buffers and state information. Before using the structure, the application must pass it to ocSessionInit to initialized the environment.

The environment structure also contains fields that the caller can update to change program the way Mobile Sync functions work.

typedef struct ocEnv_s {
                       // User infos
char username[MAX_USERNAME];     // Mobile Sync Client id 
char password[MAX_USERNAME];     // Mobile Sync Client password for 
                       // authentication during sync 
char newPassword[MAX_USERNAME];     // resetting Mobile Sync Client password 
                       // on server side if this field is not blank 
short savePassword;      // if set to 1, save 'password' 
char appRoot[MAX_PATHNAME];     // dir path on client device for deploying files
short priority;     // High priority table only or not
short secure;     // if set to 1, data encrypted over the wire 
enum {
OC_SENDRECEIVE = 0,     // full step of synchronize
OC_SENDONLY,     // send phase only
OC_RECEIVEONLY,     // receive phase only

                       // For Palm Only
OC_SENDTOFILE,     // send into local file | pdb
OC_RECEIVEFROMFILE     // receive from local file | pdb
}syncDirection;     // synchronize direction

enum {
OC_BUILDIN_HTTP = 0,     // Use build-in Http transport method
OC_USER_METHOD     // Use user defined transport method
}trType;           // type of transport

ocErrorexError;     // extra error code

ocTransportEnvtransportEnv;     // transport control information 

                       // GUI related function entry
progressProcfnProgress;     // callback to track progress; this is optional

                 // Values used for Progress Bar. If 0, progress bar won't show.
longtotalSendDataLen;      // set by Mobile Sync API informing transport total 
number of
                       // bytes to send; set before the first fnSend() is called
long totalReceiveDataLen;     // to be set by transport informing Mobile Sync 
API 
                       // total number of bytes to receive; 
                       // should be set at first fnReceive() call. 
void* userContext;     // user defined context
void* ocContext;     // internal use only
short logged;     // internal use only
long bufferSize;     // send/receive buffer size, default is 0
short pushOnly;     // Push only flag
short syncApps;     // Application deployment flag
} ocEnv;

5.1.5.2 ocTransportEnv

This structure is used to override the built-in transport functions. By providing the list of functions in the structure, applications can define their own implementation for the transport layer used by the synchronization engine.

typedef struct ocTransportEnv_s {
void* ocTrInfo;            // transport internal context

                  // for built-in Http, maped to ocTrHttp

connectProc fnConnect;     // plug-in callback to establish a connection from

                  // device to server

disconnectProc fnDisconnect;     // plug-in callback to dismantle connection 
from

                   // device to server

sendProc fnSend;           // plug-in callback to send data 
receiveProc fnReceive;     // plug-in callback to receive data 
}ocTransportEnv;

5.2 Developing Applications for the EPOC Platform

EPOC is a 32-bit operating system optimized for wireless information devices, such as smartphones and communicators, and for handheld computers. EPOC is a native C++ operating system. Oracle Lite for EPOC uses the standard EPOC C++ development environment, which is comprised of the EPOC C++ SDK and Microsoft Visual C++.

The EPOC development cycle involves the following steps:

1. Use Microsoft Visual C++ to build the application as x86 binaries. This enables the developer to execute and debug the application from within the development environment using the WINS emulator supplied with the EPOC C++ SDK.

2. After testing and debugging the application on the emulator, recompile the application into ARM binaries using the GNU C++ compiler supplied with the EPOC C++ SDK.

3. Transfer the application to the EPOC device for final testing.

4. Deploy the application to end users. See Chapter 6, "Using the Packaging Wizard", for information on deploying applications to devices.

5.2.1 Creating a Project File

When creating a new project in Visual C++, set up your project file (.mmp file) as follows.

Include the Oracle Lite header files in the include path:

USERINCLUDE \<Oracle_Home>\Mobile\SDK\EPOC\SDK\Include 

List the libraries to be linked.

For OKAPI:

LIBRARY OKAPI.LIB 

For ODBC:

OLODBC.LIB

Include the necessary header files in your code. Most of the necessary OKAPI definitions are in the okapi.h file. For ODBC, include sql.h and sqlext.h.

5.2.2 Compiling Mobile SQL for the Emulator

The following section shows how to build the Mobile SQL sample application from the command line. If you wish run the application from Developer Studio, you will need to make the vc5 targets instead of the wins targets. This section uses the sample application included with Oracle Lite to illustrate how to compile for the WINS Emulator and the EPOC device. This section assumes that you have installed the EPOC C++ SDK on your development environment.

The Oracle_Home\Mobile\SDK\epoc\sdk\samples\msql\code\msql.mmp file must be edited to set the correct paths for the PROJECT, SUBPROJECT, USERINCLUDE, and SYSTEMINCLUDE. These paths may be different for your particular installation.

5.2.2.1 Building the Emulator Debug Version of Mobile SQL

To compile a version of Mobile SQL for use on the emulator, open a console window and enter the following commands. Oracle_Home represents the drive letter and base directory where you installed the Mobile Development Kit. This process involves batch files which have default directory assignments which may need to be adjusted for your system.

1. The msqlaif.bat file copies the resulting .aif file into the emulator path. Be sure the path within the msqlaif.bat file correctly matches your emulator directory. Also, the EPOC tool aiftool.bat contains a hard-coded include path "..\..\epoc32\include" which you may need to edit.

   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\msql\code> makmake -makework msql 
   wins
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\msql\code> makmake msql wins
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\msql\bitmap> msqlaif
   
   

2. The EPOC tool eikrs.bat contains a hard-coded include path "..\..\epoc32\include" which only works if the source is in a two-level directory structure. The msql directory contains a copy of eikrs.bat which uses "\epoc32\include". You might need to modify this path if your EPOC SDK is not installed to the root directory.

   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\msql\code> eikrs msql sc
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\msql\code> nmake -f msql.wins
   
   

3. After successfully compiling the debug version, run the debug emulator with the following command:

   \epoc32\release\wins\deb\epoc.exe
   

4. Select the mSql icon from the Extras bar to run Mobile SQL

5.2.2.2 Building the Emulator Release Version of Mobile SQL

The steps for building this version of Mobile SQL are similar to the one listed in Section 5.2.2.1, "Building the Emulator Debug Version of Mobile SQL". This process involves batch files which have default directory assignments which may need to be adjusted for your system.

1. Open a console and type the following commands:

   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\msql\code> makmake -makework msql 
   wins
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\msql\code> makmake msql wins
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\msql\bitmap> msqlaif
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\msql\code> eikrs msql sc
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\msql\code> nmake -f msql.wins rel
   
   

2. Run the non-debug version of the emulator with this command:

   \epoc32\release\wins\rel\epoc.exe
   

3. Select the mSql icon from the Extras bar to run Mobile SQL

5.2.3 Compiling and Testing okdemo on the Development System

This section uses the sample application included with Oracle Lite to illustrate how to compile for the WINS Emulator and the EPOC device. This section assumes that you have installed the EPOC C++ SDK on your development environment.

The source code for the sample application is located in the Oracle_Home\Mobile\SDK\EPOC\sdk\Samples\okdemo\er5ui directory. Paths within the okdemo.mmp file may require modification depending on where the samples are installed. Check to make sure that the paths are correct before you begin creating project files or make-files.

5.2.3.1 Compiling and Running okdemo on the WINS Emulator

To compile the application for the WINS Emulator:

1. Open a console window and enter the following commands:

   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\okdemo\er5ui> makmake -makework 
   okdemo wins
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\okdemo\er5ui> makmake okdemo wins
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\okdemo\bitmap> okdaif
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\okdemo\er5ui> eikrs okdemo sc
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\okdemo\er5ui> nmake -f okdemo.wins 
   rel
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\okdemo\data> mkdir
   \epoc32\wins\c\system\apps\okdemo
   

2. The application does not run without an existing database. If you wish to use the provided sample data, copy the database files to the following directory:

   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\okdemo\data> copy *.*
   \epoc32\wins\c\system\apps\okdemo
   
   

5.2.3.2 Compiling and Running the Debug Version of okdemo

To compile the debug version of the okdemo application for the WINS Emulator:

1. Open a console window and enter the following commands:

   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\okdemo\er5ui> makmake -makework 
   okdemo wins
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\okdemo\er5ui> makmake okdemo wins
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\okdemo\bitmap> okdaif
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\okdemo\er5ui> eikrs okdemo sc
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\okdemo\er5ui> nmake -f okdemo.wins
   Oracle_Home\Mobile\SDK\epoc\sdk\Samples\okdemo\data> mkdir
   \epoc32\wins\c\system\apps\okdemo
   
   

2. The application does not run without an existing database. If you wish to use the provided sample data, copy the database files to the following directory:

    Oracle_Home\Mobile\SDK\epoc\sdk\Samples\okdemo\data> copy *.* 
   \epoc32\wins\c\system\apps\okdemo
   
   

5.2.3.3 Creating the AptData JDBC Application

Open a console window and enter the following command.

Oracle_Home\Mobile\SDK\epoc\sdk\Samples\AptData> build

After building, run the sample with the following command:

\epoc32\wins\c\system\apps\aptdata> \epoc32\release\wins\deb\java_g.exe -Mlarge 
-- -cd c:\System\Apps\AptData AptData

5.2.4 Compiling for the EPOC Device

For device builds, you compile from the DOS command line using the GNU C++ compiler supplied with the EPOC C++ SDK. The command nmake is used to compile and link the application.

To compile the application for the EPOC device, open a DOS window and enter the following commands:

C:\Oracle_Home\Mobile\SDK\EPOC\SDK\Samples\okdemo\er5ui> makmake -makework 
okdemo marm 
C:\Oracle_Home\Mobile\SDK\EPOC\SDK\Samples\okdemo\er5ui> makmake okdemo marm 
C:\Oracle_Home\Mobile\SDK\EPOC\SDK\Samples\okdemo\er5ui> eikrs okdemo sc 
C:\Oracle_Home\Mobile\SDK\EPOC\SDK\Samples\okdemo\er5ui> nmake -f okdemo.marm 

5.2.5 Installing the Application on the EPOC Device

This section uses the sample application to illustrate how to install an Oracle Lite for EPOC application to the EPOC device.

Before you can install an application, you must create an installation (.sis) file using the makesis utility. The .sis installation file contains all the files that are necessary to run the application on the device. You can create a .sis file for your application using the makesis utility included with the EPOC C++ SDK. For information about the makesis utility, see the EPOC C++ SDK documentation.

To install your application on a EPOC device, you must have an available COM port and the PsiWin utility installed on your computer. The PsiWin utility transfers the application and related data to the device over the serial cable.

To create an installation file for the sample application, open a DOS window and enter the following command:

C:\Oracle_Home\Mobile\SDK\EPOC\SDK\Samples\okdemo\er5ui makesis okdemo.pkg

To install the sample application:

1. Connect the EPOC device to the assigned COM port on your PC with the supplied serial cable.

2. Ensure that the EPOC Remote Link is set to Cable. You can change this setting through the System Tools menu on the EPOC device.

3. Select Install New Program from the PsiWin program group. The Select Installation File dialog appears.

4. Select okdemo.sis from Oracle_Home\Mobile\SDK\EPOC\sdk\runtime\Install. Click the OK button.

The PsiWin utility installs the application on the EPOC device.