26 Data and Resource Manager

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

• Data Manager Data Structures
  
  
• Data Manager Constants
  
  
• Data Manager Functions
  
  
• Application-Defined Functions
  

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

Data Manager Data Structures

DmOpenRef

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.

typedef void* DmOpenRef

DmResID

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

typedef UInt16 DmResID;

DmResType

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

typedef UInt32 DmResType;

SortRecordInfoType

The SortRecordInfoType structure specifies information that might be used to sort a record. It is used in the database sorting functions. To create this structure, you can call DmRecordInfo, which returns these values for a given record.

typedef struct {

    UInt8 attributes;
    UInt8 uniqueID[3];
} SortRecordInfoType;

typedef SortRecordInfoType * SortRecordInfoPtr;

Field Descriptions

Data Manager Constants

Category Constants

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

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.)
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

The following constants define a database's attributes:

Constant	Description
dmAllHdrAttrs	A mask used to specify all header attributes.
dmDBNameLength	Maximum length of a database's name. Currently, this is 32 bytes, which include the null terminator. Note that database names must use only 7-bit ASCII characters (0x20 through 0x7E).
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.
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. 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 Clipper 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® Shortcuts database, for example.
dmHdrAttrReadOnly	The database is a read-only database.
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

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.
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

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.

Data Manager Functions

DmArchiveRecord

Purpose

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

Prototype

Err DmArchiveRecord (DmOpenRef dbP, UInt16 index)

Parameters

-> dbP

DmOpenRef to open database.

-> index

Which record to archive.

Result

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

• dmErrReadOnly
  
  
• dmErrIndexOutOfRange
  
  
• dmErrRecordArchived
  
  
• dmErrRecordDeleted
  
  
• memErrInvalidParam
  

  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 OS device.

See Also

DmRemoveRecord, DmDetachRecord, DmNewRecord, DmDeleteRecord

DmAttachRecord

Purpose

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

Prototype

