Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

30    Data and Resource Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

Part II: System Management

30 Data and Resource Manager

Data Manager Data Structures

DmOpenRef

DmResID

DmResType

SortRecordInfoType

Data Manager Constants

Category Constants

Record Attribute Constants

Database Attribute Constants

Error Codes

Open Mode Constants

Miscellaneous Constants

Data Manager Functions

DmArchiveRecord

DmAttachRecord

DmAttachResource

DmCloseDatabase

DmCreateDatabase

DmCreateDatabaseFromImage

DmDatabaseInfo

DmDatabaseProtect

DmDatabaseSize

DmDeleteCategory

DmDeleteDatabase

DmDeleteRecord

DmDetachRecord

DmDetachResource

DmFindDatabase

DmFindRecordByID

DmFindResource

DmFindResourceType

DmFindSortPosition

DmFindSortPositionV10

DmGetAppInfoID

DmGetDatabase

DmGetDatabaseLockState

DmGetLastErr

DmGetNextDatabaseByTypeCreator

DmGetRecord

DmGetResource

DmGetResourceIndex

DmGet1Resource

DmInsertionSort

DmMoveCategory

DmMoveRecord

DmNewHandle

DmNewRecord

DmNewResource

DmNextOpenDatabase

DmNextOpenResDatabase

DmNumDatabases

DmNumRecords

DmNumRecordsInCategory

DmNumResources

DmOpenDatabase

DmOpenDatabaseByTypeCreator

DmOpenDatabaseInfo

DmOpenDBNoOverlay

DmPositionInCategory

DmQueryNextInCategory

DmQueryRecord

DmQuickSort

DmRecordInfo

DmReleaseRecord

DmReleaseResource

DmRemoveRecord

DmRemoveResource

DmRemoveSecretRecords

DmResizeRecord

DmResizeResource

DmResourceInfo

DmSearchRecord

DmSearchResource

DmSeekRecordInCategory

DmSet

DmSetDatabaseInfo

DmSetRecordInfo

DmSetResourceInfo

DmStrCopy

DmSync

DmSyncDatabase

DmWrite

DmWriteCheck

Application-Defined Functions

DmComparF

     

This chapter describes the data manager and the resource manager API declared in the header file DataMgr.h. It discusses the following topics:

For more information on the data and resource managers, see the chapter "Files and Databases" in the Palm OS Programmer's Companion, vol. I.

Data Manager Data Structures ^TOP^

DmOpenRef Typedef ^TOP^

Purpose

The DmOpenRef type defines a pointer to an open database. The database pointer is created and returned by DmOpenDatabase(). It is used in any function that requires access to an open database.

Prototype

typedef void *DmOpenRef;

DmResID Typedef ^TOP^

Purpose

The DmResID type defines a resource identifier. You assign each resource an ID at creation time. Note that resource IDs greater than or equal to 10000 are reserved for system use.

Prototype

typedef UInt16 DmResID;

DmResType Typedef ^TOP^

Purpose

The DmResType type defines the type of a resource. The resource type is a four-character code such as 'Tbmp' for bitmap resources.

Prototype

typedef UInt32 DmResType;

SortRecordInfoType Struct ^TOP^

Purpose

The SortRecordInfoType structure specifies information that can be used to sort a record. The database sorting functions (DmInsertionSort() and DmQuickSort()) pass this structure to your comparison callback function (of type DmComparF()), where you can use the information therein to help when comparing two records. To create this structure, you can call DmRecordInfo(), which returns these values for a given record.

Prototype

typedef struct {
UInt8 attributes;
UInt8 uniqueID[3];
} SortRecordInfoType;
typedef SortRecordInfoType *SortRecordInfoPtr;

Fields

attributes
The record's attributes. See "Record Attribute Constants."
uniqueID
The unique identifier for the record.

Data Manager Constants ^TOP^

Category Constants ^TOP^

The following constants are used to specify information about categories:

Constant

Value

Description

dmAllCategories

0xFF

A mask used to represent all categories.

dmCategoryLength

16

The length of a category name. Currently, this is 16 bytes, which includes the null terminator.

dmRecAttrCategoryMask

0x0F

A mask used to retrieve the category information from the record's attributes field.

dmRecNumCategories

16

The number of categories allowed. Currently, this is 16, which includes the "Unfiled" category.

dmUnfiledCategory

0

A mask used to indicate the Unfiled category.

Record Attribute Constants ^TOP^

The following constants specify a database record's attributes.

Constant

Value

Description

dmMaxRecordIndex

0xFFFF

Indicates the highest record index allowed.

dmAllRecAttrs

0xF0

A mask used to specify all record attributes.

dmRecAttrBusy

0x20

Busy (the application has locked access to this record). A call to DmGetRecord() fails on a record that has this bit set, otherwise it sets this bit. Call DmReleaseRecord() to release the record and clear this bit. The DmSetRecordInfo() function cannot be used to alter the state of dmRecAttrBusy.

dmRecAttrDelete

0x80

Deleted

dmRecAttrDirty

0x40

Dirty (has been modified since last sync)

dmRecAttrSecret

0x10

Private

dmSysOnlyRecAttrs

0x20

A mask used to specify record attributes that only the system can change. (In other words, the busy attribute.)

Database Attribute Constants ^TOP^

The following constants define a database's attributes:

Constant

Description

dmAllHdrAttrs

A mask used to specify all header attributes.

dmHdrAttrAppInfoDirty

The application info block is dirty (has been modified since the last sync).

dmHdrAttrBackup

The database should be backed up to the desktop computer if no application-specific conduit is available.

dmHdrAttrBundle

The database is bundled with its application during a beam. That is, if the user chooses to beam the application from the Launcher, the Launcher beams this database along with the application's resource database and overlay database.

This attribute applies to Palm OS® 4.0 and higher. Note that overlay databases are automatically beamed with the application database on Palm OS 4.0 and higher. You do not need to set this bit in overlay databases.

dmHdrAttrCopyPrevention

Prevents the database from being copied by methods such as IR beaming.

dmHdrAttrHidden

This database should be hidden from view. For example, this attribute is set to hide some applications in the launcher's main view. You can set it on record databases to have the launcher disregard the database's records when showing a count of records.

This attribute applies to Palm OS version 3.2 and higher.

dmHdrAttrLaunchableData

This database is a data database but it can be "launched" from the launcher. For example, this attribute is set in Palm Query Applications (PQAs) launched by the Web Clipping Application Viewer application.

dmHdrAttrOpen

The database is open.

dmHdrAttrOKToInstallNewer

The backup conduit can install a newer version of this database with a different name if the current database is open. This mechanism is used to update the Graffiti® and Graffiti 2 Shortcuts databases, for example.

dmHdrAttrReadOnly

The database is a read-only database.

dmHdrAttrRecyclable

The database is recyclable. Recyclable databases are deleted when they are closed or upon a system reset.

This attribute applies to Palm OS 4.0 and higher.

dmHdrAttrResDB

The database is a resource database.

dmHdrAttrResetAfterInstall

The device must be reset after this database is installed. That is, the HotSync® application forces a reset after installing this database.

dmHdrAttrStream

The database is a file stream.

dmSysOnlyHdrAttrs

A mask specifying the attributes that only the system can change (open and resource database).

Error Codes ^TOP^

The following constants define error codes that are returned by the data manager and resource manager functions. Several functions return a failure value such as NULL or 0 instead of an error code. In many cases, you can call DmGetLastErr() upon receiving this value and receive a more descriptive error code.

Also, note that on releases prior to Palm OS release 3.5, many data manager functions display a fatal error message using the ErrFatalDisplayIf() macro if certain error conditions are true. Because the Palm OS ROMs are usually shipped with error checking set to partial, you receive the fatal error message. If a ROM is built with error checking set to none, the function returns one of the error codes listed here. (Note that Palm has never released a ROM with error checking set to none and has no plans to do so.)

Constant

Description

dmErrAlreadyExists

Another database with the same name already exists in RAM store.

dmErrAlreadyOpenForWrites

The database is already open with write access.

dmErrCantFind

The specified resource can't be found.

dmErrCantOpen

The database cannot be opened.

dmErrCorruptDatabase

The database is corrupted.

dmErrDatabaseOpen

The function cannot be performed on an open database, and the database is open.

dmErrDatabaseNotProtected

DmDatabaseProtect() failed to protect the specified database.

dmErrDatabaseProtected

The database is marked as protected.

dmErrIndexOutOfRange

The specified index is out of range.

dmErrInvalidDatabaseName

The name you've specified for the database is invalid.

dmErrInvalidParam

The function received an invalid parameter.

dmErrMemError

A memory error occurred.

dmErrNoOpenDatabase

The function is to search all open databases, but there are none.

dmErrNotRecordDB

You've attempted to perform a record function on a resource database.

dmErrNotResourceDB

You've attempted to perform a resource manager function on a record database.

dmErrNotValidRecord

The record handle is invalid.

dmErrOpenedByAnotherTask

You've attempted to open a database that another task already has open.

dmErrReadOnly

You've attempted to write to or modify a database that is in read-only mode.

dmErrRecordArchived

The function requires that the record not be archived, but it is.

dmErrRecordBusy

The function requires that the record not be busy, but it is.

dmErrRecordDeleted

The record has been deleted.

dmErrRecordInWrongCard

You've attempted to attach a record to a database when the record and database reside on different memory cards.

dmErrResourceNotFound

The resource can't be found.

dmErrROMBased

You've attempted to delete or modify a ROM-based database.

dmErrSeekFailed

The operation of seeking the next record in the category failed.

dmErrUniqueIDNotFound

A record with the specified unique ID can't be found.

dmErrWriteOutOfBounds

A write operation exceeded the bounds of the record.

memErrCardNotPresent

The specified card can't be found.

memErrChunkLocked

The associated memory chunk is locked.

memErrInvalidParam

memErrNotEnoughSpace

A memory error occurred.

memErrInvalidStoreHeader

memErrRAMOnlyCard

The specified card has no storage RAM.

omErrBaseRequiresOverlay

An attempt was made to open a stripped resource database, but no associated overlay could be found.

omErrUnknownLocale

An attempt was made to open a resource database with overlays using an unknown locale.

Open Mode Constants ^TOP^

The following constants define the mode in which a database can be opened. You pass one or more of these as a parameter to DmOpenDatabase(), DmOpenDatabaseByTypeCreator(), or DmOpenDBNoOverlay():

Constant

Description

dmModeReadWrite

Read-write access.

dmModeReadOnly

Read-only access.

dmModeWrite

Write-only access.

dmModeLeaveOpen

Leave database open even after application quits.

dmModeExclusive

Don't let anyone else open this database.

dmModeShowSecret

Show records marked private.

Miscellaneous Constants ^TOP^

The following additional constants are used in conjunction with the Data Manager.

Constant

