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, vol. I.
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 or equal to 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, 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

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. |
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® Shortcuts database, 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

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 PalmTM 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 PoweredTM 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.
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 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.
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 (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.
DmDeleteDatabase

Purpose
Delete a database and all its records.
Prototype
Err DmDeleteDatabase (UInt16 cardNo, LocalID dbID)
Parameters
-> cardNo | Card number the database resides on. |
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. 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

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
-> 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. |
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
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.
Prototype
UInt16 DmFindSortPosition (DmOpenRef dbP, void *newRecord, SortRecordInfoPtr newRecordInfo, 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. This parameter is often used to indicate a sort direction (ascending or descending). |
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. 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

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:
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.
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,
¤tDB);
while (!theErr && currentDB) {
/* do something with currentDB */
/* now get the next DB */
theErr = DmGetNextDatabaseByTypeCreator(
false, &state, myType, myCreator,
vlatestVer, &card, ¤tDB);
}
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. |
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 the resource whose handle you want. |
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. |
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. |
-> 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). |
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. |
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.
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.
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
-> creator | Creator of database. |
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. |
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). 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. |
Result
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.
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. |
-> 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). |
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
<- 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, UInt16 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. |
-> 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 orphaned 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. |
-> 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. 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.
See Also
DmNumRecords, DmRecordInfo
DmSetResourceInfo

Purpose
Set information on a given resource.
Prototype
Err DmSetResourceInfo (DmOpenRef dbP, UInt16 index, 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. |
Result
Returns errNone if no error, or one of the following if an error occurred:
dmErrIndexOutOfRange
dmErrReadOnly
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

Purpose
Copies a string to a record within a database that is open for writing.
Prototype
Err DmStrCopy (void *recordP, UInt32 offset, const Char *srcP)
Parameters
<-> recordP | Pointer to data record (chunk pointer). |
-> offset | Offset within record to start writing. |
-> srcP | Pointer to null-terminated string. |
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
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
DmWrite

Purpose
Copies a specified number of bytes to a record within a database that is open for writing.
Prototype
Err DmWrite (void *recordP, UInt32 offset, const void *srcP, UInt32 bytes)
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. |
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
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

Purpose
Check the parameters of a write operation to a data storage chunk before actually performing the write.
Prototype
Err DmWriteCheck (void *recordP, UInt32 offset, UInt32 bytes)
Parameters
-> recordP | Locked pointer to recordH. |
-> offset | Offset into record to start writing. |
-> bytes | Number of bytes to write. |
Result
Returns errNone if no error; returns dmErrNotValidRecord or dmErrWriteOutOfBounds if an error occurred.
Application-Defined Functions

DmComparF

Purpose
Compares two records in a database.
Prototype
typedef Int16 DmComparF (void *rec1, void *rec2, Int16 other, SortRecordInfoPtr rec1SortInfo, SortRecordInfoPtr rec2SortInfo, MemHandle appInfoH)
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. |
Result
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.
|