Documentation  |   Table of Contents   |  < Previous   |  Next >  

26    DataMgr.h

Porting Applications to Palm OS® Cobalt

Exploring Palm OS®

The card number parameter has been removed from a number of functions.

A number of functions have been renamed to better reflect their operation.

Databases are no longer uniquely identified solely by name, so DmFindDatabase() now takes a creator ID in addition to the database name. This function also has a new parameter that allows you to specify which of Schema, Extended, or Classic databases should be searched for, and it now optionally returns information about the found database.

DmGetNextDatabaseByTypeCreator() must now be used in conjunction with the new DmOpenIteratorByTypeCreator() function; you indicate what you are searching for when calling that function. DmGetNextDatabaseByTypeCreator() now optionally returns information about the found database in addition to its database ID.

Palm OS Cobalt doesn't support resource chains (except for backwards compatibility purposes). Consequently, you now have to identify the resource database to be searched when using DmGetResource().


NOTE: Early in the porting process you may want to #include DataMgrCompatibility.h (after the #include for PalmOS.h). This header file defines a number of APIs and macros that allow applications calling certain deleted functions and functions with modified prototypes to compile and run. This compatibility header should not be counted on long-term, however, so later in the porting process you should remove the #include and fix any problems that result.

Deleted APIs ^TOP^

Table 26.1  Deleted functions

Deleted API

Use instead

DmDatabaseProtect()

DmSetDatabaseProtection()

DmFindSortPositionV10()

DmGetRecordSortPosition()

DmGet1Resource()

DmGetResource() or DmGetResourceByIndex()

DmGetAppInfoID()

DmGetAppInfo()

DmInit()

Nothing. This function was documented as "System Use Only" and should not have been used by applications.

DmOpenDatabaseInfo()

DmGetOpenInfo()

DmRecordInfo()

DmGetRecordAttr(), DmGetRecordCategory(), DmGetRecordID(), or DmQueryNextInCategory()

DmSetRecordInfo()

DmSetRecordAttr() and/or DmSetRecordID()

DmWriteCheck()

DmWrite()

Modified APIs ^TOP^

Table 26.2  Modified functions 

Modified API

Description of change

status_t DmCreateDatabase (const char *, uint32_t, uint32_t, Boolean)

The card number parameter has been removed.

status_t DmCreateDatabaseFromImage (MemPtr, DatabaseID *)

Now has an additional parameter through which the caller can obtain the name of the newly-created database.

status_t DmDatabaseInfo (DatabaseID, DmDatabaseInfoPtr)

The card number parameter has been removed, and all returned information is returned using a single DmDatabaseInfoType structure rather than through a large number of individual parameters.

status_t DmDatabaseSize (DatabaseID, uint32_t *, uint32_t *, uint32_t *)

The card number parameter has been removed.

status_t DmDeleteDatabase (DatabaseID)

The card number parameter has been removed.

DatabaseID DmFindDatabase (const char *, uint32_t, DmFindType, DmDatabaseInfoPtr)

Now takes a creator ID in addition to the database name to reflect the fact that databases are no longer uniquely identified solely by name. The card number parameter has been removed. A parameter has been added that allows you to specify which of Schema, Extended, or Classic databases should be searched for. This function now optionally returns information about the found database.

DatabaseID DmGetDatabase (uint16_t)

The card number parameter has been removed.

status_t DmGetDatabaseLockState (DmOpenRef, uint8_t *, uint32_t *, uint32_t *)

Now returns an error code if the lock state couldn't be obtained.

status_t DmGetNextDatabaseByTypeCreator (DmSearchStatePtr, DatabaseID *, DmDatabaseInfoPtr)

This function must now be used in conjunction with the new DmOpenIteratorByTypeCreator() function; you indicate what you are searching for when calling that function. This function now optionally returns information about the found database in addition to its database ID.

MemHandle DmGetResource (DmOpenRef, DmResourceType, DmResourceID)

Palm OS Cobalt doesn't support resource chains (except for backwards compatibility purposes). Consequently, you now have to identify the resource database to be searched.

uint16_t DmNumDatabases (void)

The card number parameter has been removed.

DmOpenRef DmOpenDatabase (DatabaseID, uint16_t)

The card number parameter has been removed.

DmOpenRef DmOpenDBNoOverlay (DatabaseID, uint16_t)

The card number parameter has been removed.

status_t DmSetDatabaseInfo (DatabaseID, DmDatabaseInfoPtr)