Value

Description

dmDBNameLength

32

Maximum length of a database name, including the null terminator. Database names must use only 7-bit ASCII characters (0x20 through 0x7E).

Data Manager Functions ^TOP^

DmArchiveRecord Function ^TOP^

Purpose

Mark a record as archived by leaving the record's chunk intact and setting the delete bit for the next sync.

Declared In

DataMgr.h

Prototype

Err DmArchiveRecord (
   DmOpenRefdbP,
   UInt16index
)

Parameters

dbP
DmOpenRef to open database.
index
Which record to archive.

Returns

Returns errNone if no error, or one of the following if an error occurs:

Some releases may display a fatal error message instead of returning the error code.

Comments

When a record is archived, the deleted bit is set but the chunk is not freed and the local ID is preserved. This way, the next time the user synchronizes with the desktop system, the desktop can save the record data on the PC before it permanently removes the record entry and data from the Palm Powered device.

Based on the assumption that a call to DmArchiveRecord indicates that you are finished with the record and aren't going to refer to it again, this function sets the chunk's lock count to zero.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmRemoveRecord(), DmDetachRecord(), DmNewRecord(), DmDeleteRecord()

DmAttachRecord Function ^TOP^

Purpose

Attach an existing chunk ID handle to a database as a record.

Declared In

DataMgr.h

Prototype

Err DmAttachRecord (
   DmOpenRefdbP,
   UInt16*atP,
   MemHandlenewH,
   MemHandle*oldHP
)

Parameters

dbP
DmOpenRef to open database.
atP
Pointer to the index where the new record should be placed. Specify the value dmMaxRecordIndex to add the record to the end of the database.
newH
Handle of the new record.
oldHP
If non-NULL upon entry, indicates that the record at *atP should be replaced. Upon return, contains the handle to the replaced record.

Returns

Returns errNone if no error, or one of the following if an error occurs:

Some releases may display a fatal error message instead of returning some of these error codes.

Comments

Given the handle of an existing chunk, this routine makes that chunk a new record in a database and sets the dirty bit. The parameter atP points to an index variable. If oldHP is NULL, the new record is inserted at index *atP and all record indices that follow are shifted down. If *atP is greater than the number of records currently in the database, the new record is appended to the end and its index is returned in *atP. If oldHP is not NULL, the new record replaces an existing record at index *atP and the handle of the old record is returned in *oldHP so that the application can free it or attach it to another database.

This function is useful for cutting and pasting between databases.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmDetachRecord(), DmNewRecord(), DmNewHandle(), DmFindSortPosition()

DmAttachResource Function ^TOP^

Purpose

Attach an existing chunk ID to a resource database as a new resource.

Declared In

DataMgr.h

Prototype

Err DmAttachResource (
   DmOpenRefdbP,
   MemHandlenewH,
   DmResTyperesType,
   DmResIDresID
)

Parameters

dbP
DmOpenRef to open database.
newH
Handle of new resource's data.
resType
Type of the new resource.
resID
ID of the new resource.

Returns

Returns errNone if no error, or one of the following if an error occurs:

Some releases may display a fatal error message instead of returning some of these error codes. All releases may display a fatal error message if the database is not a resource database.

Comments

Given the handle of an existing chunk with resource data in it, this routine makes that chunk a new resource in a resource database. The new resource will have the given type and ID.

See Also

DmDetachResource(), DmRemoveResource(), DmNewHandle(), DmNewResource()

DmCloseDatabase Function ^TOP^

Purpose

Close a database.

Declared In

DataMgr.h

Prototype

Err DmCloseDatabase (
   DmOpenRefdbP
)

Parameters

dbP
Database access pointer.

Returns

Returns errNone if no error, or dmErrInvalidParam if an error occurs. Some releases may display a fatal error message instead of returning the error code.

Comments

This routine doesn't unlock any records that were left locked. Records and resources should not be left locked. If a record/resource is left locked, you should not use its reference because the record can disappear during a HotSync operation or if the database is deleted by the user. To prevent the database from being deleted, you can use DmDatabaseProtect() before closing.

If there is an overlay associated with the database passed in, DmCloseDatabase closes the overlay as well.

If the database has the recyclable bit set (dmHdrAttrRecyclable), DmCloseDatabase calls DmDeleteDatabase() to delete it.

Compatibility

Starting with Palm OS 2.0, DmCloseDatabase updates the database's modification date.

  • On Palm OS 2.0, the modification date is updated if the database was opened with write access.
  • On Palm OS 3.0 and higher, the modification date is updated only if a change has been made and the database was opened with write access. Changes that trigger an update include adding, deleting, archiving, rearranging, or resizing records, setting a record's dirty bit in DmReleaseRecord(), rearranging or deleting categories, or updating the database header fields using DmSetDatabaseInfo().

Under Palm OS 1.0, the modification date was never updated.

If you need to ensure that the modification date is updated the same way regardless of the operating system version, use DmSetDatabaseInfo() to set the modification date explicitly.

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmOpenDatabase(), DmDeleteDatabase(), DmOpenDatabaseByTypeCreator()

DmCreateDatabase Function ^TOP^

Purpose

Create a new database on the specified card with the given name, creator, and type.

Declared In

DataMgr.h

Prototype

Err DmCreateDatabase (
   UInt16cardNo,
   constChar*nameP,
   UInt32creator,
   UInt32type,
   BooleanresDB
)

Parameters

cardNo
The card number to create the database on.
nameP
Name of new database, up to 32 ASCII bytes long, including the null terminator (as specified by dmDBNameLength). Database names must use only 7-bit ASCII characters (0x20 through 0x7E).
creator
Creator of the database.
type
Type of the database.
resDB
If true, create a resource database.

Returns

Returns errNone if no error, or one of the following if an error occurs:

May display a fatal error message if the master database list cannot be found.

Comments

Call this routine to create a new database on a specific card. If another database with the same name already exists in RAM store, this routine returns a dmErrAlreadyExists error code. Once created, the database ID can be retrieved by calling DmFindDatabase(). The database can be opened using the database ID. To create a resource database instead of a record-based database, set the resDB Boolean to true.

After you create a database, it's recommended that you call DmSetDatabaseInfo() to set the version number. Databases default to version 0 if the version isn't explicitly set.

See Also

DmCreateDatabaseFromImage(), DmOpenDatabase(), DmDeleteDatabase()

DmCreateDatabaseFromImage Function ^TOP^

Purpose

Create an entire database from a single resource that contains an image of the database.

Declared In

DataMgr.h

Prototype

Err DmCreateDatabaseFromImage (
   MemPtrbufferP
)

Parameters

bufferP
Pointer to locked resource containing database image.

Returns

Returns errNone if no error.

Comments

An image is the same as a desktop file representation of a prc or pdb file.

This function is intended for applications in the ROM to install default databases after a hard reset. RAM-based applications that want to install a default database should install a pdb file separately to save storage heap space.

See Also

DmCreateDatabase(), DmOpenDatabase()

DmDatabaseInfo Function ^TOP^

Purpose

Retrieve information about a database.

Declared In

DataMgr.h

Prototype

Err DmDatabaseInfo (
   UInt16cardNo,
   LocalIDdbID,
   Char*nameP,
   UInt16*attributesP,
   UInt16*versionP,
   UInt32*crDateP,
   UInt32*modDateP,
   UInt32*bckUpDateP,
   UInt32*modNumP,
   LocalID*appInfoIDP,
   LocalID*sortInfoIDP,
   UInt32*typeP,
   UInt32*creatorP
)

Parameters

cardNo
Number of the card the database resides on.
dbID
Database ID of the database.
nameP
The database's name. Pass a pointer to 32-byte character array for this parameter, or NULL if you don't care about the name.
attributesP
The database's attribute flags. The section "Database Attribute Constants" lists constants you can use to query the values returned in this parameter. Pass NULL for this parameter if you don't want to retrieve it.
versionP
The application-specific version number. The default version number is 0. Pass NULL for this parameter if you don't want to retrieve it.
crDateP
The date the database was created, expressed as the number of seconds since the first instant of Jan. 1, 1904. Pass NULL for this parameter if you don't want to retrieve it.
modDateP
The date the database was last modified, expressed as the number of seconds since the first instant of Jan. 1, 1904. Pass NULL for this parameter if you don't want to retrieve it.
bckUpDateP
The date the database was backed up, expressed as the number of seconds since the first instant of Jan. 1, 1904. Pass NULL for this parameter if you don't want to retrieve it.
modNumP
The modification number, which is incremented every time a record in the database is added, modified, or deleted. Pass NULL for this parameter if you don't want to retrieve it.
appInfoIDP
The local ID of the application info block, or NULL. The application info block is an optional field that the database may use to store application-specific information about the database. Pass NULL for this parameter if you don't want to retrieve it.
sortInfoIDP
The local ID of the database's sort table. This is an optional field in the database header. Pass NULL for this parameter if you don't want to retrieve it.
typeP
The database's type, specified when it is created. Pass NULL for this parameter if you don't want to retrieve it.
creatorP
The database's creator, specified when it is created. Pass NULL for this parameter if you don't want to retrieve it.

Returns

Returns errNone if no error, or dmErrInvalidParam if an error occurs.

Compatibility

Updating of the modification date differs based on which version of the OS your application is running on.

  • Under Palm OS 1.0, the modification date is never updated.
  • Under Palm OS 2.0, the modification date is updated every time a database opened with write access is closed.
  • Beginning with Palm OS 3.0, the modification date is updated only if a change has been made to the database opened with write access. (The update still occurs upon closing the database.) Changes that trigger an update include adding, deleting, archiving, rearranging, or resizing records, setting a record's dirty bit in DmReleaseRecord(), rearranging or deleting categories, or updating the database header fields using DmSetDatabaseInfo().

If you need to ensure that the modification date is updated the same way regardless of the operating system version, use DmSetDatabaseInfo() to set the modification date explicitly.

See Also

DmSetDatabaseInfo(), DmDatabaseSize(), DmOpenDatabaseInfo(), DmFindDatabase(), DmGetNextDatabaseByTypeCreator(), TimSecondsToDateTime()

DmDatabaseProtect Function ^TOP^

Purpose

Increment or decrement the database's protection count.

Declared In

DataMgr.h

Prototype

Err DmDatabaseProtect (
   UInt16cardNo,
   LocalIDdbID,
   Booleanprotect
)

Parameters

cardNo
Card number of database to protect/unprotect.
dbID
Local ID of database to protect/unprotect.
protect
If true, protect count will be incremented. If false, protect count will be decremented.

Returns

Returns errNone if no error, or one of the following if an error occurs:

Comments

This routine can be used to prevent a database from being deleted (by passing true for the protect parameter). It increments the protect count if protect is true and decrements it if protect is false. All true calls should be balanced by false calls before the application terminates.