Err DmAttachRecord (DmOpenRef dbP, UInt16* atP, MemHandle newH, 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.

Result

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

• dmErrMemError
  
  
• memErrChunkLocked
  
  
• memErrInvalidParam
  
  
• memErrNotEnoughSpace
  
  
• dmErrReadOnly
  
  
• dmErrNotRecordDB
  
  
• dmErrRecordInWrongCard
  
  
• dmErrIndexOutOfRange
  

  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.

See Also

DmDetachRecord, DmNewRecord, DmNewHandle, DmFindSortPosition

DmAttachResource

Purpose

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

Prototype

Err DmAttachResource (DmOpenRef dbP, MemHandle newH, DmResType resType, DmResID resID)

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.

Result

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

• dmErrMemError
  
  
• memErrChunkLocked
  
  
• memErrInvalidParam
  
  
• memErrNotEnoughSpace
  
  
• dmErrReadOnly
  
  
• dmErrRecordInWrongCard
  

  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

Purpose

Close a database.

Prototype

Err DmCloseDatabase (DmOpenRef dbP)

Parameters

-> dbP

Database access pointer.

Result

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 this reference because the record can disappear if the database is deleted by the user or during a HotSync^®. 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.

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.

See Also

DmOpenDatabase, DmDeleteDatabase, DmOpenDatabaseByTypeCreator

DmCreateDatabase

Purpose

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

Prototype

Err DmCreateDatabase (UInt16 cardNo, const Char * nameP, UInt32 creator, UInt32 type, Boolean resDB)

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.

Result

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

• dmErrInvalidDatabaseName
  
  
• dmErrAlreadyExists
  
  
• memErrCardNotPresent
  
  
• dmErrMemError
  
  
• memErrChunkLocked
  
  
• memErrInvalidParam
  
  
• memErrInvalidStoreHeader
  
  
• memErrNotEnoughSpace
  
  
• memErrRAMOnlyCard
  

  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

Purpose

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

Prototype

Err DmCreateDatabaseFromImage (MemPtr bufferP)

Parameters

-> bufferP

Pointer to locked resource containing database image.

Result

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

Purpose

Retrieve information about a database.

Prototype

Err DmDatabaseInfo (UInt16 cardNo, LocalID dbID, 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.

Result

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

Purpose

Increment or decrement the database's protection count.

Prototype

Err DmDatabaseProtect (UInt16 cardNo, LocalID dbID, Boolean protect)

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.

Result

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

• memErrCardNotPresent
  
  
• dmErrROMBased
  
  
• dmErrCantFind
  
  
• memErrNotEnoughSpace
  
  
• dmErrDatabaseNotProtected
  

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

Purpose

Retrieve size information on a database.

Prototype

Err DmDatabaseSize (UInt16 cardNo, LocalID dbID, 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.

Result

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

See Also

DmDatabaseInfo, DmOpenDatabaseInfo, DmFindDatabase, DmGetNextDatabaseByTypeCreator

DmDeleteCategory

Purpose

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

Prototype

Err DmDeleteCategory (DmOpenRef dbR, UInt16 categoryNum)

Parameters

-> dbR

Database access pointer.

-> categoryNum

Category of records to delete. Category masks such as dmAllCategories are invalid.

Result

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

• dmErrReadOnly
  
  
• memErrInvalidParam
  

  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. 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.

DmDeleteDatabase

Purpose

Delete a database and all its records.

Prototype

Err DmDeleteDatabase (UInt16 cardNo, LocalID dbID)

Parameters

-> cardNo

Card number the database resides on.

-> dbID

Database ID.

Result

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

• dmErrCantFind
  
  
• dmErrCantOpen
  
  
• memErrChunkLocked
  
  
• dmErrDatabaseOpen
  
  
• dmErrROMBased
  
  
• memErrInvalidParam
  
  
• memErrNotEnoughSpace
  

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.

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.

See Also

DmDeleteRecord, DmRemoveRecord, DmRemoveResource, DmCreateDatabase, DmGetNextDatabaseByTypeCreator, DmFindDatabase

DmDeleteRecord

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.

Prototype

Err DmDeleteRecord (DmOpenRef dbP, UInt16 index)

Parameters

-> dbP

DmOpenRef to open database.

-> index

Which record to delete.

Result

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

• dmErrReadOnly
  
  
• dmErrIndexOutOfRange
  
  
• dmErrRecordArchived
  
  
• dmErrRecordDeleted
  
  
• memErrInvalidParam
  

  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.

See Also

DmDetachRecord, DmRemoveRecord, DmArchiveRecord, DmNewRecord

DmDetachRecord

Purpose

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

Prototype

Err DmDetachRecord (DmOpenRef dbP, UInt16 index, MemHandle* oldHP)

Parameters

-> dbP

DmOpenRef to open.

-> index

Index of the record to detach.

<-> oldHP

Pointer to return handle of the detached record.

Result

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

• dmErrReadOnly
  
  
• dmErrIndexOutOfRange
  
  
• dmErrNotRecordDB
  
  
• memErrChunkLocked
  
  
• memErrInvalidParam
  

  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.

See Also

DmAttachRecord, DmRemoveRecord, DmArchiveRecord, DmDeleteRecord

DmDetachResource

Purpose

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

Prototype

Err DmDetachResource (DmOpenRef dbP, UInt16 index, MemHandle* oldHP)

Parameters

-> dbP

DmOpenRef to open database.

-> index

Index of resource to detach.

<-> oldHP

Pointer to return handle of the detached record.

Result

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

• dmErrReadOnly
  
  
• dmErrIndexOutOfRange
  
  
• dmErrCorruptDatabase
  
  
• memErrChunkLocked
  
  
• memErrInvalidParam
  

  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

Purpose

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

Prototype

LocalID DmFindDatabase (UInt16 cardNo, const Char* nameP)

Parameters

-> cardNo

Number of card to search.

-> nameP

Name of the database to look for.

Result

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.

See Also

DmGetNextDatabaseByTypeCreator, DmDatabaseInfo, DmOpenDatabase

DmFindRecordByID

Purpose

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

Prototype

Err DmFindRecordByID (DmOpenRef dbP, UInt32 uniqueID, UInt16* indexP)

Parameters

-> dbP

Database access pointer.

-> uniqueID

Unique ID to search for.

<- indexP

Return index.

Result

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

See Also

DmQueryRecord, DmGetRecord, DmRecordInfo

DmFindResource

Purpose

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

Prototype

UInt16 DmFindResource (DmOpenRef dbP, DmResType resType, DmResID resID, MemHandle resH)

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.

Result

Returns index of resource in resource database, or -1 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

Purpose

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

Prototype

UInt16 DmFindResourceType (DmOpenRef dbP, DmResType resType, UInt16 typeIndex)

Parameters

-> dbP

Open resource database access pointer.

-> resType

Type of resource to search for.

-> typeIndex

Index of given resource type.

Result

Index of resource in resource database, or -1 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

Purpose

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

Prototype

UInt16 DmFindSortPosition (DmOpenRef dbP, void* newRecord, SortRecordInfoPtr newRecordInfo, DmComparF *compar, Int16 other)

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.

Result

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.

See Also

DmFindSortPositionV10

DmFindSortPositionV10

Purpose

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

Prototype

UInt16 DmFindSortPositionV10 (DmOpenRef dbP, void* newRecord, DmComparF *compar, Int16 other)

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.

Result

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

Purpose

Return the local ID of the application info block.

Prototype

LocalID DmGetAppInfoID (DmOpenRef dbP).

Parameters

-> dbP

Database access pointer.

Result

Returns local ID of the application info block.

See Also

DmDatabaseInfo, DmOpenDatabase

DmGetDatabase

Purpose

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

Prototype

LocalID DmGetDatabase (UInt16 cardNo, UInt16 index)

Parameters

-> cardNo

Card number of database.

-> index

Index of database.

Result

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

Purpose

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

Prototype

void DmGetDatabaseLockState (DmOpenRef dbR, 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.

Result

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

Purpose

Return error code from last data manager call.

Prototype

Err DmGetLastErr (void)

Parameters

None.

Result

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:

DmFindDatabase	DmOpenDatabaseByTypeCreator
DmOpenDatabase	DmNewRecord
DmQueryRecord	DmGetRecord
DmQueryNextInCategory	DmPositionInCategory
DmSeekRecordInCategory	DmResizeRecord
DmGetResource	DmGet1Resource
DmNewResource	DmGetResourceIndex
DmNewHandle	DmOpenDBNoOverlay
DmResizeResource

DmGetNextDatabaseByTypeCreator

Purpose

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

Prototype

Err DmGetNextDatabaseByTypeCreator (Boolean newSearch, DmSearchStatePtr stateInfoP, UInt32 type, UInt32 creator, Boolean onlyLatestVers, 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.

Result

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 NULL as a wildcard operator for the type or creator parameter to conduct searches of wider scope. If the type parameter is NULL, this routine can be called successively to return all databases of the given creator. If the creator parameter is NULL, this routine can be called successively to return all databases of the given type. You can also pass NULL 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.

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,
    latestVer, &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 NULL for either the type or creator parameter (or both).
  

See Also

DmGetDatabase, DmFindDatabase, DmDatabaseInfo, DmOpenDatabaseByTypeCreator, DmDatabaseSize

DmGetRecord

Purpose

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

Prototype

MemHandle DmGetRecord (DmOpenRef dbP, UInt16 index)

Parameters

-> dbP

DmOpenRef to open database.

-> index

Which record to retrieve.

Result

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.

See Also

DmSearchRecord, DmFindRecordByID, DmRecordInfo, DmReleaseRecord, DmQueryRecord

DmGetResource

Purpose

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

Prototype

MemHandle DmGetResource (DmResType type, DmResID resID)

Parameters

-> type

The resource type.

->resID

The resource ID.

Result

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

Purpose

Return a handle to a resource by index.

Prototype

MemHandle DmGetResourceIndex (DmOpenRef dbP, UInt16 index)

Parameters

-> dbP

Access pointer to open database.

-> index

Index of resource to lock down.

Result

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

Purpose

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

Prototype

MemHandle DmGet1Resource (DmResType type, DmResID resID)

Parameters

-> type

The resource type.

-> resID

The resource ID.

Result

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

Purpose

Sort records in a database.

Prototype

Err DmInsertionSort (DmOpenRef dbR, DmComparF *compar, Int16 other)

Parameters

-> dbR

Database access pointer.

-> compar

Comparison function. See DmComparF.

-> other

Any value the application wants to pass to the comparison function.

Result

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

• dmErrReadOnly
  
  
• dmErrNotRecordDB
  

  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.

See Also

DmQuickSort

DmMoveCategory

Purpose

Move all records in a category to another category.

Prototype

Err DmMoveCategory (DmOpenRef dbP, UInt16 toCategory, UInt16 fromCategory, Boolean dirty)

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.

Result

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);

DmMoveRecord

Purpose

Move a record from one index to another.

Prototype

Err DmMoveRecord (DmOpenRef dbP, UInt16 from, UInt16 to)

Parameters

-> dbP

DmOpenRef to open database.

-> from

Index of record to move.

-> to

Where to move the record.

Result

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

• dmErrReadOnly
  
  
• dmErrIndexOutOfRange
  
  
• dmErrNotRecordDB
  
  
• dmErrMemError
  
  
• memErrInvalidParam
  
  
• memErrChunkLocked
  

  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.

DmNewHandle

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.

Prototype

MemHandle DmNewHandle (DmOpenRef dbP, UInt32 size)

Parameters

-> dbP

DmOpenRef to open database.

-> size

Size of new handle.

Result

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.

DmNewRecord

Purpose

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

Prototype

MemHandle DmNewRecord (DmOpenRef dbP, UInt16* atP, UInt32 size)

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.

Result

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.

See Also

DmAttachRecord, DmRemoveRecord, DmDeleteRecord

DmNewResource

Purpose

Allocate and add a new resource to a resource database.

Prototype

MemHandle DmNewResource (DmOpenRef dbP, DmResType resType, DmResID resID, UInt32 size)

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.

Result

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

Purpose

Return DmOpenRef to next open database for the current task.

Prototype

DmOpenRef DmNextOpenDatabase (DmOpenRef currentP)

Parameters

-> currentP

Current database access pointer or NULL.

Result

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

Purpose

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

Prototype

DmOpenRef DmNextOpenResDatabase (DmOpenRef dbP)

Parameters

-> dbP

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

Result

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

Purpose

Determine how many databases reside on a memory card.

Prototype

UInt16 DmNumDatabases (UInt16 cardNo)

Parameters

-> cardNo

Number of the card to check.

Result

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.

See Also

DmGetDatabase

DmNumRecords

Purpose

Return the number of records in a database.

Prototype

UInt16 DmNumRecords (DmOpenRef dbP)

Parameters

-> dbP

DmOpenRef to open database.

Result

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

Purpose

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

Prototype

UInt16 DmNumRecordsInCategory (DmOpenRef dbP, UInt16 category)

Parameters

-> dbP

DmOpenRef to open database.

-> category

Category index.

Result

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);

See Also

DmNumRecords, DmQueryNextInCategory, DmPositionInCategory, DmSeekRecordInCategory, DmMoveCategory

DmNumResources

Purpose

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

Prototype

UInt16 DmNumResources (DmOpenRef dbP)

Parameters

-> dbP

DmOpenRef to open database.

Result

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

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.

Prototype

DmOpenRef DmOpenDatabase (UInt16 cardNo, LocalID dbID, UInt16 mode)

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").

Result

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.

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.

See Also

DmCloseDatabase, DmCreateDatabase, DmFindDatabase, DmOpenDatabaseByTypeCreator, DmDeleteDatabase, DmOpenDBNoOverlay

DmOpenDatabaseByTypeCreator

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.

Prototype

DmOpenRef DmOpenDatabaseByTypeCreator (UInt32 type, UInt32 creator, UInt16 mode)

Parameters

-> type

Type of database.

-> creator

Creator of database.

-> mode

Which mode to open database in (see "Open Mode Constants").

Result

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.

See Also

DmCreateDatabase, DmOpenDatabase, DmOpenDatabaseInfo, DmCloseDatabase, DmOpenDBNoOverlay

DmOpenDatabaseInfo

Purpose

Retrieve information about an open database.

Prototype

Err DmOpenDatabaseInfo (DmOpenRef dbP, 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.

Result

Returns errNone if no error.

See Also

DmDatabaseInfo

DmOpenDBNoOverlay

Purpose

Open a database and return a reference to it.

Prototype

DmOpenRef DmOpenDBNoOverlay (UInt16 cardNo, LocalID dbID, UInt16 mode)

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").

Result

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.

See Also

DmCloseDatabase, DmCreateDatabase, DmFindDatabase, DmOpenDatabaseByTypeCreator, DmDeleteDatabase, DmOpenDatabase

DmPositionInCategory

Purpose

Return a position of a record within the specified category.

Prototype

UInt16 DmPositionInCategory (DmOpenRef dbP, UInt16 index, UInt16 category)

Parameters

-> dbP

DmOpenRef to open database.

-> index

Index of the record.

-> category

Index of category to search.

Result

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.

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.

See Also

DmQueryNextInCategory, DmSeekRecordInCategory, DmMoveCategory

DmQueryNextInCategory

Purpose

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

Prototype

MemHandle DmQueryNextInCategory (DmOpenRef dbP, UInt16* indexP, UInt16 category)

Parameters

-> dbP

DmOpenRef to open database.

-> indexP

Index of a known record (often retrieved with DmPositionInCategory).

-> category

Index of category to query, or dmAllCategories to find the next record in any category.

Result

Returns a handle to the record following a known 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.

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);

See Also

DmNumRecordsInCategory, DmPositionInCategory, DmSeekRecordInCategory

DmQueryRecord

Purpose

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

Prototype

MemHandle DmQueryRecord (DmOpenRef dbP, UInt16 index)

Parameters

-> dbP

DmOpenRef to open database.

-> index

Which record to retrieve.

Result

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.

DmQuickSort

Purpose

Sort records in a database.

Prototype

Err DmQuickSort (DmOpenRef dbP, DmComparF *compar, Int16 other)

Parameters

-> dbP

Database access pointer.

-> compar

Comparison function. See DmComparF.

-> other

Any value the application wants to pass to the comparison function.

Result

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

• dmErrReadOnly
  
  
• dmErrNotRecordDB
  

  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).

See Also

DmFindSortPositionV10, DmInsertionSort

DmRecordInfo

Purpose

Retrieve the record information as stored in the database header.

Prototype

Err DmRecordInfo (DmOpenRef dbP, UInt16 index, 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.

Result

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.

See Also

DmNumRecords, DmSetRecordInfo, DmQueryNextInCategory

DmReleaseRecord

Purpose

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

Prototype

Err DmReleaseRecord (DmOpenRef dbP, UInt16 index, Boolean dirty)

Parameters

-> dbP

DmOpenRef to open database.

-> index

The record to unlock.

-> dirty

If true, set the dirty bit.

Result

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.

See Also

DmGetRecord

DmReleaseResource

Purpose

Release a resource acquired with DmGetResource.

Prototype

Err DmReleaseResource (MemHandle resourceH)

Parameters

-> resourceH

Handle to resource.

Result

Returns errNone if no error.

Comments

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

See Also

DmGet1Resource, DmGetResource

DmRemoveRecord

Purpose

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

Prototype

Err DmRemoveRecord (DmOpenRef dbP, UInt16 index)

Parameters

-> dbP

DmOpenRef to open database.

-> index

Index of the record to remove.

Result

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

• dmErrReadOnly
  
  
• dmErrIndexOutOfRange
  
  
• dmErrNotRecordDB
  
  
• memErrChunkLocked
  
  
• memErrInvalidParam
  

  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.

See Also

DmDetachRecord, DmDeleteRecord, DmArchiveRecord, DmNewRecord

DmRemoveResource

Purpose

Delete a resource from a resource database.

Prototype

Err DmRemoveResource (DmOpenRef dbP, UInt16 index)

Parameters

-> dbP

DmOpenRef to open database.

-> index

Index of resource to delete.

Result

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

• dmErrCorruptDatabase
  
  
• dmErrIndexOutOfRange
  
  
• dmErrReadOnly
  
  
• memErrChunkLocked
  
  
• memErrInvalidParam
  
  
• memErrNotEnoughSpace
  

  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

Purpose

Remove all secret records.

Prototype

Err DmRemoveSecretRecords (DmOpenRef dbP)

Parameters

-> dbP

DmOpenRef to open database.

Result

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

• dmErrReadOnly
  
  
• dmErrNotRecordDB
  

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

See Also

DmRemoveRecord, DmRecordInfo, DmSetRecordInfo

DmResizeRecord

Purpose

Resize a record by index.

Prototype

MemHandle DmResizeRecord (DmOpenRef dbP, UInt16 index, UInt32 newSize)

Parameters

-> dbP

DmOpenRef to open database.

-> index

Which record to retrieve.

-> newSize

New size of record.

Result

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.

DmResizeResource

Purpose

Resize a resource and return the new handle.

Prototype

MemHandle DmResizeResource (MemHandle resourceH, UInt32 newSize)

Parameters

-> resourceH

Handle to resource.

-> newSize

Desired new size of resource.

Result

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

Purpose

Retrieve information on a given resource.

Prototype

Err DmResourceInfo (DmOpenRef dbP, UInt16 index, 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.

Result

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

Purpose

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

Prototype

UInt16 DmSearchRecord (MemHandle recH, DmOpenRef* dbPP)

Parameters

-> recH

Record handle.

<- dbPP

The database that contains the record recH.

Result

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

Purpose

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

Prototype

UInt16 DmSearchResource (DmResType resType, DmResID resID, MemHandle resH, 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.

Result

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

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.)

Prototype

Err DmSeekRecordInCategory (DmOpenRef dbP, UInt16* indexP, Int16 offset, Int16 direction, UInt16 category)

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.

Result

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.

See Also

DmNumRecordsInCategory, DmQueryNextInCategory, DmPositionInCategory, DmMoveCategory

DmSet

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.

Prototype

Err DmSet (void* recordP, UInt32 offset, UInt32 bytes, UInt8 value)

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.

Result

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

Purpose

Set information about a database.

Prototype

Err DmSetDatabaseInfo (UInt16 cardNo, LocalID dbID, const Char* 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 32-byte character array for new name, or NULL.

-> 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.

Result

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

• dmErrInvalidDatabaseName
  
  
• dmErrAlreadyExists
  
  
• dmErrInvalidParam
  

Comments

When this call changes appInfoID or sortInfoID, the old chunk ID (if any) is marked as an orphan chunk 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

Purpose

Set record information stored in the database header.

Prototype

Err DmSetRecordInfo (DmOpenRef dbP, UInt16 index, 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.

Result

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

• dmErrReadOnly
  
  
• dmErrNotRecordDB
  
  
• dmErrIndexOutOfRange
  

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

Comments

Sets information about a record.

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.

See Also

DmNumRecords, DmRecordInfo