The card number parameter has been removed, and all database information is specified using a single DmDatabaseInfoType structure rather than through a large number of individual parameters.

Table 26.3  Modified #defines 

Modified API

Description of change

#define dmAllHdrAttrs ( dmHdrAttrResDB | dmHdrAttrReadOnly | dmHdrAttrAppInfoDirty | dmHdrAttrBackup | dmHdrAttrOKToInstallNewer | dmHdrAttrResetAfterInstall | dmHdrAttrCopyPrevention | dmHdrAttrStream | dmHdrAttrHidden | dmHdrAttrLaunchableData | dmHdrAttrRecyclable | dmHdrAttrBundle | dmHdrAttrSchema | dmHdrAttrSecure | dmHdrAttrOpen )

Added the dmHdrAttrSchema and dmHdrAttrSecure bits.

#define dmMaxRecordIndex ( (uint16_t) 0xFFFE )

Formerly was 0xffff.

#define dmSysOnlyHdrAttrs ( dmHdrAttrResDB | dmHdrAttrSchema | dmHdrAttrSecure | dmHdrAttrOpen )

Added the dmHdrAttrSchema and dmHdrAttrSecure bits.

Renamed APIs ^TOP^

Table 26.4  Renamed functions 

Old name

New name

DmFindSortPosition()

DmGetRecordSortPosition()

DmGetResourceIndex()

DmGetResourceByIndex()

DmPositionInCategory()

DmGetPositionInCategory()

DmSearchRecord()

DmSearchRecordOpenDatabases()

DmSearchResource()

DmSearchResourceOpenDatabases()

DmSeekRecordInCategory()

DmFindRecordByOffsetInCategory()

Table 26.5  Renamed structures

Old name

New name

SortRecordInfoType

DmSortRecordInfoType

Table 26.6  Renamed types

Old name

New name

DmResID

DmResourceID

DmResType

DmResourceType

SortRecordInfoPtr

DmSortRecordInfoPtr

Table 26.7  Renamed application-defined functions

Old name

New name

DmComparF()

DmCompareFunctionType()

Unchanged APIs ^TOP^

Table 26.8  Unchanged functions 

DmArchiveRecord()

DmAttachRecord()

DmAttachResource()

DmCloseDatabase()

DmDeleteCategory()

DmDeleteRecord()

DmDetachRecord()

DmDetachResource()

DmFindRecordByID()

DmFindResource()

DmFindResourceType()

DmGetLastErr()

DmGetRecord()

DmInsertionSort()

DmMoveCategory()

DmMoveRecord()

DmNewHandle()

DmNewRecord()

DmNewResource()

DmNextOpenDatabase()

DmNextOpenResDatabase()

DmNumRecords()

DmNumRecordsInCategory()

DmNumResources()

DmOpenDatabaseByTypeCreator()

DmQueryNextInCategory()

DmQueryRecord()

DmQuickSort()

DmReleaseRecord()

DmReleaseResource()

DmRemoveRecord()

DmRemoveResource()

DmRemoveSecretRecords()

DmResetRecordStates()

DmResizeRecord()

DmResizeResource()

DmResourceInfo()

DmSet()

DmSetResourceInfo()

DmStrCopy()

DmWrite()

Table 26.9  Unchanged structures

DmSearchStateType

Table 26.10  Unchanged types

DmOpenRef

DmSearchStatePtr

Table 26.11  Unchanged #defines 

dmAllCategories

dmAllRecAttrs

dmCategoryLength

dmDBNameLength

dmDefaultRecordsID

dmErr...

dmHdrAttrAppInfoDirty

dmHdrAttrBackup

dmHdrAttrBundle

dmHdrAttrCopyPrevention

dmHdrAttrHidden

dmHdrAttrLaunchableData

dmHdrAttrOKToInstallNewer

dmHdrAttrOpen

dmHdrAttrReadOnly

dmHdrAttrRecyclable

dmHdrAttrResDB

dmHdrAttrResetAfterInstall

dmHdrAttrStream

dmModeExclusive

dmModeLeaveOpen

dmModeReadOnly

dmModeReadWrite

dmModeShowSecret

dmModeWrite

dmRecAttrBusy

dmRecAttrCategoryMask

dmRecAttrDelete

dmRecAttrDirty

dmRecAttrSecret

dmRecNumCategories

dmRecordIDReservedRange

dmSeekBackward

dmSeekForward

dmSysOnlyRecAttrs

dmUnfiledCategory

dmUnusedRecordID