Converting CEDB to EDB

 

<I know this is not a question... but I want to make sure this information gets out to the public as fast as possible>

Porting Applications from CEDB to EDB

Luis Eduardo Cabrera
Microsoft Corporation

May 2005

Applies to:
   Windows Mobile-based devices

   eMbedded Visual C++

   Visual Studio 2005

   CEDB

   EDB

 

Summary: Learn how to port applications that use CEDB to EDB. It is intended for developers that have written CEDB applications for Windows Mobile devices that use CEDB (2003, 2003 Second Edition) and that would like to port their applications to target Windows Mobile 5.0 devices. (4 printed pages)

Contents

Introduction

Comparing EDB with CEDB
Porting your Application

#define EDB

Pass EDB_MOUNT_FLAG to CeMountDBVol

Use the Recommended APIs

Read the description of the EDB API on msdn

Sample code

Conclusion

Introduction

The purpose of this white paper is to explain how to modify an existing application that uses CEDB as a data store to use EDB. It outlines some of the differences between CEDB and EDB and then walks through some actions required to convert an existing CEDB application to EDB. CEDB has been deprecated in Windows Mobile 5.0, so developers writing for this platform should use EDB.

Comparing CEDB and EDB

EDB and CEDB both create a volume on top of a file. This volume contains one or more databases. While EDB and CEDB share many of the same features and use a similar API for accessing databases, EDB includes support for these major features, unavailable in CEDB:

·         Both explicit and implicit transactions

·         Use of schemas to define the database structure

·         Improved sort order support (16 sort orders supported and sort orders supported on all data types.)

·         Support for stream data types

·         Multi-user access.

 

Conversely, there are a number of CEDB features not supported by EDB:

·         A shared system volume

·         Tracking of the last modified time or the size of a database

·         A default sort order

·         Add and remove columns. (EDB requires all records to have the same properties.)

·         Support for Microsoft eMBedded Visual Basic®. You must use Visual Studio 2005 ® when developing applications that use EDB.

 

EDB is designed as a complete replacement for CEDB. The differences in the functionality and features of EDB and those of CEDB are significant enough that a database created with CEDB is not accessible to EDB; an EDB database is also not accessible to CEDB.

 

In order to simplify application development, the EDB API is very similar to the CEDB API, while extending core functionality to include sessions, transactions, and stream data types. The EDB API is not fully compatible with the CEDB API, and applications written to use CEDB will need to be updated to use EDB.

Comparing EDB with other Databases

 

Porting your Application

First of all, you will need to port your application from eMbedded Visual C++ (eVC) to Visual Studio 2005. The purpose of this whitepaper is not to explain how to convert an eMbedded Visual C++ project to Visual Studio 2005, but you should be able to use the project conversion wizard to do that.  Once you port your application you will need to take the following steps:

 

1. #define EDB

When you build your project you should see the following build error:

 

CEDB is deprecated and will no longer work in future versions of Windows Mobile.  It is strongly recommended that you #define EDB which will enable you to use EDB instead.

 

This error occurs because you included winDbase.h and did not define EDB, so you will need to #define EDB before your #include <windbase.h>.

 

Try to rebuild your application. Your application may build with no errors after defining EDB, but this does not mean that your application will actually work properly!

 

2. Pass EDB_MOUNT_FLAG to CeMountDBVol

We will need to modify your call to CeMountDBVolume so that it mounts an EDB volume. Your CEDB call to CeMountDBVolume probably looks something like this:

CeMountDBVol( &m_VolGUID, pszDBVolName, CREATE_ALWAYS));

To work with EDB, modify it by passing the EDB_MOUNT_FLAG to the third parameter (dwFlags) as shown below.

CeMountDBVol( &m_VolGUID, pszDBVolName,

  CREATE_ALWAYS | EDB_MOUNT_FLAG);

An even better change would be to call the recommended API CeMountDBVolEx as shown below.

CeMountDBVolEx( &m_VolGUID, pszDBVolName,

                NULL,

    CREATE_ALWAYS);

 

The second parameter takes a pointer CEVOLUMEOPTIONS structure (pOptions), if this is NULL, the default options are used. If it is not, keep in mind that pOptions->wVersion should be set to CEVOLUMEOPTIONS_VERSION.

 

3. Use the Recommended APIs

In some cases, just like in the case of CeMountDBVolEx, the original API (in this case CeMountDBVol) may be used, but applications should use a recommended API.

 

Here is a table that shows the recommended EDB functions to be used.

 

Function

Recommended Function

CeMountDBVol

CeMountDBVolEx

CeCreateDatabaseEx2

CeCreateDatabaseWithProps

CeReadRecordProps

CeReadRecordPropsEx

CeSeekDatabase

CeSeekDatabaseEx

CeOidGetInfoEx

CeOidGetInfoEx2

CeOpenDatabaseEx

CeOpenDatabaseEx2

CeOpenDatabaseInSession

 

4. Read the description of the EDB API on msdn

The names of the APIs used for EDB are usually similar to those used for CEDB, but you need to make sure the arguments you pass to them are correct. Let’s take CeOidGetInfoEx2 as an example.  Looking at the documentation for both EDB and CEDB we notice that the signature of this API is the same in both cases:

BOOL CeOidGetInfoEx2( 

  PCEGUID pGuid, 

  CEOID oid,

  CEOIDINFO* poidInfo

);

Notice that the use is slightly different though. On the EDB version,
poidInfo->wVersion should be set to CEOIDINFOEX_VERSION. This is not obvious unless you carefully read the description of the parameters and for the EDB version.

 

More information on EDB and CEDB can be found on msdn:

CEDB Reference

EDB Reference

 

Sample Code

The Visual Studio 2005 attached project (FileDB) shows how an application that used CEDB has been ported to use EDB. Using #ifdef EDB both the CEDB and EDB versions are shown in the sample. If you would like to build for CEDB just remove the #define EDB at the top of the FileDB.cpp file.

This sample is very simple; it creates a database with 3 rows and populates it with the names, size and time of the files in a directory. The database is then closed and opened sorted by date, time and size respectively. The results are shown in Visual Studio 2005 debug output window.

 

 

 

 

Conclusion

As you port your application from CEDB to EDB you will benefit from its improvements - multi-user access, better overall performance and order support, among others. Porting your application should be relatively simple, but just getting it to compile under EDB is not enough, you need to refer to the EDB documentation or to this whitepaper to understand some of the changes that are required when calling the EDB APIs.