Use this function if you want to keep a particular record or resource in a database locked down but don't want to keep the database open. This information is kept in the dynamic heap, so all databases are "unprotected" at system reset.

If the database is a resource database that has an overlay associated with it for the current locale, the overlay is also protected or unprotected by this call.

Compatibility

Implemented only if 2.0 New Feature Set is present. Overlay support is only available if 3.5 New Feature Set is present.

DmDatabaseSize Function ^TOP^

Purpose

Retrieve size information on a database.

Declared In

DataMgr.h

Prototype

Err DmDatabaseSize (
   UInt16cardNo,
   LocalIDdbID,
   UInt32*numRecordsP,
   UInt32*totalBytesP,
   UInt32*dataBytesP
)

Parameters

cardNo
Card number the database resides on.
dbID
Database ID of the database.
numRecordsP
The total number of records in the database. Pass NULL for this parameter if you don't want to retrieve it.
totalBytesP
The total number of bytes used by the database including the overhead. Pass NULL for this parameter if you don't want to retrieve it.
dataBytesP
The total number of bytes used to store just each record's data, not including overhead. Pass NULL for this parameter if you don't want to retrieve it.

Returns

Returns errNone if no error, or dmErrMemError if an error occurs.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmDatabaseInfo(), DmOpenDatabaseInfo(), DmFindDatabase(), DmGetNextDatabaseByTypeCreator()

DmDeleteCategory Function ^TOP^

Purpose

Delete all records in a category. The category name is not changed.

Declared In

DataMgr.h

Prototype

Err DmDeleteCategory (
   DmOpenRefdbR,
   UInt16categoryNum
)

Parameters

dbR
Database access pointer.
categoryNum
Category of records to delete. Category masks such as dmAllCategories are invalid.

Returns

Returns errNone if no error, or one of the following if an error occurs:

Some releases may display a fatal error message instead of returning the error code.

Comments

