Database Volumes

< BACK  NEXT >

[oR]

Database volumes allow property databases to be created outside the Object Store on devices such as storage cards. A property database is an integrated part of the object store each record has its own OID. To replicate this behavior in other storage devices, a file (a "database volume") needs to be created, and one or more property databases will be created in that file. Database volumes usually have a CDB extension.

Since database volumes are simply files, the user cannot use Explorer to view the databases in the volume. CDB files are not necessarily hidden and can be deleted by a user. Microsoft Pocket Access can be used to open a CDB file and view the contents.

Database volumes need to be "mounted" before the databases in the volume can be accessed. Finally, when all the databases are closed, the database volume should be unmounted.

Creating and Mounting Database Volumes

The function CEMountDBVol is used both to create new volumes and to open existing volumes. Listing 4.1 shows how to create a new database volume and mount the volume on a storage device called "Storage Card."

Listing 4.1 Creates a database volume

 void Listing4_1() {   CEGUID pceguid;   if(!CeMountDBVol(&pceguid,           _T("\\Storage Card\\MyVolume.CDB"),           CREATE_NEW))     cout   _T("Could not create database volume")            endl;   else     cout   _T("Database volume created")   endl;  } 

Table 4.1. CEMountDBVol Creates and/or opens a database volume

CEMountDBVol
PCEGUID pceguid	Pointer to a CEGUID that uniquely identifies the open database volume
LPWSTR lpszDBVol	String containing the path and CDB filename for the database volume
DWORD dwFlags	Flags specifying how the volume will be created/opened
BOOL Return Value	Returns TRUE on success

The first argument, pceguid, is used to return a CEGUID value that is used to reference the newly created and mounted database volume. The CEGUID data type is a structure that contains four DWORD values, and although superficially similar to the GUID (Globally Unique Identifier) used in COM and ActiveX (see Chapter 14), its use is restricted to Windows CE databases.

The constant values and semantics for dwFlags are the same as the dwCreationDisposition parameter used when opening and creating files using CreateFile (see Chapter 2). You need to take care when using CREATE_ ALWAYS and TRUNCATE_EXISTING since all databases in an existing volume can be deleted.

• CREATE_NEW Create a new volume, fail if the volume already exists.

• CREATE_ALWAYS Create a new volume, overwriting the volume if it already exists.

• OPEN_EXISTING Open an existing volume, and fail if the volume does not exist.

• OPEN_ALWAYS Open an existing volume, and if it does not exist, create the volume.

• TRUNCATE_EXISTING Open an existing volume and empty the contents. Fail if the volume does not exist.

You can call GetLastError to determine the error code if the call to CEMountDBVol fails. If the function fails, pceguid will contain an invalid value. This can be tested using the CHECK_INVALIDGUID macro, which takes a pointer to the CEGUID.

 if (CHECK_INVALIDGUID(&pceguid))     cout   _T("Invalid CEGUID"); else     cout   _T("Valid CEGUID"); 

Mounting an existing volume simply requires changing the dwFlags value:

 CeMountDBVol(&pceguid,     _T("\\Storage Card\\MyVolume.CDB"),     OPEN_EXISTING); 

Unmounting a Volume

You will need to unmount the database volume by calling CeUnmountDBVol once you have finished accessing databases in the volume.

 if(!CeUnmountDBVol(&peceguid))   cout   _T("Volume unmounted"); else   cout   _T("Volume could not be unmounted"); 

Table 4.2. CeUnmountDBVol Unmounts a mounted database

CeUnmountDBVol
PCEGUID pceguid	Pointer to the CEGUID for an open database volume
BOOL Return Value	Returns TRUE if database volume is unmounted

A reference count is maintained for each volume, and this is incremented whenever an application mounts the volume. The volume is only unmounted when the reference count returns to zero, which happens when the last application unmounts the volume.

< BACK  NEXT >