< Home < Developers < Development Support < Documentation

## 28 Data and Resource Manager

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 28 Data and Resource Manager Data Manager Data Structures DmOpenRef DmResID DmResType SortRecordInfoType Data Manager Constants Category Constants Record Attribute Constants Database Attribute Constants Error Codes Open Mode Constants Data Manager Functions DmArchiveRecord DmAttachRecord DmAttachResource DmCloseDatabase DmCreateDatabase DmCreateDatabaseFromImage DmDatabaseInfo DmDatabaseProtect DmDatabaseSize DmDeleteCategory DmDeleteDatabase DmDeleteRecord DmDetachRecord DmDetachResource DmFindDatabase DmFindRecordByID DmFindResource DmFindResourceType DmFindSortPosition DmFindSortPositionV10 DmGetAppInfoID DmGetDatabase DmGetDatabaseLockState DmGetLastErr DmGetNextDatabaseByTypeCreator DmGetRecord DmGetResource DmGetResourceIndex DmGet1Resource DmInsertionSort DmMoveCategory DmMoveRecord DmNewHandle DmNewRecord DmNewResource DmNextOpenDatabase DmNextOpenResDatabase DmNumDatabases DmNumRecords DmNumRecordsInCategory DmNumResources DmOpenDatabase DmOpenDatabaseByTypeCreator DmOpenDatabaseInfo DmOpenDBNoOverlay DmPositionInCategory DmQueryNextInCategory DmQueryRecord DmQuickSort DmRecordInfo DmReleaseRecord DmReleaseResource DmRemoveRecord DmRemoveResource DmRemoveSecretRecords DmResizeRecord DmResizeResource DmResourceInfo DmSearchRecord DmSearchResource DmSeekRecordInCategory DmSet DmSetDatabaseInfo DmSetRecordInfo DmSetResourceInfo DmStrCopy DmWrite DmWriteCheck Application-Defined Functions DmComparF |  |  |  | This chapter describes the data manager and the resource manager API declared in the header file DataMgr.h. It discusses the following topics: 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 #####
attributes | The record's attributes. See "Record Attribute Constants."
uniqueID | The unique identifier for the record.
## 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.
#####
-> 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. 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 #####
-> 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 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.
#####
-> newRecordInfo | Sort information about the new record. See SortRecordInfoType.
#####
-> compar | Pointer to comparison function. See DmComparF.
#####
-> other | Any value the application wants to pass to the comparison function. This parameter is often used to indicate a sort direction (ascending or descending).
#### 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: #####
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. WARNING! Don't create or delete a database while using DmGetNextDatabaseByTypeCreator to iterate through the existing databases. This could cause databases to be skipped, or it could result in a given database being returned more than once. #### Compatibility In Palm OS version 3.1 and higher, if onlyLatestVers is true, you only receive one matching database for each type/creator pair. In version 3.0 and earlier, you could receive multiple matching databases if onlyLatestVers was true. Note that the behavior is different only when you have specified a value for both type and creator and onlyLatestVers is true. For example, suppose your application maintains three databases that all have the same type, creator, and version number and you write this code to process them in some way:
    DmSearchStateType state;
    Boolean latestVer;
    UInt16 card;
    LocalID currentDB = 0;

    theErr = DmGetNextDatabaseByTypeCreator(true,
      &state, myType, myCreator, latestVer, &card,
      &currentDB);
    while (!theErr && currentDB) {
      /* do something with currentDB */
      /* now get the next DB */
      theErr = DmGetNextDatabaseByTypeCreator(
        false, &state, myType, myCreator,
      vlatestVer, &card, &currentDB);
    }
If latestVer is false, then your code will work the same on all versions of Palm OS and will return all three databases whose type and creator match those specified. If latestVer is true, this code returns all three databases on Palm OS version 3.0 and earlier, but only returns one database on version 3.1 and higher. (Exactly which database it returns is unspecified.) If you expect multiple databases to match your search criteria, make sure you call DmGetNextDatabaseByTypeCreator in one of the following ways to ensure that your code operates the same on all Palm OS versions: Set onlyLatestVers to false if you specify both a type and creator. Specify 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 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.
#####
-> 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. 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.
#####
-> 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. 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 #####
-> 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). 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.
#####
-> compar | Comparison function. See DmComparF.
#####
-> other | Any value the application wants to pass to the comparison function. This parameter is often used to indicate a sort direction (ascending or descending).
#### 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, 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.
#####
-> 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 orphaned chunk1 and the new chunk ID is unorphaned. Consequently, you shouldn't replace an existing appInfoID or sortInfoID if that chunk has already been attached to another database. Call this routine to set any or all information about a database except for the card number and database ID. This routine sets the new value for any non-NULL parameter. #### See Also DmDatabaseInfo, DmOpenDatabaseInfo, DmFindDatabase, DmGetNextDatabaseByTypeCreator, TimDateTimeToSeconds ## DmSetRecordInfo #### 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. 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. 1. An "orphaned chunk" is one that is allocated in the storage heap, but to which nothing refers. If the orphaned chunk is not put into a database as a record, an appInfo block, or the like, and if the application doesn't keep track of it-in a global variable, perhaps-it could get lost. If the application doesn't get around to freeing the chunk before it quits or crashes, or before the device is reset, that storage will be forever unusable: the user can't delete it since the user only deletes databases. During a soft reset, the OS walks through the storage heap and frees any orphaned chunks that it finds. Since most users reset only rarely, however, you shouldn't rely on this happening. |