This function deletes all records in a category, but does not delete the category itself (note that it deletes the record data and header info, and doesn't just set the deleted bit). For each record in the category, DmDeleteCategory marks the delete bit in the database header for the record and disposes of the record's data chunk. The record entry in the database header remains, but its localChunkID is set to NULL.

If the category contains no records, this function does nothing and returns errNone to indicate success. The categoryNum parameter is assumed to represent a single category. If you pass a category mask to specify more than one category, this function interprets that value as a single category, finds no records to delete in that category, and returns errNone.

You can use the DmRecordInfo() call to obtain a category index from a given record. For example:


DmOpenRef myDB; 
UInt16 record, attr, category, total; 
 
DmRecordInfo(myDB, record, &attr, NULL, NULL); 
category = attr & dmRecAttrCategoryMask; 
err = DmDeleteCategory(myDB, category); 

Compatibility

Implemented only if 2.0 New Feature Set is present.

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, sysErrNotAllowed is returned. For more information see "Accessing the PIM Application Databases."

DmDeleteDatabase Function ^TOP^

Purpose

Delete a database and all its records.

Declared In

DataMgr.h

Prototype

Err DmDeleteDatabase (
   UInt16cardNo,
   LocalIDdbID
)

Parameters

cardNo
Card number the database resides on.
dbID
Database ID.

Returns

Returns errNone if no error, or one of the following if an error occurs:

Comments

Call this routine to delete a database. This routine deletes the database, the application info block, the sort info block, and any other overhead information that is associated with this database. After deleting the database, this function enqueues a deferred sysNotifyDBDeletedEvent notification, which will be broadcast at the top of the event loop.

If the database has an overlay associated with it, this function does not delete the overlay. You can delete the overlay with a separate call to DmDeleteDatabase.

This routine accepts a database ID as a parameter. To determine the database ID, call either DmFindDatabase() or DmGetDatabase() with a database index.

Compatibility

The sysNotifyDBDeletedEvent notification is only broadcast if the 4.0 New Feature Set is present.

See Also

DmDeleteRecord(), DmRemoveRecord(), DmRemoveResource(), DmCreateDatabase(), DmGetNextDatabaseByTypeCreator(), DmFindDatabase()

DmDeleteRecord Function ^TOP^

Purpose

Delete a record's chunk from a database but leave the record entry in the header and set the delete bit for the next sync.

Declared In

DataMgr.h

Prototype

Err DmDeleteRecord (
   DmOpenRefdbP,
   UInt16index
)

Parameters

dbP
DmOpenRef to open database.
index
Which record to delete.

Returns

Returns errNone if no error, or one of the following if an error occurs:

Some releases may display a fatal error message instead of returning the error code.

Comments

Marks the delete bit in the database header for the record and disposes of the record's data chunk. Does not remove the record entry from the database header, but simply sets the localChunkID of the record entry to NULL.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmDetachRecord(), DmRemoveRecord(), DmArchiveRecord(), DmNewRecord()

DmDetachRecord Function ^TOP^

Purpose

Detach and orphan a record from a database but don't delete the record's chunk.

Declared In

DataMgr.h

Prototype

Err DmDetachRecord (
   DmOpenRefdbP,
   UInt16index,
   MemHandle*oldHP
)

Parameters

dbP
DmOpenRef to open.
index
Index of the record to detach.
oldHP
Pointer to return handle of the detached record.

Returns

Returns errNone if no error, or one of the following if an error occurs:

Some releases may display a fatal error message instead of returning the error code.

Comments

This routine detaches a record from a database by removing its entry from the database header and returns the handle of the record's data chunk in *oldHP. Unlike DmDeleteRecord(), this routine removes its entry in the database header but it does not delete the actual record.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmAttachRecord(), DmRemoveRecord(), DmArchiveRecord(), DmDeleteRecord()

DmDetachResource Function ^TOP^

Purpose

Detach a resource from a database and return the handle of the resource's data.

Declared In

DataMgr.h

Prototype

Err DmDetachResource (
   DmOpenRefdbP,
   UInt16index,
   MemHandle*oldHP
)

Parameters

dbP
DmOpenRef to open database.
index
Index of resource to detach.
oldHP
Pointer to return handle of the detached record.

Returns

Returns errNone if no error, or one of the following if an error occurs:

Some releases may display a fatal error message instead of returning the error code. All releases may display a fatal error message if the database is not a resource database.

Comments

This routine detaches a resource from a database by removing its entry from the database header and returns the handle of the resource's data chunk in *oldHP.

See Also

DmAttachResource(), DmRemoveResource()

DmFindDatabase Function ^TOP^

Purpose

Return the database ID of a database by card number and name.

Declared In

DataMgr.h

Prototype

LocalID DmFindDatabase (
   UInt16cardNo,
   constChar*nameP
)

Parameters

cardNo
Number of card to search.
nameP
Name of the database to look for.

Returns

Returns the database ID. If the database can't be found, this function returns 0, and DmGetLastErr() returns an error code indicating the reason for failure.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmGetNextDatabaseByTypeCreator(), DmDatabaseInfo(), DmOpenDatabase()

DmFindRecordByID Function ^TOP^

Purpose

Return the index of the record with the given unique ID.

Declared In

DataMgr.h

Prototype

Err DmFindRecordByID (
   DmOpenRefdbP,
   UInt32uniqueID,
   UInt16*indexP
)

Parameters

dbP
Database access pointer.
uniqueID
Unique ID to search for.
indexP
Return index.

Returns

Returns 0 if found, otherwise dmErrUniqueIDNotFound. May display a fatal error message if the unique ID is invalid.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmQueryRecord(), DmGetRecord(), DmRecordInfo()

DmFindResource Function ^TOP^

Purpose

Search the given database for a resource by type and ID, or by pointer if it is non-NULL.

Declared In

DataMgr.h

Prototype

UInt16 DmFindResource (
   DmOpenRefdbP,
   DmResTyperesType,
   DmResIDresID,
   MemHandleresH
)

Parameters

dbP
Open resource database access pointer.
resType
Type of resource to search for.
resID
ID of resource to search for.
resH
Pointer to locked resource, or NULL.

Returns

Returns index of resource in resource database, or dmInvalidRecIndex if not found.

May display a fatal error message if the database is not a resource database.

Comments

Use this routine to find a resource in a particular resource database by type and ID or by pointer. It is particularly useful when you want to search only one database for a resource and that database is not the topmost one.


IMPORTANT: This function searches for the resource only in the database you specify. If you pass a pointer to a base resource database, its overlay is not searched. To search both a base database and its overlay for a localized resource, use DmGet1Resource() instead of this function.

If resH is NULL, the resource is searched for by type and ID.

If resH is not NULL, resType and resID are ignored and the index of the given locked resource is returned.

Once the index of a resource is determined, it can be locked down and accessed by calling DmGetResourceIndex().

See Also

DmGetResource(), DmSearchResource(), DmResourceInfo(), DmGetResourceIndex(), DmFindResourceType()

DmFindResourceType Function ^TOP^

Purpose

Search the given database for a resource by type and type index.

Declared In

DataMgr.h

Prototype

UInt16 DmFindResourceType (
   DmOpenRefdbP,
   DmResTyperesType,
   UInt16typeIndex
)

Parameters

dbP
Open resource database access pointer.
resType
Type of resource to search for.
typeIndex
Index of given resource type.

Returns

Index of resource in resource database, or 0xFFFF if not found.

May display a fatal error message if the database is not a resource database.

Comments

Use this routine to retrieve all the resources of a given type in a resource database. By starting at typeIndex 0 and incrementing until an error is returned, the total number of resources of a given type and the index of each of these resources can be determined. Once the index of a resource is determined, it can be locked down and accessed by calling DmGetResourceIndex().


IMPORTANT: This function searches for resources only in the database you specify. If you pass a pointer to a base resource database, its overlay is not searched. To search both a base database and its overlay for a localized resource, use DmGet1Resource() instead of this function.

See Also

DmGetResource(), DmSearchResource(), DmResourceInfo(), DmGetResourceIndex(), DmFindResource()

DmFindSortPosition Function ^TOP^

Purpose

Returns where in a sorted list of records a given record would be located. Useful to find where to insert a record with DmAttachRecord(). Uses a binary search.

Declared In

DataMgr.h

Prototype

UInt16 DmFindSortPosition (
   DmOpenRefdbP,
   void*newRecord,
   SortRecordInfoPtrnewRecordInfo,
   DmComparF*compar,
   Int16other
)

Parameters

dbP
Database access pointer.
newRecord
Pointer to the new record.
newRecordInfo
Sort information about the new record. See SortRecordInfoType.
compar
Pointer to comparison function. See DmComparF().
other
Any value the application wants to pass to the comparison function. This parameter is often used to indicate a sort direction (ascending or descending).

Returns

The position where the record should be inserted.

The position should be viewed as between the record returned and the record before it. Note that the return value may be one greater than the number of records.

Comments

If newRecord has the same key as another record in the database, DmFindSortPosition assumes that newRecord should be inserted after that record. If there are several records with the same key, newRecord is inserted after all of them. For this reason, if you use DmFindSortPosition to search for the location of a record that you know is already in the database, you must subtract 1 from the result. (Be sure to check that the value is not 0.)

If there are deleted records in the database, DmFindSortPosition only works if those records are at the end of the database. DmFindSortPosition always assumes that a deleted record is greater than or equal to any other record.

Compatibility

Implemented only if 2.0 New Feature Set is present.

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmFindSortPositionV10()

DmFindSortPositionV10 Function ^TOP^

Purpose

Return where a record should be. Useful to find where to insert a record with DmAttachRecord(). Uses a binary search.

Declared In

DataMgr.h

Prototype

UInt16 DmFindSortPositionV10 (
   DmOpenRefdbP,
   void*newRecord,
   DmComparF*compar,
   Int16other
)

Parameters

dbP
Database access pointer.
newRecord
Pointer to the new record.
compar
Pointer to comparison function. See DmComparF().
other
Any value the application wants to pass to the comparison function.

Returns

Returns the position where the record should be inserted. The position should be viewed as between the record returned and the record before it. Note that the return value may be one greater than the number of records.

Comments

If there are deleted records in the database, DmFindSortPositionV10 only works if those records are at the end of the database. DmFindSortPositionV10 always assumes that a deleted record is greater than or equal to any other record.

Compatibility

This function corresponds to the 1.0 version of DmFindSortPosition.

See Also

DmFindSortPosition(), DmQuickSort(), DmInsertionSort()

DmGetAppInfoID Function ^TOP^

Purpose

Return the local ID of the application info block.

Declared In

DataMgr.h

Prototype

LocalID DmGetAppInfoID (
   DmOpenRefdbP
).

Parameters

dbP
Database access pointer.

Returns

Returns local ID of the application info block. The application info block is an optional field that the database may use to store application-specific information about the database; if the database doesn't have an application info block, DmGetAppInfoID returns zero.

See Also

DmDatabaseInfo(), DmOpenDatabase()

DmGetDatabase Function ^TOP^

Purpose

Return the database header ID of a database by index and card number.

Declared In

DataMgr.h

Prototype

LocalID DmGetDatabase (
   UInt16cardNo,
   UInt16index
)

Parameters

cardNo
Card number of database.
index
Index of database.

Returns

Returns the database ID, or 0 if an invalid parameter is passed.

Comments

Call this routine to retrieve the database ID of a database by index. The index should range from 0 to DmNumDatabases()-1.

This routine is useful for getting a directory of all databases on a card. The databases returned may reside in either the ROM or the RAM. The order in which databases are returned is not fixed; therefore, you should not rely on receiving a list of databases in a particular order.

See Also

DmOpenDatabase(), DmNumDatabases(), DmDatabaseInfo(), DmDatabaseSize()

DmGetDatabaseLockState Function ^TOP^

Purpose

Return information about the number of locked and busy records in a database.

Declared In

DataMgr.h

Prototype

void DmGetDatabaseLockState (
   DmOpenRefdbR,
   UInt8*highest,
   UInt32*count,
   UInt32*busy
)

Parameters

dbR
Database access pointer.
highest
The highest lock count found for all of the records in the database. If a database has two records, one has a lock count of 2 and one has a lock count of 1, the highest lock count is 2. Pass NULL for this parameter if you don't want to retrieve it.
count
The number of records that have the lock count that is returned in the highest parameter. Pass NULL for this parameter if you don't want to retrieve it.
busy
The number of records that have the busy bit set. Pass NULL for this parameter if you don't want to retrieve it.

Returns

No return value. Returns all information in the parameters you pass.

Comments

This function is intended to be used for debugging purposes. You can use it to obtain information about how many records are busy and how much locking occurs.

Compatibility

Implemented only if 3.2 New Feature Set is present.

DmGetLastErr Function ^TOP^

Purpose

Return error code from last data manager call.

Declared In

DataMgr.h

Prototype

Err DmGetLastErr (
   void
)

Parameters

None.

Returns

Error code from last unsuccessful data manager call.

Comments

Use this routine to determine why a data manager call failed. In particular, calls like DmGetRecord() return 0 if unsuccessful, so calling DmGetLastErr() is the only way to determine why they failed.

Note that DmGetLastErr does not always reflect the error status of the last data manager call. Rather, it reflects the error status of data manager calls that don't return an error code. For some of those calls, the saved error code value is not set to 0 when the call is successful.

For example, if a call to DmOpenDatabaseByTypeCreator() returns NULL for database reference (that is, it fails), DmGetLastErr returns something meaningful; otherwise, it returns the error value of some previous data manager call.

Only the following data manager functions currently affect the value returned by DmGetLastErr:

DmGetNextDatabaseByTypeCreator Function ^TOP^

Purpose

Return a database header ID and card number given the type and/or creator. This routine searches all memory cards for a match.

Declared In

DataMgr.h

Prototype

Err DmGetNextDatabaseByTypeCreator(
   BooleannewSearch,
   DmSearchStatePtrstateInfoP,
   UInt32type,
   UInt32creator,
   BooleanonlyLatestVers,
   UInt16*cardNoP,
   LocalID*dbIDP
)

Parameters

newSearch
true if starting a new search.
stateInfoP
If newSearch is false, this must point to the same data used for the previous invocation.
type
Type of database to search for, pass 0 as a wildcard.
creator
Creator of database to search for, pass 0 as a wildcard.
onlyLatestVers
If true, only the latest version of a database with a given type and creator is returned.
cardNoP
On exit, the card number of the found database.
dbIDP
Database local ID of the found database.

Returns

Returns errNone if no error, or dmErrCantFind if no matches were found.

Comments

You may need to call this function successively to discover all databases having a specified type/creator pair.

To start the search, pass true for newSearch. Allocate a DmSearchStateType structure and pass it as the stateInfoP parameter. DmGetNextDatabaseByTypeCreator stores private information in stateInfoP and uses it if the search is continued.

To continue a search where the previous one left off, pass false for newSearch and pass the same stateInfoP that you used during the previous call to this function.

You can pass 0 as a wildcard operator for the type or creator parameter to conduct searches of wider scope. If the type parameter is 0, this routine can be called successively to return all databases of the given creator. If the creator parameter is 0, this routine can be called successively to return all databases of the given type. You can also pass 0 as the value for both of these parameters to return all available databases without regard to type or creator.

Because databases are scattered freely throughout memory space, they are not returned in any particular order—any database matching the specified type/creator criteria can be returned.Thus, if the value of the onlyLatestVers parameter is false, this function may return a database which is not the most recent version matching the specified type/creator pair. To obtain only the latest version of a database matching the search criteria, set the value of the onlyLatestVers parameter to true.

When determining which is the latest version of the database, RAM databases are considered newer than ROM databases that have the same version number. Because of this, you can replace any ROM-based application with your own version of it. Also, a RAM database on card 1 is considered newer than a RAM database on card 0 if the version numbers are identical.


WARNING! Don't create or delete a database while using DmGetNextDatabaseByTypeCreator to iterate through the existing databases. This could cause databases to be skipped, or it could result in a given database being returned more than once.

Compatibility

In Palm OS version 3.1 and higher, if onlyLatestVers is true, you only receive one matching database for each type/creator pair. In version 3.0 and earlier, you could receive multiple matching databases if onlyLatestVers was true.

Note that the behavior is different only when you have specified a value for both type and creator and onlyLatestVers is true.

For example, suppose your application maintains three databases that all have the same type, creator, and version number and you write this code to process them in some way:


DmSearchStateType state; 
Boolean latestVer; 
UInt16 card; 
LocalID currentDB = 0; 
 
theErr = DmGetNextDatabaseByTypeCreator(true,  
&state, myType, myCreator, latestVer, &card,  
&currentDB); 
while (!theErr && currentDB) { 
/* do something with currentDB */ 
/* now get the next DB */ 
theErr = DmGetNextDatabaseByTypeCreator( 
false, &state, myType, myCreator,  
vlatestVer, &card, &currentDB); 
} 

If latestVer is false, then your code will work the same on all versions of Palm OS and will return all three databases whose type and creator match those specified. If latestVer is true, this code returns all three databases on Palm OS version 3.0 and earlier, but only returns one database on version 3.1 and higher. (Exactly which database it returns is unspecified.)

If you expect multiple databases to match your search criteria, make sure you call DmGetNextDatabaseByTypeCreator in one of the following ways to ensure that your code operates the same on all Palm OS versions:

  • Set onlyLatestVers to false if you specify both a type and creator.
  • Specify 0 for either the type or creator parameter (or both).

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmGetDatabase(), DmFindDatabase(), DmDatabaseInfo(), DmOpenDatabaseByTypeCreator(), DmDatabaseSize()

DmGetRecord Function ^TOP^

Purpose

Return a handle to a record by index and mark the record busy.

Declared In

DataMgr.h

Prototype

MemHandle DmGetRecord (
   DmOpenRefdbP,
   UInt16index
)

Parameters

dbP
DmOpenRef to open database.
index
Which record to retrieve.

Returns

Returns a handle to record data. If another call to DmGetRecord for the same record is attempted before the record is released, NULL is returned and DmGetLastErr() returns an error code indicating the reason for failure.

Comments

Returns a handle to given record and sets the busy bit for the record.

If the record is ROM-based (pointer accessed), this routine makes a fake handle to it and stores this handle in the DmAccessType structure.

DmReleaseRecord() should be called as soon as the caller finishes viewing or editing the record.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmSearchRecord(), DmFindRecordByID(), DmRecordInfo(), DmReleaseRecord(), DmQueryRecord()

DmGetResource Function ^TOP^

Purpose

Search all open resource databases and return a handle to a resource, given the resource type and ID.

Declared In

DataMgr.h

Prototype

MemHandle DmGetResource (
   DmResTypetype,
   DmResIDresID
)

Parameters

type
The resource type.
resID
The resource ID.

Returns

Handle to resource data. If the specified resource cannot be found, this function returns NULL and DmGetLastErr() returns an error code indicating the reason for failure.

Comments

Searches all open resource databases starting with the most recently opened one for a resource of the given type and ID. If found, the resource handle is returned. The application should call DmReleaseResource() as soon as it finishes accessing the resource data. The resource handle is not locked by this function.

This function always returns the resource located in the overlay if any open overlay has a resource matching that type and ID. If there is no overlay version of the resource, this function returns the resource from the base database.

See Also

DmGet1Resource(), DmReleaseResource(), ResLoadConstant()

DmGetResourceIndex Function ^TOP^

Purpose

Return a handle to a resource by index.

Declared In

DataMgr.h

Prototype

MemHandle DmGetResourceIndex (
   DmOpenRefdbP,
   UInt16index
)

Parameters

dbP
Access pointer to open database.
index
Index of the resource whose handle you want.

Returns

Handle to resource data. If the specified index is out of range, this function returns NULL and DmGetLastErr() returns an error code indicating the reason for failure.

May display a fatal error message if the database is not a resource database.


IMPORTANT: This function accesses the resource only in the database you specify. If you pass a pointer to a base resource database, its overlay is not accessed. Therefore, you should use care when using this function to access a potentially localized resource. You can use DmSearchResource() to obtain a pointer to the overlay database if the resource is localized; however, it's more convenient to use DmGetResource() or DmGet1Resource().

See Also

DmFindResource(), DmFindResourceType(), DmSearchResource()

DmGet1Resource Function ^TOP^

Purpose

Search the most recently opened resource database and return a handle to a resource given the resource type and ID.

Declared In

DataMgr.h

Prototype

MemHandle DmGet1Resource (
   DmResTypetype,
   DmResIDresID
)

Parameters

type
The resource type.
resID
The resource ID.

Returns

Handle to resource data. If unsuccessful, this function returns NULL and DmGetLastErr() returns an error code indicating the reason for failure.

Comments

Searches the most recently opened resource database for a resource of the given type and ID. If the database has an overlay associated with it, the overlay is searched first, and then the base database is searched if the overlay does not contain the resource. If found, the resource handle is returned. The application should call DmReleaseResource() as soon as it finishes accessing the resource data. The resource handle is not locked by this function.

See Also

DmGetResource(), DmReleaseResource(), ResLoadConstant()

DmInsertionSort Function ^TOP^

Purpose

Sort records in a database.

Declared In

DataMgr.h

Prototype

Err DmInsertionSort (
   DmOpenRefdbR,
   DmComparF*compar,
   Int16other
)

Parameters

dbR
Database access pointer.
compar
Comparison function. See DmComparF().
other
Any value the application wants to pass to the comparison function. This parameter is often used to indicate a sort direction (ascending or descending).

Returns

Returns errNone if no error, or one of the following if an error occurs:

Some releases may display a fatal error message instead of returning the error code.

Comments

Deleted records are placed last in any order. All others are sorted according to the passed comparison function. Only records which are out of order move. Moved records are moved to the end of the range of equal records. If a large number of records are being sorted, try to use the quick sort.

The following insertion-sort algorithm is used: Starting with the second record, each record is compared to the preceding record. Each record not greater than the last is inserted into sorted position within those already sorted. A binary insertion is performed. A moved record is inserted after any other equal records.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmQuickSort()

DmMoveCategory Function ^TOP^

Purpose

Move all records in a category to another category.

Declared In

DataMgr.h

Prototype

Err DmMoveCategory (
   DmOpenRefdbP,
   UInt16toCategory,
   UInt16fromCategory,
   Booleandirty
)

Parameters

dbP
DmOpenRef to open database.
toCategory
Category to which the records should be added.
fromCategory
Category from which to remove records.
dirty
If true, set the dirty bit.

Returns

Returns 0 if successful, or dmErrReadOnly if the database is in read-only mode. Some releases may display a fatal error message instead of returning the error code.

Comments

If dirty is true, the moved records are marked as dirty.

The toCategory and fromCategory parameters hold category index values. You can learn which category a record is in with the DmRecordInfo() call and use that value in this function. For example, the following code, ensures that the records rec1 and rec2 are in the same category:


DmOpenRef myDB; 
UInt16 rec1, rec2; 
UInt16 rec1Attr, rec2Attr; 
UInt16 category1, category2; 
 
DmRecordInfo (myDB, rec1, &rec1Attr, NULL,  
NULL); 
category1 = rec1Attr & dmRecAttrCategoryMask; 
DmRecordInfo(myDB, rec2, &rec2Attr, NULL,  
NULL); 
category2 = rec2Attr & dmRecAttrCategoryMask; 
if (category1 != category2)  
DmMoveCategory(myDB, category1, category2,  
true); 

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, sysErrNotAllowed is returned. For more information see "Accessing the PIM Application Databases."

DmMoveRecord Function ^TOP^

Purpose

Move a record from one index to another.

Declared In

DataMgr.h

Prototype

Err DmMoveRecord (
   DmOpenRefdbP,
   UInt16from,
   UInt16to
)

Parameters

dbP
DmOpenRef to open database.
from
Index of record to move.
to
Where to move the record.

Returns

Returns errNone if no error, or one of the following if an error occurs:

Some releases may display a fatal error message instead of returning the error code.

Comments

Insert the record at the to index and move other records down. The to position should be viewed as an insertion position. This value may be one greater than the index of the last record in the database. In cases where to is greater than from, the new index of the record becomes to–1 after the move is complete.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

DmNewHandle Function ^TOP^

Purpose

Attempt to allocate a new chunk in the same data heap or card as the database header of the passed database access pointer. If there is not enough space in that data heap, try other heaps.

Declared In

DataMgr.h

Prototype

MemHandle DmNewHandle (
   DmOpenRefdbP,
   UInt32size
) 

Parameters

dbP
DmOpenRef to open database.
size
Size of new handle.

Returns

Returns the chunkID of new chunk. If an error occurs, returns 0, and DmGetLastErr() returns an error code indicating the reason for failure.

Comments

Allocates a new handle of the given size. Ensures that the new handle is in the same memory card as the given database. This guarantees that you can attach the handle to the database as a record to obtain and save its LocalID in the appInfoID or sortInfoID fields of the header.

The handle should be attached to a database as soon as possible. If it is not attached to a database and the application crashes, the memory used by the new handle is unavailable until the next soft reset.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

DmNewRecord Function ^TOP^

Purpose

Return a handle to a new record in the database and mark the record busy.

Declared In

DataMgr.h

Prototype

MemHandle DmNewRecord (
   DmOpenRefdbP,
   UInt16*atP,
   UInt32size
)

Parameters

dbP
DmOpenRef to open database.
atP
Pointer to index where new record should be placed. Specify the value dmMaxRecordIndex to add the record to the end of the database.
size
Size of new record.

Returns

Handle to record data. If an error occurs, this function returns 0 and DmGetLastErr() returns an error code indicating the reason for failure.

Some releases may display a fatal error message if the database is opened in read-only mode or it is a resource database.

Comments

Allocates a new record of the given size, and returns a handle to the record data. The parameter atP points to an index variable. The new record is inserted at index *atP and all record indices that follow are shifted down. If *atP is greater than the number of records currently in the database, the new record is appended to the end and its index is returned in *atP.

Both the busy and dirty bits are set for the new record and a unique ID is automatically created.

DmReleaseRecord() should be called as soon as the caller finishes viewing or editing the record.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmAttachRecord(), DmRemoveRecord(), DmDeleteRecord()

DmNewResource Function ^TOP^

Purpose

Allocate and add a new resource to a resource database.

Declared In

DataMgr.h

Prototype

MemHandle DmNewResource (
   DmOpenRefdbP,
   DmResTyperesType,
   DmResIDresID,
   UInt32size
)

Parameters

dbP
DmOpenRef to open database.
resType
Type of the new resource.
resID
ID of the new resource.
size
Desired size of the new resource.

Returns

Returns a handle to the new resource. If an error occurs, this function returns NULL and DmGetLastErr() returns an error code indicating the reason for failure.

May display a fatal error message if the database is not a resource database.

Comments

Allocates a memory chunk for a new resource and adds it to the given resource database. The new resource has the given type and ID. If successful, the application should call DmReleaseResource() as soon as it finishes initializing the resource.

See Also

DmAttachResource(), DmRemoveResource()

DmNextOpenDatabase Function ^TOP^

Purpose

Return DmOpenRef to next open database for the current task.

Declared In

DataMgr.h

Prototype

DmOpenRef DmNextOpenDatabase (
   DmOpenRefcurrentP
)

Parameters

currentP
Current database access pointer or NULL.

Returns

DmOpenRef to next open database, or NULL if there are no more.

Comments

Call this routine successively to get the DmOpenRefs of all open databases. Pass NULL for currentP to get the first one. Applications don't usually call this function, but is useful for system information.

See Also

DmOpenDatabaseInfo(), DmDatabaseInfo()

DmNextOpenResDatabase Function ^TOP^

Purpose

Return access pointer to next open resource database in the search chain.

Declared In

DataMgr.h

Prototype

DmOpenRef DmNextOpenResDatabase (
   DmOpenRefdbP
) 

Parameters

dbP
Database reference, or 0 to start search from the top.

Returns

Pointer to next open resource database.

Comments

Returns pointer to next open resource database. To get a pointer to the first one in the search chain, pass NULL for dbP. This is the database that is searched when DmGet1Resource() is called.

If you use this function to access a resource database that might have an overlay associated with it, be careful how you use the result. The DmOpenRef returned by this function is a pointer to the overlay database, not the base database. If you subsequently pass this pointer to DmFindResource(), you'll receive a handle to the overlaid resource. If you're searching for a resource that is found only in the base, you won't find it. Instead, always use DmGetResource() or DmGet1Resource() to obtain a resource. Both of those functions search both the overlay databases and their associated base databases.

DmNumDatabases Function ^TOP^

Purpose

Determine how many databases reside on a memory card.

Declared In

DataMgr.h

Prototype

UInt16 DmNumDatabases (
   UInt16cardNo
)

Parameters

cardNo
Number of the card to check.

Returns

The number of databases found.

Comments

This routine is helpful for getting a directory of all databases on a card. The routine DmGetDatabase() accepts an index from 0 to DmNumDatabases() -1 and returns a database ID by index.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmGetDatabase()

DmNumRecords Function ^TOP^

Purpose

Return the number of records in a database.

Declared In

DataMgr.h

Prototype

UInt16 DmNumRecords (
   DmOpenRefdbP
)

Parameters

dbP
DmOpenRef to open database.

Returns

The number of records in a database.

Comments

Records that have that have the deleted bit set (that is, records that will be deleted during the next synchronization because the user has marked them deleted) are included in the count. If you want to exclude these records from your count, use DmNumRecordsInCategory() and pass dmAllCategories as the category.

See Also

DmNumRecordsInCategory(), DmRecordInfo(), DmSetRecordInfo()

DmNumRecordsInCategory Function ^TOP^

Purpose

Return the number of records of a specified category in a database.

Declared In

DataMgr.h

Prototype

UInt16 DmNumRecordsInCategory (
   DmOpenRefdbP,
   UInt16category
)

Parameters

dbP
DmOpenRef to open database.
category
Category index.

Returns

The number of records in the category.

Comments

Because this function must examine all records in the database, it can be slow to return, especially when called on a large database.

Records that have the deleted bit set are not counted, and if the user has specified to hide or mask private records, private records are not counted either.

You can use the DmRecordInfo() call to obtain a category index from a given record. For example:


DmOpenRef myDB; 
UInt16 record, attr, category, total; 
 
DmRecordInfo(myDB, record, &attr, NULL, NULL); 
category = attr & dmRecAttrCategoryMask; 
total = DmNumRecordsInCategory(myDB, category); 

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmNumRecords(), DmQueryNextInCategory(), DmPositionInCategory(), DmSeekRecordInCategory(), DmMoveCategory()

DmNumResources Function ^TOP^

Purpose

Return the total number of resources in a given resource database.

Declared In

DataMgr.h

Prototype

UInt16 DmNumResources (
   DmOpenRefdbP
)

Parameters

dbP
DmOpenRef to open database.

Returns

The total number of resources in the given database.

May display a fatal error message if the database is not a resource database.

Comments

DmNumResources only counts the resources in the database indicated by the DmOpenRef parameter. If the database is a resource database that has an overlay associated with it, this function only returns the number of resources in the base database, not in the overlay.

DmOpenDatabase Function ^TOP^

Purpose

Open a database and return a reference to it. If the database is a resource database, also open its overlay for the current locale.

Declared In

DataMgr.h

Prototype

DmOpenRef DmOpenDatabase (
   UInt16cardNo,
   LocalIDdbID,
   UInt16mode
)

Parameters

cardNo
Card number database resides on.
dbID
The database ID of the database.
mode
Which mode to open database in (see "Open Mode Constants").

Returns

Returns DmOpenRef to open database. May display a fatal error message if the database parameter is NULL or is an invalid ID. On all other errors, this function returns 0 and DmGetLastErr() returns an error code indicating the reason for failure.

Comments

Call this routine to open a database for reading or writing.

This routine returns a DmOpenRef which must be used to access particular records in a database. If unsuccessful, 0 is returned and the cause of the error can be determined by calling DmGetLastErr().

When you use this routine to open a resource database in read-only mode, it also opens the overlay associated with this database for the current locale, if it exists. (The function OmGetCurrentLocale() returns the current locale.) Overlays are resource databases typically used to localize applications, shared libraries, and panels. They have the same creator as the base database, a type of 'ovly' (symbolically named omOverlayDBType), and contain resources with the same IDs and types as the resources in the base database. When you request a resource from the database using DmGetResource() or DmGet1Resource(), the overlay is searched first. If the overlay contains a resource for the given ID, it is returned. If not, the resource from the base database is returned.

The DmOpenRef returned by this function is the pointer to the base database, not to the overlay database, so care should be taken when passing this pointer to functions such as DmFindResource() because this circumvents the overlay.

It's possible to create a "stripped" base resource database, one that does not contain any user interface resources. DmOpenDatabase only opens a stripped database if its corresponding overlay exists. If the overlay does not exist or if the overlay doesn't match the resource database, DmOpenDatabase returns NULL and DmGetLastErr() returns the error code omErrBaseRequiresOverlay.

If you open a resource database in a writable mode, the associated overlay is not opened. If you make changes to the resource database, the overlay database is invalidated if those changes affect any resources that are also in the overlay. This means that on future occasions where you open the resource database in read-only mode, the overlay will not be opened because Palm OS considers it to be invalid.


TIP: If you want to prevent your resource database from being overlaid, include an 'xprf' resource (symbolically named sysResTExtPrefs) in the database with the ID 0 (sysResIDExtPrefs) and set its disableOverlays flag. This resource is defined in UIResources.r.

Compatibility

Overlay support is only available if 3.5 New Feature Set is present. On earlier releases, this function opens resource databases without looking for an associated overlay.

If 4.0 New Feature Set is present, when DmOpenDatabase attempts to open a stripped resource database and cannot find an overlay for it, it searches for an overlay matching the default locale if the system locale is different from the default locale.

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmCloseDatabase(), DmCreateDatabase(), DmFindDatabase(), DmOpenDatabaseByTypeCreator(), DmDeleteDatabase(), DmOpenDBNoOverlay()

DmOpenDatabaseByTypeCreator Function ^TOP^

Purpose

Open the most recent revision of a database with the given type and creator. If the database is a resource database, also open its overlay for the current locale.

Declared In

DataMgr.h

Prototype

DmOpenRef DmOpenDatabaseByTypeCreator(
   UInt32type,
   UInt32creator,
   UInt16mode
)

Parameters

type
Type of database.
creator
Creator of database.
mode
Which mode to open database in (see "Open Mode Constants").

Returns

DmOpenRef to open database. If the database couldn't be found, this function returns 0 and DmGetLastErr() returns an error code indicating the reason for failure.

Comments

If you use this routine to open a resource database in read-only mode, it also opens the overlay associated with this database for the current locale. See DmOpenDatabase() for more information on overlays and resource databases.

Compatibility

Overlay support is only available if 3.5 New Feature Set is present. On earlier releases, this function opens resource databases without looking for an associated overlay.

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmCreateDatabase(), DmOpenDatabase(), DmOpenDatabaseInfo(), DmCloseDatabase(), DmOpenDBNoOverlay()

DmOpenDatabaseInfo Function ^TOP^

Purpose

Retrieve information about an open database.

Declared In

DataMgr.h

Prototype

Err DmOpenDatabaseInfo (
   DmOpenRefdbP,
   LocalID*dbIDP,
   UInt16*openCountP,
   UInt16*modeP,
   UInt16*cardNoP,
   Boolean*resDBP
)

Parameters

dbP
DmOpenRef to open database.
dbIDP
The ID of the database. Pass NULL for this parameter if you don't want to retrieve this information.
openCountP
The number of applications that have this database open. Pass NULL for this parameter if you don't want to retrieve this information.
modeP
The mode used to open the database (see "Open Mode Constants"). Pass NULL for this parameter if you don't want to retrieve this information.
cardNoP
The number of the card on which this database resides. Pass NULL for this parameter if you don't want to retrieve this information.
resDBP
If true upon return, the database is a resource database, false otherwise. Pass NULL for this parameter if you don't want to retrieve this information.

Returns

Returns errNone if no error.

See Also

DmDatabaseInfo()

DmOpenDBNoOverlay Function ^TOP^

Purpose

Open a database and return a reference to it.

Declared In

DataMgr.h

Prototype

DmOpenRef DmOpenDBNoOverlay (
   UInt16cardNo,
   LocalIDdbID,
   UInt16mode
)

Parameters

cardNo
Card number database resides on.
dbID
The database ID of the database.
mode
Which mode to open database in (see "Open Mode Constants").

Returns

DmOpenRef to open database. May display a fatal error message if the database parameter is NULL. On all other errors, this function returns 0 and DmGetLastErr() returns an error code indicating the reason for failure.

Comments

Call this routine to open a database for reading or writing, while ignoring any overlay databases that might be associated with it.

This routine returns a DmOpenRef which must be used to access particular records in a database. If unsuccessful, 0 is returned and the cause of the error can be determined by calling DmGetLastErr().

Compatibility

Implemented only if 3.5 New Feature Set is present.

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmCloseDatabase(), DmCreateDatabase(), DmFindDatabase(), DmOpenDatabaseByTypeCreator(), DmDeleteDatabase(), DmOpenDatabase()

DmPositionInCategory Function ^TOP^

Purpose

Return a position of a record within the specified category.

Declared In

DataMgr.h

Prototype

UInt16 DmPositionInCategory (
   DmOpenRefdbP,
   UInt16index,
   UInt16category
) 

Parameters

dbP
DmOpenRef to open database.
index
Index of the record.
category
Index of category to search.

Returns

Returns the position (zero-based). If the specified index is out of range, this function returns 0 and DmGetLastErr() returns an error code indicating the reason for failure. Note that this means a 0 return value might indicate either success or failure. If this function returns 0 and DmGetLastErr returns errNone, the return value indicates that this is the first record in the category.

Comments

Because this function must examine all records up to the current record, it can be slow to return, especially when called on a large database.

Records that have the deleted bit set are ignored, and if the user has specified that private records should be hidden or masked, private records are ignored as well.

If the record is ROM-based (pointer accessed) this routine makes a fake handle to it and stores this handle in the DmAccessType structure.

To learn which category a record is in, use DmRecordInfo().

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmQueryNextInCategory(), DmSeekRecordInCategory(), DmMoveCategory()

DmQueryNextInCategory Function ^TOP^

Purpose

Return a handle to the next record in the specified category for reading only (does not set the busy bit).

Declared In

DataMgr.h

Prototype

MemHandle DmQueryNextInCategory (
   DmOpenRefdbP,
   UInt16*indexP,
   UInt16category
)

Parameters

dbP
DmOpenRef to open database.
indexP
Index of a known record (often retrieved with DmPositionInCategory()). If a "next" record is found, this index is updated to indicate that record.
category
Index of category to query, or dmAllCategories to find the next record in any category.

Returns

Returns a handle to the record following a known record, along with the index of that record. If a record couldn't be found, this function returns NULL, and DmGetLastErr() returns an error code indicating the reason for failure.

Comments

This function begins searching the database from the record at *indexP for a record that is in the specified category. If the record at *indexP belongs to that category, then a handle to it is returned. If not, the function continues searching until it finds a record in the category.

Records that have the deleted bit set are skipped, and if the user has specified that private records should be hidden or masked, private records are skipped as well.

Thus, if you want to find the next record in the category after the one you have an index for, increment the index value before calling this function. For example:


DmOpenRef myDB; 
UInt16 record, attr, category, pos; 
MemHandle newRecH; 
 
DmRecordInfo(myDB, record, &attr, NULL, NULL); 
category = attr & dmRecAttrCategoryMask; 
pos = DmPositionInCategory(myDB, record,  
category); 
pos++; 
newRecH = DmQueryNextInCategory(myDB, &pos, category); 

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmNumRecordsInCategory(), DmPositionInCategory(), DmSeekRecordInCategory()

DmQueryRecord Function ^TOP^

Purpose

Return a handle to a record for reading only (does not set the busy bit).

Declared In

DataMgr.h

Prototype

MemHandle DmQueryRecord (
   DmOpenRefdbP,
   UInt16index
)

Parameters

dbP
DmOpenRef to open database.
index
Which record to retrieve.

Returns

Returns a record handle. If an error occurs, this function returns NULL, and DmGetLastErr() returns an error code indicating the reason for failure.

Some releases may display a fatal error message if the specified index is out of range.

Comments

Returns a handle to the given record. Use this routine only when viewing the record. This routine successfully returns a handle to the record even if the record is busy.

If the record is ROM-based (pointer accessed) this routine returns the fake handle to it.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

DmQuickSort Function ^TOP^

Purpose

Sort records in a database.

Declared In

DataMgr.h

Prototype

Err DmQuickSort (
   DmOpenRefdbP,
   DmComparF*compar,
   Int16other
)

Parameters

dbP
Database access pointer.
compar
Comparison function. See DmComparF().
other
Any value the application wants to pass to the comparison function. This parameter is often used to indicate a sort direction (ascending or descending).

Returns

Returns errNone if no error, or one of the following if an error occurs:

Some releases may display a fatal error message instead of returning the error code.

Comments

Deleted records are placed last in any order. All others are sorted according to the passed comparison function.

After DmQuickSort returns, equal database records do not have a consistent order. That is, if DmQuickSort is passed two equal records, their resulting order is unpredictable. To prevent records that contain the same data from being rearranged in an unpredictable order, pass the record's unique ID to the comparison function (using the SortRecordInfoType structure).

DmQuickSort contains its own stack to limit uncontrolled recursion. When the stack is full DmQuickSort instead performs an insertion sort. An insertion sort is also performed when the number of records is low, avoiding the noticeable overhead of a quick sort with a small number of records. Finally, if the records seem mostly sorted an insertion sort is performed to move only those records that need moving.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmFindSortPositionV10(), DmInsertionSort()

DmRecordInfo Function ^TOP^

Purpose

Retrieve the record information as stored in the database header.

Declared In

DataMgr.h

Prototype

Err DmRecordInfo (
   DmOpenRefdbP,
   UInt16index,
   UInt16*attrP,
   UInt32*uniqueIDP,
   LocalID*chunkIDP
)

Parameters

dbP
DmOpenRef to open database.
index
Index of the record.
attrP
The record's attributes. See "Record Attribute Constants." Pass NULL for this parameter if you don't want to retrieve this value.
uniqueIDP
The record's unique ID. Pass NULL for this parameter if you don't want to retrieve this value.
chunkIDP
The record's local ID. Pass NULL for this parameter if you don't want to retrieve this value.

Returns

Returns errNone if no error or dmErrIndexOutOfRange if the specified record can't be found. Some releases may display a fatal error message instead of returning the error code.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmNumRecords(), DmSetRecordInfo(), DmQueryNextInCategory()

DmReleaseRecord Function ^TOP^

Purpose

Clear the busy bit for the given record and set the dirty bit if dirty is true.

Declared In

DataMgr.h

Prototype

Err DmReleaseRecord (
   DmOpenRefdbP,
   UInt16index,
   Booleandirty
)

Parameters

dbP
DmOpenRef to open database.
index
The record to unlock.
dirty
If true, set the dirty bit.

Returns

Returns errNone if no error, or dmErrIndexOutOfRange if the specified index is out of range. Some releases may display a fatal error message instead of returning the error code.

Comments

Call this routine when you finish modifying or reading a record that you've called DmGetRecord() on or created using DmNewRecord().

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmGetRecord()

DmReleaseResource Function ^TOP^

Purpose

Release a resource acquired with DmGetResource().

Declared In

DataMgr.h

Prototype

Err DmReleaseResource (
   MemHandleresourceH
)

Parameters

resourceH
Handle to resource.

Returns

Returns errNone if no error.

Comments

Marks a resource as being no longer needed by the application.

See Also

DmGet1Resource(), DmGetResource()

DmRemoveRecord Function ^TOP^

Purpose

Remove a record from a database and dispose of its data chunk.

Declared In

DataMgr.h

Prototype

Err DmRemoveRecord (
   DmOpenRefdbP,
   UInt16index
)

Parameters

dbP
DmOpenRef to open database.
index
Index of the record to remove.

Returns

Returns errNone if no error, or one of the following if an error occurs:

Some releases may display a fatal error message instead of returning the error code.

Comments

Disposes of a the record's data chunk and removes the record's entry from the database header. DmRemoveRecord should only be used for newly-created records that have just been deleted or records that have never been sync'ed.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmDetachRecord(), DmDeleteRecord(), DmArchiveRecord(), DmNewRecord()

DmRemoveResource Function ^TOP^

Purpose

Delete a resource from a resource database.

Declared In

DataMgr.h

Prototype

Err DmRemoveResource (
   DmOpenRefdbP,
   UInt16index
) 

Parameters

dbP
DmOpenRef to open database.
index
Index of resource to delete.

Returns

Returns errNone if no error, or one of the following if an error occurs:

May display a fatal error message if the database is not a resource database.

Comments

This routine disposes of the memory manager chunk that holds the given resource and removes its entry from the database header.

See Also

DmDetachResource(), DmRemoveResource(), DmAttachResource()

DmRemoveSecretRecords Function ^TOP^

Purpose

Remove all secret records.

Declared In

DataMgr.h

Prototype

Err DmRemoveSecretRecords (
   DmOpenRefdbP
)

Parameters

dbP
DmOpenRef to open database.

Returns

Returns errNone if no error, or one of the following if an error occurs:

Some releases may display a fatal error message instead of returning the error code.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, sysErrNotAllowed is returned. For more information see "Accessing the PIM Application Databases."

See Also

DmRemoveRecord(), DmRecordInfo(), DmSetRecordInfo()

DmResizeRecord Function ^TOP^

Purpose

Resize a record by index.

Declared In

DataMgr.h

Prototype

MemHandle DmResizeRecord (
   DmOpenRefdbP,
   UInt16index,
   UInt32newSize
)

Parameters

dbP
DmOpenRef to open database.
index
Which record to retrieve.
newSize
New size of record.

Returns

Handle to resized record. Returns NULL if there is not enough space to resize the record, and DmGetLastErr() returns an error code indicating the reason for failure. Some releases may display a fatal error message instead of returning the error code.

Comments

This routine reallocates the record in another heap of the same memory card if the current heap is not big enough. If this happens, the handle changes, so be sure to use the returned handle to access the resized record.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

DmResizeResource Function ^TOP^

Purpose

Resize a resource and return the new handle.

Declared In

DataMgr.h

Prototype

MemHandle DmResizeResource (
   MemHandleresourceH,
   UInt32newSize
)

Parameters

resourceH
Handle to resource.
newSize
Desired new size of resource.

Returns

Returns a handle to newly sized resource. Returns NULL if there is not enough space to resize the resource, and DmGetLastErr() returns an error code indicating the reason for failure. Some releases may display a fatal error message instead of returning the error code.

Comments

Resizes the resource and returns a new handle. If necessary in order to grow the resource, this routine will reallocate it in another heap on the same memory card that it is currently in.

The handle may change if the resource had to be reallocated in a different data heap because there was not enough space in its present data heap.

DmResourceInfo Function ^TOP^

Purpose

Retrieve information on a given resource.

Declared In

DataMgr.h

Prototype

Err DmResourceInfo (
   DmOpenRefdbP,
   UInt16index,
   DmResType*resTypeP,
   DmResID*resIDP,
   LocalID*chunkLocalIDP
)

Parameters

dbP
DmOpenRef to open database.
index
Index of resource to get info on.
resTypeP
The resource type. Pass NULL if you don't want to retrieve this information.
resIDP
The resource ID. Pass NULL if you don't want to retrieve this information.
chunkLocalIDP
The memory manager local ID of the resource data. Pass NULL if you don't want to retrieve this information.

Returns

Returns errNone if no error or dmErrIndexOutOfRange if an error occurred. May display a fatal error message if the database is not a resource database.

Comments

If dbP is a pointer to a base resource database, the information returned is about the resource from that database alone; this function ignores any associated overlay.

See Also

DmGetResource(), DmGet1Resource(), DmSetResourceInfo(), DmFindResource(), DmFindResourceType()

DmSearchRecord Function ^TOP^

Purpose

Search all open record databases for a record with the handle passed.

Declared In

DataMgr.h

Prototype

UInt16 DmSearchRecord (
   MemHandlerecH,
   DmOpenRef*dbPP
)

Parameters

recH
Record handle.
dbPP
The database that contains the record recH.

Returns

Returns the index of the record and database access pointer; if not found, returns -1 and *dbPP is 0.

See Also

DmGetRecord(), DmFindRecordByID(), DmRecordInfo()

DmSearchResource Function ^TOP^

Purpose

Search all open resource databases for a resource by type and ID, or by pointer if it is non-NULL.

Declared In

DataMgr.h

Prototype

UInt16 DmSearchResource (
   DmResTyperesType,
   DmResIDresID,
   MemHandleresH,
   DmOpenRef*dbPP
)

Parameters

resType
Type of resource to search for.
resID
ID of resource to search for.
resH
Pointer to locked resource, or NULL.
dbPP
The resource database that contains the specified resource.

Returns

Returns the index of the resource, stores DmOpenRef in dbPP.

Comments

This routine can be used to find a resource in all open resource databases by type and ID or by pointer. If resH is NULL, the resource is searched for by type and ID. If resH is not NULL, resType and resID is ignored and the index of the resource handle is returned. On return, *dbPP contains the access pointer of the resource database that the resource was eventually found in. Once the index of a resource is determined, it can be locked down and accessed by calling DmGetResourceIndex().

If any of the open databases are overlaid, this function finds and returns the localized version of the resource when searching by type and creator. In this case, the dbPP return value is a pointer to the overlay database, not the base resource database.

See Also

DmGetResource(), DmFindResourceType(), DmResourceInfo(), DmFindResource()

DmSeekRecordInCategory Function ^TOP^

Purpose

Return the index of the record nearest the offset from the passed record index whose category matches the passed category. (The offset parameter indicates the number of records to move forward or backward.)

Declared In

DataMgr.h

Prototype

Err DmSeekRecordInCategory (
   DmOpenRefdbP,
   UInt16*indexP,
   UInt16offset,
   Int16direction,
   UInt16category
)

Parameters

dbP
DmOpenRef to open database.
index
The index to start the search at. Upon return, contains the index of the record at offset from the index that you passed in.
offset
Offset of the passed record index. This must be a positive number; use dmSeekBackward for the direction parameter to search backwards.
direction
Must be either dmSeekForward or dmSeekBackward.
category
Category index.

Returns

Returns errNone if no error; returns dmErrIndexOutOfRange or dmErrSeekFailed if an error occurred.

Comments

DmSeekRecordInCategory searches for a record in the specified category. The search begins with the record at index. When it finds a record in the specified category, it decrements the offset parameter and continues searching until a match is found and offset is 0.

Because of this, if you use DmSeekRecordInCategory to find the nearest matching record in a particular category, you must pass different offset parameters if the starting record is in the category than if it isn't. If the record at index is in the category, then you must pass an offset of 1 to find the next record in the category because the comparison is performed before the index value changes. If the record at index isn't in the category, you must pass an offset of 0 to find the next record in the category. In this case, an offset of 1 skips the first matching record.

Records that have the deleted bit set are ignored, and if the user has specified that private records should be hidden or masked, private records are ignored as well.

See Also

DmNumRecordsInCategory(), DmQueryNextInCategory(), DmPositionInCategory(), DmMoveCategory()

DmSet Function ^TOP^

Purpose

Write a specified value into a section of a record. This function also checks the validity of the pointer for the record and makes sure the writing of the record information doesn't exceed the bounds of the record.

Declared In

DataMgr.h

Prototype

Err DmSet (
   void*recordP,
   UInt32offset,
   UInt32bytes,
   UInt8value
)

Parameters

recordP
Pointer to locked data record (chunk pointer).
offset
Offset within record to start writing.
bytes
Number of bytes to write.
value
Byte value to write.

Returns

Returns errNone if no error. May display a fatal error message if the record pointer is invalid or the function overwrites the record.

Comments

Must be used to write to data manager records because the data storage area is write-protected.

See Also

DmWrite()

DmSetDatabaseInfo Function ^TOP^

Purpose

Set information about a database.

Declared In

DataMgr.h

Prototype

Err DmSetDatabaseInfo (
   UInt16cardNo,
   LocalIDdbID,
   constChar*nameP,
   UInt16*attributesP,
   UInt16*versionP,
   UInt32*crDateP,
   UInt32*modDateP,
   UInt32*bckUpDateP,
   UInt32*modNumP,
   LocalID*appInfoIDP,
   LocalID*sortInfoIDP,
   UInt32*typeP,
   UInt32*creatorP
)

Parameters

cardNo
Card number the database resides on.
dbID
Database ID of the database.
nameP
Pointer to the new name of the database, or NULL. A database name can be up to 32 ASCII bytes long, including the null terminator (as specified by dmDBNameLength). Database names must use only 7-bit ASCII characters (0x20 through 0x7E).
attributesP
Pointer to new attributes variable, or NULL. See "Database Attribute Constants" for a list of possible values.
versionP
Pointer to new version, or NULL.
crDateP
Pointer to new creation date variable, or NULL. Specify the value as a number of seconds since Jan. 1, 1904.
modDateP
Pointer to new modification date variable, or NULL. Specify the value as a number of seconds since Jan. 1, 1904.
bckUpDateP
Pointer to new backup date variable, or NULL. Specify the value as a number of seconds since Jan. 1, 1904.
modNumP
Pointer to new modification number variable, or NULL.
appInfoIDP
Pointer to new appInfoID variable, or NULL.
sortInfoIDP
Pointer to new sortInfoID variable, or NULL.
typeP
Pointer to new type variable, or NULL.
creatorP
Pointer to new creator variable, or NULL.

Returns

Returns errNone if no error or one of the following if an error occurred:

Comments

When this call changes appInfoID or sortInfoID, the old chunk ID (if any) is marked as an orphaned chunk1 and the new chunk ID is unorphaned. Consequently, you shouldn't replace an existing appInfoID or sortInfoID if that chunk has already been attached to another database.

Call this routine to set any or all information about a database except for the card number and database ID. This routine sets the new value for any non-NULL parameter.

See Also

DmDatabaseInfo(), DmOpenDatabaseInfo(), DmFindDatabase(), DmGetNextDatabaseByTypeCreator(), TimDateTimeToSeconds()

DmSetRecordInfo Function ^TOP^

Purpose

Set record information stored in the database header.

Declared In

DataMgr.h

Prototype

Err DmSetRecordInfo (
   DmOpenRefdbP,
   UInt16index,
   UInt16*attrP,
   UInt32*uniqueIDP
)

Parameters

dbP
DmOpenRef to open database.
index
Index of record.
attrP
Pointer to new attribute variable, or NULL. See "Record Attribute Constants" for a list of possible values.
uniqueIDP
Pointer to new unique ID variable, or NULL.

Returns

Returns errNone if no error, or one of the following if an error occurred:

Some releases may display a fatal error message instead of returning the error code.

Comments

Sets information about a record. This routine cannot be used to set the dmRecAttrBusy bit; instead, use DmGetRecord() to set the bit and DmReleaseRecord() to clear it.

Normally, the unique ID for a record is automatically created by the data manager when a record is created using DmNewRecord(), so an application would not typically change the unique ID.

Compatibility

If Palm OS Cobalt Feature Set is present and the call to this function involves a PIM application database, PACE intercepts the call and takes the appropriate action on the corresponding schema database. For more information see "Accessing the PIM Application Databases."

See Also

DmNumRecords(), DmRecordInfo()

DmSetResourceInfo Function ^TOP^

Purpose

Set information on a given resource.

Declared In

DataMgr.h

Prototype

Err DmSetResourceInfo (
   DmOpenRefdbP,
   UInt16index,
   DmResType*resTypeP,
   DmResID*resIDP
)

Parameters

dbP
DmOpenRef to open database.
index
Index of resource to set info for.
resTypeP
Pointer to new resType (resource type), or NULL.
resIDP
Pointer to new resource ID, or NULL.

Returns

Returns errNone if no error, or one of the following if an error occurred:

May display a fatal error message if the database is not a resource database.

Comments

Use this routine to set all or a portion of the information on a particular resource. Any or all of the new info pointers can be NULL. If not NULL, the type and ID of the resource are changed to *resTypeP and *resIDP.

DmStrCopy Function ^TOP^

Purpose

Copies a string to a record within a database that is open for writing.

Declared In

DataMgr.h

Prototype

Err DmStrCopy (
   void*recordP,
   UInt32offset,
   constChar*srcP
)

Parameters

recordP
Pointer to data record (chunk pointer).
offset
Offset within record to start writing.
srcP
Pointer to null-terminated string.

Returns

Returns errNone if no error. May display a fatal error message if the record pointer is invalid or the function overwrites the record.

Comments

This is one of the routines that must be used to write to Data Manager records; because the data storage area is write-protected, you cannot write to it directly. This routine checks the validity of the chunk pointer for the record to insure that writing the record will not exceed the chunk bounds. DmStrCopy is a convenience method that determines the size of the supplied string and then simply calls DmWrite().

See Also

DmSet()

DmSync Function ^TOP^

Purpose

Update the automatic backup files for all open databases. This function is deprecated; developers should use DmSyncDatabase() instead.

Declared In

DataMgr.h

Prototype

void DmSync(
   void
)

Parameters

None.

Returns

Nothing.

Compatibility

This function is not supported on Palm OS Cobalt and is deprecated on Palm OS Garnet. Developers should use DmSyncDatabase() instead.

DmSyncDatabase Function ^TOP^

Purpose

Update the automatic backup file for a given open database.

Declared In

DataMgr.h

Prototype

Err DmSyncDatabase (
   DmOpenRef dbRef
)

Parameters

dbRef
A DmOpenRef to an open database.

Returns

Returns errNone if no error, or one of the following if an error occurs:

dmErrInvalidParam
dbRef isn't a valid reference to an open database.
dmErrReadOnly
dbRef references a database that is open in read-only mode. The database must be open for writing
dmErrOperationAborted
The Palm OS device doesn't support the automatic database backup feature.

Comments

The database is left open.

Use this function to cause an open database to be backed up.

Many devices running Palm OS Cobalt version 6.1 will back up the contents of the RAM storage heaps to some sort of non-volatile NAND flash. In the event that the RAM storage heaps are corrupted or are lost for some reason, the storage heaps can then be restored to their saved state. Backup is automatically triggered on a limited set of events: database close, database create, a call to DmSetDatabaseInfo(), or upon device sleep (open databases only). Developers can explicitly cause a database to be backed up by calling DmSyncDatabase().

For additional information on this feature, see "Automatic Database Backup and Restore."

Compatibility

In order to determine whether or not a given device has this capability, check for the presence of the sysFtrNumDmAutoBackup feature.

DmWrite Function ^TOP^

Purpose

Copies a specified number of bytes to a record within a database that is open for writing.

Declared In

DataMgr.h

Prototype

Err DmWrite (
   void*recordP,
   UInt32offset,
   constvoid*srcP,
   UInt32bytes
)

Parameters

recordP
Pointer to locked data record (chunk pointer).
offset
Offset within record to start writing.
srcP
Pointer to data to copy into record.
bytes
Number of bytes to write.

Returns

Returns errNone if no error. May display a fatal error message if the record pointer is invalid or the function overwrites the record.

Comments

This is one of the routines that must be used to write to Data Manager records; because the data storage area is write-protected, you cannot write to it directly. This routine checks the validity of the chunk pointer for the record to insure that writing the record will not exceed the chunk bounds.

See Also

DmStrCopy(), DmSet()

DmWriteCheck Function ^TOP^

Purpose

Check the parameters of a write operation to a data storage chunk before actually performing the write.

Declared In

DataMgr.h

Prototype

Err DmWriteCheck (
   void*recordP,
   UInt32offset,
   UInt32bytes
)

Parameters

recordP
Locked pointer to recordH.
offset
Offset into record to start writing.
bytes
Number of bytes to write.

Returns

Returns errNone if no error; returns dmErrNotValidRecord or dmErrWriteOutOfBounds if an error occurred.

Application-Defined Functions ^TOP^

DmComparF Function ^TOP^

Purpose

Compares two records in a database.

Declared In

DataMgr.h

Prototype

typedef Int16 DmComparF (
   void*rec1,
   void*rec2,
   Int16other,
   SortRecordInfoPtrrec1SortInfo,
   SortRecordInfoPtrrec2SortInfo,
   MemHandleappInfoH
)

Parameters

rec1, rec2
Pointers to the two records to compare.
other
Any other custom information you want passed to the comparison function. This parameter is often used to indicate a sort direction (ascending or descending).
rec1SortInfo, rec2SortInfo
Pointers to SortRecordInfoType structures that specify unique sorting information for the two records.
appInfoH
A handle to the database's application info block.

Returns

Returns:

  • 0 if rec1 = rec2.
  • < 0 if rec1 < rec2.
  • > 0 if rec1 > rec2.

Comments

This function is used to sort the records in a database. It is specifically called by DmFindSortPosition(), DmInsertionSort(), and DmQuickSort().

Compatibility

The DmComparF prototype changed in Palm OS version 2.0. Previously, the prototype only defined the first three parameters.

As a rule, the change in the number of arguments from three to six doesn't cause problems when a 1.0 application is run on a 2.0 device because the system only pulls the arguments from the stack that are there.

Keep in mind, however, that some optimized applications built with tools other than Metrowerks CodeWarrior for Palm OS may have problems as a result of the change in arguments when running on a 2.0 or later device.


1. An "orphaned chunk" is one that is allocated in the storage heap, but to which nothing refers. If the orphaned chunk is not put into a database as a record, an appInfo block, or the like, and if the application doesn't keep track of it—in a global variable, perhaps—it could get lost. If the application doesn't get around to freeing the chunk before it quits or crashes, or before the device is reset, that storage will be forever unusable: the user can't delete it since the user only deletes databases.

1.

1. During a soft reset, the OS walks through the storage heap and frees any orphaned chunks that it finds. Since most users reset only rarely, however, you shouldn't rely on this happening.