This chapter describes the Data Manager APIs. These APIs are those structures, constants, and functions that operate on extended and classic databases (collectively, the "non-schema" databases). This chapter is organized as follows:
Data Manager Structures and Types
Data Manager Constants
Data Manager Functions and Macros
Application-Defined Functions
The header file DataMgr.h
declares the API that this chapter describes.
For more information on Palm OS® databases, see Chapter 2, "Palm OS Databases."
Data Manager Structures and Types
CategoryID Typedef
Purpose
Container for a category's unique identifier.
Declared In
DataMgr.h
Prototype
typedef int32_t CategoryID
DatabaseID Typedef
Purpose
Container for a database's unique identifier.
Declared In
DataMgr.h
Prototype
typedef uint32_t DatabaseID
DmBackupRestoreStateType Struct
Purpose
Opaque container for the backup state, used to maintain state across multiple calls to DmBackupUpdate()
or DmRestoreUpdate()
.
Declared In
DataMgr.h
Prototype
typedef struct DmBackupRestoreStateTag { uint32_t info[12]; } DmBackupRestoreStateType
typedef DmBackupRestoreStateType *DmBackupRestoreStatePtr
Fields
Comments
Your application allocates a structure of this type and passes it to DmBackupInitialize()
(or DmRestoreInitialize()
) for initialization prior to serializing a database (or restoring a database that has been serialized). After passing it to DmBackupUpdate()
(DmRestoreUpdate()
), calling that function as many times as necessary, your application must pass it to DmBackupFinalize()
(DmRestoreFinalize()
) before releasing the storage occupied by the structure.
NOTE: The contents of this structure are opaque; your application should not attempt to directly manipulate the contents of this structure in any way.
DmDatabaseInfoType Struct
Purpose
Data structure used to return information about a database through a call to DmDatabaseInfo()
.
Declared In
DataMgr.h
Prototype
typedef struct DmDatabaseInfoTag { uint32_t size; char *pName; char *pDispName; uint16_t *pAttributes; uint16_t *pVersion; uint32_t *pType; uint32_t *pCreator; uint32_t *pCrDate; uint32_t *pModDate; uint32_t *pBckpDate; uint32_t *pModNum; MemHandle *pAppInfoHandle; MemHandle *pSortInfoHandle; uint16_t *pEncoding; } DmDatabaseInfoType
typedef DmDatabaseInfoType *DmDatabaseInfoPtr
Fields
-
size
- Size of this structure.
-
pName
- The database's name. This should be a pointer to 32-byte character array for this parameter, or
NULL
if you don't care about the name. -
pDispName
- (Schema databases only) The database's display name.
-
pAttributes
- The database's attribute flags. The section "Database Attributes" lists constants you can use to query the values returned in this parameter.
-
pVersion
- The application-specific version number. The default version number is 0.
-
pType
- The database's type, specified when it is created.
-
pCreator
- The database's creator, specified when it is created.
-
pCrDate
- The date the database was created, expressed as the number of seconds since the start of the Unix epoch.
-
pModDate
- The date the database was last modified, expressed as the number of seconds since the start of the Unix epoch.
-
pBckpDate
- The date the database was backed up, expressed as the number of seconds since the start of the Unix epoch.
-
pModNum
- The modification number, which is incremented every time a record in the database is added, modified, or deleted.
-
pAppInfoHandle
- (Non-schema databases only) Handle 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. -
pSortInfoHandle
- (Non-schema databases only) Handle of the database's sort table. This is an optional field in the database header.
-
pEncoding
- (Schema databases only) The database's encoding.
Comments
Prior to calling DmDatabaseInfo()
, initialize the fields of this structure to point to variables where DmDatabaseInfo()
will write the information. If you don't want to retrieve data corresponding to a given field, set that field to NULL
. See the comments section for DmGetNextDatabaseByTypeCreator()
for an example of how this structure is initialized and used.
The fields representing dates (pCrDate
, pModDate
, pBckpDate) contain the number of non-leap seconds since the start of the Unix epoch: 00:00:00 UTC on Jan 1, 1970. Note that this is different from the way dates are returned by PACE, and is different from the way they are returned by DmDatabaseInfoV50()
; PACE and DmDatabaseInfoV50()
return dates based upon the "Palm OS epoch": the number of seconds since the beginning of Jan 1, 1904, local time.
DmFindType Typedef
Purpose
Flags that indicate the type of database to be searched for when using DmFindDatabase()
, DmFindDatabaseByTypeCreator()
, or DmOpenIteratorByTypeCreator()
. These flags can be OR'd together to search for a combination of database types.
Declared In
DataMgr.h
Prototype
typedef uint32_t DmFindType
Constants
-
#define dmFindClassicDB ((DmFindType)0x00000004)
- Classic databases.
-
#define dmFindExtendedDB ((DmFindType)0x00000002)
- Extended databases.
-
#define dmFindSchemaDB ((DmFindType)0x00000001)
- Schema databases.
-
#define dmFindAllDB (dmFindSchemaDB | dmFindExtendedDB | dmFindClassicDB)
- A convenience value that can be used when searching for databases of any type.
See Also
Chapter 2, "Palm OS Databases,"
DmOpenModeType Typedef
Purpose
Type that holds the mode in which a database can be opened. You pass one or more of the associated constants as a parameter to DmOpenDatabase()
, DmOpenDatabaseByTypeCreator()
, or DmOpenDBNoOverlay()
. These constants are also used when working with schema databases using either DbOpenDatabase()
or DbOpenDatabaseByName()
.
Declared In
DataMgr.h
Prototype
typedef uint16_t DmOpenModeType;
Constants
-
#define dmModeExclusive ((DmOpenModeType)0x0008)
- While the database is open don't let anyone else open it. This value cannot be passed to
DbOpenDatabase()
andDbOpenDatabaseByName()
. -
#define dmModeReadOnly ((DmOpenModeType)0x0001)
- Open the database with read-only access. This value can be passed to
DbOpenDatabase()
andDbOpenDatabaseByName()
. -
#define dmModeReadWrite ((DmOpenModeType)0x0003)
- Open the database with read-write access. This value can be passed to
DbOpenDatabase()
andDbOpenDatabaseByName()
. UsedmModeWrite
when calling any of theDmOpen...
functions. -
#define dmModeShowSecret ((DmOpenModeType)0x0010)
- Show records marked private. This value can be passed to
DbOpenDatabase()
andDbOpenDatabaseByName()
. -
#define dmModeWrite ((DmOpenModeType)0x0002)
- Open the database with write-only access. This value cannot be passed to
DbOpenDatabase()
andDbOpenDatabaseByName()
; usedmModeReadWrite
when calling one of these functions.
DmOpenRef Struct
Purpose
Defines a pointer to an open database.
Declared In
DataMgr.h
Prototype
typedef struct _opaque *DmOpenRef
Fields
Comments
The database pointer is created and returned by DmOpenDatabase()
. It is used in any function that requires access to an open database.
DmResourceID Typedef
Purpose
Defines a resource identifier. You assign each resource an ID at creation time.
Declared In
DataMgr.h
Prototype
typedef uint16_t DmResourceID
Comments
Resource IDs greater than or equal to 10000 are reserved for system use.
DmResourceType Typedef
Purpose
Defines the type of a resource.
Declared In
DataMgr.h
Prototype
typedef uint32_t DmResourceType
Comments
The resource type is a four-character code such as 'Tbmp'
for bitmap resources.
DmSearchStateType Struct
Purpose
Opaque container for the search state, used to maintain state when iterating through databases that match a specified type and creator.
Declared In
DataMgr.h
Prototype
typedef struct { uint32_t info[8]; } DmSearchStateType
typedef DmSearchStateType *DmSearchStatePtr
Fields
Comments
Your application should allocate a DmSearchStateType
structure and pass it as the stateInfoP
parameter when iterating through databases with DmOpenIteratorByTypeCreator()
, DmGetNextDatabaseByTypeCreator()
, and DmCloseIteratorByTypeCreator()
; or when calling DmGetNextDatabaseByTypeCreatorV50()
. These functions store private information in this structure and use that information if the search is continued.
NOTE: The contents of this structure are opaque; your application should not attempt to directly manipulate the contents of this structure in any way.
DmSortRecordInfoType Struct
Purpose
Specifies information that can be used to sort a record.
Declared In
DataMgr.h
Prototype
typedef struct { uint8_t attributes; uint8_t uniqueID[3]; } DmSortRecordInfoType
typedef DmSortRecordInfoType *DmSortRecordInfoPtr
Fields
-
attributes
- The record's attributes. See "Non-Schema Database Record Attributes."
-
uniqueID
- The unique identifier for the record.
Comments
The database sorting functions (DmInsertionSort()
and DmQuickSort()
) pass this structure to your comparison callback function (of type DmCompareFunctionType()
), where you can use the information therein to help when comparing two records. To create this structure, you can call DmRecordInfoV50()
, which returns these values for a given record.
DmStorageInfoType Struct
Purpose
Returns storage heap memory usage information through a call to DmGetStorageInfo()
.
Declared In
DataMgr.h
Prototype
typedef struct DmStorageInfoTag { uint32_t size; uint32_t bytesTotal; uint32_t bytesNonSecureUsed; uint32_t bytesNonSecureFree; uint32_t bytesSecureUsed; uint32_t bytesSecureFree; uint32_t bytesFreePool; } DmStorageInfoType
typedef DmStorageInfoType *DmStorageInfoPtr
Fields
-
size
- Size of this structure.
-
bytesTotal
- Total amount of memory available for persistent storage.
-
bytesNonSecureUsed
- Amount of memory used in non-secure storage.
-
bytesNonSecureFree
- Amount of free memory in non-secure storage.
-
bytesSecureUsed
- Amount of memory used in secure storage.
-
bytesSecureFree
- Amount of free memory in secure storage.
-
bytesFreePool
- Amount of memory in the free pool, available for both secure and non-secure storage.
Data Manager Constants
Non-Schema Database Record Attributes
Purpose
These constants define the set of attributes that a non-schema database record can have. Use DmGetRecordAttr()
to obtain a database record's attributes.
Declared In
DataMgr.h
Constants
-
#define dmAllRecAttrs ( dmRecAttrDelete | dmRecAttrDirty | dmRecAttrBusy | dmRecAttrSecret )
- The complete set of record attributes.
-
#define dmRecAttrBusy 0x20
- The application has locked access to the record. A call to
DmGetRecord()
fails on a record that has this bit set. -
#define dmRecAttrDelete 0x80
- The record has been deleted.
-
#define dmRecAttrDirty 0x40
- The record has been modified since the last sync.
-
#define dmRecAttrSecret 0x10
- The record is private.
-
#define dmSysOnlyRecAttrs ( dmRecAttrBusy )
- Mask that identifies those attributes that only the system can change.
-
#define dmRecAttrCategoryMask ( (uint8_t) 0x0F )
- Mask that isolates the record's category.
Database Attributes
Purpose
Define the set of attributes that a database can have. These attributes apply to schema, extended, and classic databases.
Declared In
DataMgr.h
Constants
-
#define dmAllHdrAttrs (dmHdrAttrResDB | dmHdrAttrReadOnly | dmHdrAttrAppInfoDirty | dmHdrAttrBackup | dmHdrAttrOKToInstallNewer | dmHdrAttrResetAfterInstall | dmHdrAttrCopyPrevention | dmHdrAttrStream | dmHdrAttrHidden | dmHdrAttrLaunchableData | dmHdrAttrRecyclable | dmHdrAttrBundle | dmHdrAttrSchema | dmHdrAttrSecure | dmHdrAttrOpen)
- A mask used to specify all header attributes.
-
#define dmHdrAttrAppInfoDirty 0x0004
- The application info block is dirty (it has been modified since the last sync). This bit only applies to non-schema databases; schema databases don't have application info blocks.
-
#define dmHdrAttrBackup 0x0008
- The database should be backed up to the desktop computer if no application-specific conduit is available.
-
#define dmHdrAttrBundle 0x0800
- The database is bundled with its application during a beam, send, or copy operation. 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. (Note that overlay databases are automatically beamed with the application database. You do not need to set this bit in overlay databases.)
-
#define dmHdrAttrCopyPrevention 0x0040
- Prevents the database from being copied by methods such as IR beaming.
-
#define dmHdrAttrHidden 0x0100
- 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.
-
#define dmHdrAttrLaunchableData 0x0200
- This database contains data but it can be "launched" from the Launcher.
-
#define dmHdrAttrExtendedDB dmHdrAttrSecure
- If
dmHdrAttrSchema
is not set, the database is an extended database. Note that this bit serves a dual-purpose, depending upon thedmHdrAttrSchema
bit; if the database is a schema database (dmHdrAttrSchema
is set), this bit indicates whether or not the schema database is a secure database. See Chapter 2, "Palm OS Databases," for an explanation of the differences between the various database types. -
#define dmHdrAttrOKToInstallNewer 0x0010
- 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 2 Shortcuts databases, for example.
-
#define dmHdrAttrOpen 0x8000
- The database is open.
-
#define dmHdrAttrReadOnly 0x0002
- The database is a read-only database.
-
#define dmHdrAttrRecyclable 0x0400
- The database is recyclable. Recyclable databases are deleted when they are closed or upon a system reset.
-
#define dmHdrAttrResDB 0x0001
- The database is a resource database.
-
#define dmHdrAttrResetAfterInstall 0x0020
- The device must be reset after this database is installed. That is, the HotSync® application forces a reset after installing this database.
-
#define dmHdrAttrSchema 0x1000
- The database is a schema database. See Chapter 2, "Palm OS Databases," for an explanation of the differences between the various database types.
-
#define dmHdrAttrSecure 0x2000
- The database is a secure database.
-
#define dmHdrAttrStream 0x0080
- The database is a file stream.
-
#define dmSysOnlyHdrAttrs ( dmHdrAttrResDB | dmHdrAttrSchema | dmHdrAttrSecure | dmHdrAttrOpen )
- A mask specifying the attributes that only the system can change (open and resource database).
Miscellaneous Data Manager Constants
Purpose
Miscellaneous constants defined by the Data Manager.
Declared In
DataMgr.h
Constants
-
#define appInfoStringsRsc 'tAIS'
- Application Info strings resource type.
-
#define dmMaxRecordIndex ( (uint16_t) 0xFFFE )
- The highest record index that can be used with a classic database.
-
#define dmAllCategories ( (uint8_t) 0xFF )
- Category value that can be supplied to
DmNumRecordsInCategory()
andDmQueryNextInCategory()
to indicate all categories. -
#define dmCategoryLength 16
- The maximum length of a classic or extended database category name, in bytes, including the
NULL
terminator. -
#define dmDBNameLength 32
- The maximum length of a database name, in bytes, including the
NULL
terminator. -
#define dmDefaultRecordsID 0
- Records in a default database are copied with their unique ID seeds set to this value.
-
#define dmInvalidRecIndex ( (uint16_t) -1 )
- Resource index value returned by
DmFindResource()
when that function fails to find the specified resource. -
#define dmRecNumCategories 16
- The maximum number of categories that can be used with a classic or extended database.
-
#define dmRecordIDReservedRange 1
- Upper limit of the range of unique ID seed values reserved for use by the operating system in conjunction with classic and extended databases.
-
#define dmSearchWildcardID ((uint32_t)0)
- A "wild card" that matches databases of any type and/or creator when iterating through databases with
DmOpenIteratorByTypeCreator()
or searching for databases with eitherDmGetNextDatabaseByTypeCreator()
orDmGetNextDatabaseByTypeCreatorV50()
. -
#define dmSeekBackward -1
- Direction value supplied to
DmFindRecordByOffsetInCategory()
to indicate that the search should be performed from the specified position towards the beginning of the database. -
#define dmSeekForward 1
- Direction value supplied to
DmFindRecordByOffsetInCategory()
to indicate that the search should be performed from the specified position towards the end of the database. -
#define dmUnfiledCategory 0
- Category identifier for the Unfiled category.
-
#define dmUnusedRecordID 0
- A record ID value representing an illegal or unused record. A "real" record cannot use this value as its record identifier.
Data Manager Error Codes
Purpose
Error codes returned by the various Data Manager functions. These codes are returned by schema database functions as well as classic database functions.
Declared In
DataMgr.h
Constants
-
#define dmErrAccessDenied (dmErrorClass | 37)
- The database is a secure database and you don't have permission to edit it.
-
#define dmErrAlreadyExists (dmErrorClass | 25)
- Another database with the same name already exists.
-
#define dmErrAlreadyOpenForWrites (dmErrorClass | 22)
- The database is already open with write access.
-
#define dmErrBadOverlayDBName (dmErrorClass | 32)
- The length of the locale description or overlay database name is incorrect, or the locale description begins with an underscore ('_') character.
-
#define dmErrBaseRequiresOverlay (dmErrorClass | 33)
- The base probably requires an overlay, but the corresponding overlay cannot be located.
-
#define dmErrBufferNotLargeEnough (dmErrorClass | 42)
- While copying a table column value from a schema database, it was determined that the supplied buffer wasn't large enough to contain the column value.
-
#define dmErrBuiltInProperty (dmErrorClass | 58)
- The schema database column property you are trying to alter is a built-in property; it cannot be changed or removed.
-
#define dmErrCantFind (dmErrorClass | 7)
- The specified database can't be found.
-
#define dmErrCantOpen (dmErrorClass | 6)
- The database cannot be opened.
-
#define dmErrCategoryLimitReached (dmErrorClass | 74)
- The schema database row cannot be made a member of the specified category because it is already a member of the maximum number of allowable categories.
-
#define dmErrColumnDefinitionsLocked (dmErrorClass | 76)
- The schema database table's column definitions are locked.
-
#define dmErrColumnIDAlreadyExists (dmErrorClass | 46)
- The specified schema database table already contains a column with the specified ID.
-
#define dmErrColumnIndexOutOfRange (dmErrorClass | 43)
- The supplied column index exceeds the number of columns in the schema database table.
-
#define dmErrColumnNameAlreadyExists (dmErrorClass | 70)
- The specified schema database table already contains a column with the specified name.
-
#define dmErrColumnPropertiesLocked (dmErrorClass | 75)
- The specified column property is locked.
-
#define dmErrCorruptDatabase (dmErrorClass | 9)
- The database is corrupted.
-
#define dmErrDatabaseNotProtected (dmErrorClass | 28)
-
DmDatabaseProtectV50()
failed to protect the specified database. -
#define dmErrDatabaseOpen (dmErrorClass | 5)
- The function cannot be performed on an open database, and the database is open.
-
#define dmErrDatabaseProtected (dmErrorClass | 27)
- The database is marked as protected.
-
#define dmErrDeviceLocked (dmErrorClass | 59)
-
#define dmErrEncryptionFailure (dmErrorClass | 54)
-
#define dmErrIndexOutOfRange (dmErrorClass | 2)
- The specified index is out of range.
-
#define dmErrInvalidCategory (dmErrorClass | 18)
- At least one of the supplied category IDs is not a valid schema database category.
-
#define dmErrInvalidColSpec (dmErrorClass | 40)
- At least one of the specified schema database table column attributes is not a valid column attribute.
-
#define dmErrInvalidColType (dmErrorClass | 41)
- The specified schema database table column type is not a valid column type.
-
#define dmErrInvalidColumnID (dmErrorClass | 44)
- One or more of the specified column IDs doesn't correspond to a column in the specified schema database table.
-
#define dmErrInvalidColumnName (dmErrorClass | 79)
- The supplied column name doesn't correspond to a column within the schema database table.
-
#define dmErrInvalidDatabaseName (dmErrorClass | 26)
- The name you've specified for the database is invalid.
-
#define dmErrInvalidID (dmErrorClass | 30)
- The schema database row ID is invalid.
-
#define dmErrInvalidIndex (dmErrorClass | 29)
- The row or sort index value exceeds the number of rows or sort indices defined for the schema database table.
-
#define dmErrInvalidTableName (dmErrorClass | 78)
- The supplied table name doesn't correspond to a table in the schema database.
-
#define dmErrInvalidOperation (dmErrorClass | 60)
- The requested schema database operation is not valid.
-
#define dmErrInvalidParam (dmErrorClass | 3)
- The function received an invalid parameter.
-
#define dmErrInvalidPrimaryKey (dmErrorClass | 66)
- Not currently used.
-
#define dmErrInvalidPropID (dmErrorClass | 56)
- The specified schema database table column doesn't have a property with the specified property ID.
-
#define dmErrInvalidSchemaDefn (dmErrorClass | 38)
- You are creating a schema database or adding a table to an existing schema database and the supplied
DbTableDefinitionType
structure defining the new table is invalid. -
#define dmErrInvalidSizeSpec (dmErrorClass | 51)
- You are creating a schema database or adding a table to an existing schema database and one of the table's vector column sizes is zero.
-
#define dmErrInvalidSortDefn (dmErrorClass | 71)
- You are adding a sort index to a schema database that is incorrectly specified or you are attempting to remove a sort index that isn't defined for the database.
-
#define dmErrInvalidSortIndex (dmErrorClass | 65)
- You are opening a schema database cursor and one of the specified sort IDs isn't defined for the specified database table.
-
#define dmErrInvalidVectorType (dmErrorClass | 50)
- You adding a vector column to an existing schema database—either explicitly or during the creation of a new schema database—but the specified column type isn't appropriate for a vector column.
-
#define dmErrMemError (dmErrorClass | 1)
- A memory error occurred.
-
#define dmErrNoColumnData (dmErrorClass | 48)
- Your request for the value of one or more schema database table columns cannot be fulfilled because the column contains no data.
-
#define dmErrNoCustomProperties (dmErrorClass | 57)
- The schema database contains no custom properties.
-
#define dmErrNoData (dmErrorClass | 53)
- The specified schema database table has no columns defined.
-
#define dmErrNoMoreData (dmErrorClass | 72)
- The backup operation is complete. See
DmBackupUpdate()
for a detailed explanation and example of how this error code is used. -
#define dmErrNoOpenDatabase (dmErrorClass | 17)
- The function is to search all open databases, but there are none.
-
#define dmErrNotRecordDB (dmErrorClass | 12)
- You've attempted to perform a record function on a resource database.
-
#define dmErrNotResourceDB (dmErrorClass | 13)
- You've attempted to perform a Resource Manager operation on a record database.
-
#define dmErrNotSchemaDatabase (dmErrorClass | 35)
- The specified database is not a schema database.
-
#define dmErrNotSecureDatabase (dmErrorClass | 36)
- The specified database is not a secure schema database.
-
#define dmErrNotValidRecord (dmErrorClass | 19)
- The record handle is invalid.
-
#define dmErrNoUserPassword (dmErrorClass | 68)
- The Authorization Manager doesn't have a user password on file.
-
#define dmErrOneOrMoreFailed (dmErrorClass | 62)
- At least one of the schema database table's column definitions could not be retrieved.
-
#define dmErrOpenedByAnotherTask (dmErrorClass | 23)
- You've attempted to open a database that another task already has open.
-
#define dmErrOperationAborted (dmErrorClass | 73)
- The variables bound to a schema database cursor couldn't be written to the database, or a database backup or restore operation was aborted.
-
#define dmErrReadOnly (dmErrorClass | 4)
- You've attempted to write to or modify a database that is open in read-only mode.
-
#define dmErrReadOutOfBounds (dmErrorClass | 49)
- A schema database table vector column is being read in which the specified offset exceeds the bounds of the column.
-
#define dmErrRecordArchived (dmErrorClass | 11)
- The function requires that the record not be archived, but it is.
-
#define dmErrRecordBusy (dmErrorClass | 15)
- The function requires that the record not be busy, but it is.
-
#define dmErrRecordDeleted (dmErrorClass | 10)
- The record has been deleted.
-
#define dmErrRecordInWrongCard (dmErrorClass | 8)
- You've attempted to attach a record to a database when the record and database reside on different memory cards.
-
#define dmErrTableNotEmpty (dmErrorClass | 61)
- An attempt to remove a schema database table failed because the table isn't empty.
-
#define dmErrResourceNotFound (dmErrorClass | 16)
- The resource can't be found.
-
#define dmErrROMBased (dmErrorClass | 14)
- You've attempted to delete or modify a ROM-based database.
-
#define dmErrSchemaBase (dmErrorClass | 34)
- Not an actual error code: this value serves to mark the beginning of the set of error codes created specifically for schema databases.
-
#define dmErrSchemaIndexOutOfRange (dmErrorClass | 47)
- The supplied table index exceeds the number of tables in the schema database.
-
#define dmErrTableNameAlreadyExists (dmErrorClass | 69)
- The schema database to which you are attempting to add a new table already contains a table with the supplied name, or, during the creation of a new schema database, you specified the same table name more than once.
-
#define dmErrSchemaNotFound (dmErrorClass | 55)
- Not currently used.
-
#define dmErrSeekFailed (dmErrorClass | 21)
- The operation of seeking the next record in the category failed.
-
#define dmErrSortDisabled (dmErrorClass | 67)
- Not currently used.
-
#define dmErrSQLParseError (dmErrorClass | 78)
- The SQL used to specify the schema database sort index is incorrectly formatted.
-
#define dmErrUniqueIDNotFound (dmErrorClass | 24)
- A record with the specified unique ID can't be found.
-
#define dmErrUnknownLocale (dmErrorClass | 31)
- The specified locale is unknown to the operating system.
-
#define dmErrCursorBOF (dmErrorClass | 63)
- The schema database cursor position—either the current position or the one specified—is located before the first row in the cursor.
-
#define dmErrCursorEOF (dmErrorClass | 64)
- The schema database cursor position—either the current position or the one specified—is located after the last row in the cursor.
-
#define dmErrWriteOutOfBounds (dmErrorClass | 20)
- A write operation exceeded the bounds of the record.
Data Manager Functions and Macros
DmArchiveRecord Function
Purpose
Mark a record as archived by leaving the record's chunk intact and setting the delete bit for the next HotSync operation.
Declared In
DataMgr.h
Prototype
status_t DmArchiveRecord ( DmOpenRefdbRef
, uint16_tindex
)
Parameters
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
dmErrIndexOutOfRange
- The specified index is out of range.
-
dmErrRecordArchived
- The function requires that the record not be archived, but it is.
-
dmErrRecordDeleted
- The record has been deleted.
-
memErrInvalidParam
- A memory error occurred.
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 record ID is preserved. This way, the next time the user synchronizes with the desktop system, the conduit can save the record data on the desktop before it permanently removes the record entry and data from the Palm Powered™ device.
Based on the assumption that a call to DmArchiveRecord()
indicates that you are finished with the record and aren't going to refer to it again, this function sets the chunk's lock count to zero.
See Also
DmRemoveRecord()
, DmDetachRecord()
, DmNewRecord()
, DmDeleteRecord()
DmAttachRecord Function
Purpose
Attach an existing chunk ID handle to a database as a record.
Declared In
DataMgr.h
Prototype
status_t DmAttachRecord ( DmOpenRefdbRef
, uint16_t*pIndex
, MemHandlehNewRecord
, MemHandle*hReplacedRecord
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
↔ pIndex
- 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. -
→ hNewRecord
- Handle of the new record.
-
↔ hReplacedRecord
- If non-
NULL
upon entry, indicates that the record at*
pIndex
should be replaced. Upon return, contains the handle to the replaced record.
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrMemError
- A memory error occurred.
-
memErrChunkLocked
- The associated memory chunk is locked.
-
memErrInvalidParam
- A memory error occurred.
-
memErrNotEnoughSpace
- A memory error occurred.
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
dmErrNotRecordDB
- You've attempted to perform a record function on a resource database.
-
dmErrRecordInWrongCard
- You've attempted to attach a record to a database when the record and database reside on different memory cards.
-
dmErrIndexOutOfRange
- The specified index is out of range.
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 function makes that chunk a new record in a database and sets the dirty bit. The parameter pIndex
points to an index variable. If hReplacedRecord
is NULL
, the new record is inserted at index *pIndex
and all record indices that follow are shifted down. If *pIndex
is greater than the number of records currently in the database, the new record hNewRecord
is appended to the end and its index is returned in *pIndex
. If hReplacedRecord
is not NULL
, the new record replaces an existing record at index *pIndex
and the handle of the old record is returned in *hReplacedRecord
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
DmRemoveRecord()
, DmDetachRecord()
, DmNewRecord()
, DmDeleteRecord()
DmAttachResource Function
Purpose
Attach an existing chunk ID to a resource database as a new resource.
Declared In
DataMgr.h
Prototype
status_t DmAttachResource ( DmOpenRefdbRef
, MemHandlehNewRes
, DmResourceTyperesType
, DmResourceIDresID
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ hNewRes
- Handle of new resource's data.
-
→ resType
- Type of the new resource.
-
→ resID
- ID of the new resource.
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrMemError
- A memory error occurred.
-
memErrChunkLocked
- The associated memory chunk is locked.
-
memErrInvalidParam
- A memory error occurred.
-
memErrNotEnoughSpace
- A memory error occurred.
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
dmErrRecordInWrongCard
- You've attempted to attach a record to a database when the record and database reside on different memory cards.
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 function 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()
DmBackupFinalize Function
Purpose
Complete or abort an on-going database backup operation.
Declared In
DataMgr.h
Prototype
status_t DmBackupFinalize ( DmBackupRestoreStatePtrpState
, BooleanfAbort
)
Parameters
-
→ pState
- Pointer to a
DmBackupRestoreStateType
structure allocated by the caller and initialized withDmBackupInitialize()
. -
→ fAbort
- Set to
true
to abort an on-going backup operation, orfalse
to clean up after a successful backup.
Returns
Returns errNone
if the database image was successfully created, dmErrOperationAborted
if the backup operation was cancelled, or one of the following errors otherwise:
-
dmErrInvalidParam
- One of the parameters is invalid or corrupt.
-
dmErrMemError
- A memory error occurred which prevented the backup operation from completing.
Comments
This function allows the Data Manager to perform a final clean up of the internal structures it allocated for the operation. Applications should always call this function after having started a backup operation, whether or not the backup completed successfully. See DmBackupUpdate()
for sample code illustrating this function's use.
The backup operation can be used with schema, extended, or classic databases.
See Also
DmBackupInitialize()
, DmRestoreFinalize()
DmBackupInitialize Function
Purpose
Initialize the Data Manager prior to starting a backup operation on the specified database.
Declared In
DataMgr.h
Prototype
status_t DmBackupInitialize ( DmBackupRestoreStatePtrpState
, DatabaseIDdbID
)
Parameters
-
↔ pState
- Pointer to a
DmBackupRestoreStateType
structure allocated by the caller. -
→ dbID
- Database ID of the database to be backed up.
Returns
Returns errNone
if the structure was successfully initialized, or one of the following if an error occurred:
-
dmErrCantFind
- The specified database doesn't exist.
-
dmErrDatabaseOpen
- The function cannot be performed on an open database, and the database is open.
-
dmErrAccessDenied
- The caller was not authorized to perform a backup operation for the specified database. This can be returned if the specified database is a secure schema database.
-
dmErrInvalidParam
- One of the parameters is invalid.
-
dmErrMemError
- A memory error occurred.
Comments
Use DmBackupInitialize()
to start a database backup operation. See DmBackupUpdate()
for sample code illustrating this function's use.
The backup operation can be used with schema, extended, or classic databases.
IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.
See Also
DmBackupFinalize()
, DmRestoreInitialize()
DmBackupUpdate Function
Purpose
Stream a database into its corresponding image within the specified buffer.
Declared In
DataMgr.h
Prototype
status_t DmBackupUpdate ( DmBackupRestoreStatePtrpState
, MemPtrpBuffer
, uint32_t*pSize
)
Parameters
-
→ pState
- Pointer to a
DmBackupRestoreStateType
structure allocated by the caller and initialized withDmBackupInitialize()
. -
→ pBuffer
- Pointer to a buffer to hold the backed-up database image.
-
↔ pSize
- Before calling, set this variable to the size of the
pBuffer
data buffer. Upon return, it contains the actual number of bytes written topBuffer
.
Returns
Returns errNone
if the operation was successful, dmErrNoMoreData
if the backup operation is complete, or one of the following if an error occurred:
-
dmErrInvalidParam
- One of the parameters is invalid or corrupt.
-
dmErrMemError
- A memory error occurred which prevented the backup operation from completing.
Comments
Use DmBackupUpdate()
, along with DmBackupInitialize()
and DmBackupFinalize()
, to get the serial image of a database.
You may need to call DmBackupUpdate()
several times in order to get the complete image of the specified database. Call DmBackupUpdate()
as many times as required and as long as it returns errNone
, until it finally returns dmErrNoMoreData
.
When DmBackupUpdate()
returns an error code other than errNone
or dmErrNoMoreData
, the operation has been aborted due to a fatal error. You must still call DmBackupFinalize()
in order to let the Data Manager perform its final clean up of the internal structures it allocated for the operation.
The backup operation can be used with schema, extended, or classic databases.
Example
The following code shows how to use the DmBackup...()
functions to send an image of a database to a fictitious serial channel.
status_t error; DmBackupRestoreStateType backupState; char buffer[BUFFER_SIZE]; uint32_t size; Boolean fAbort; Boolean fDone; error = DmBackupInitialize(&backupState, dbID); if (error == errNone){ do { // Reset the size value with the buffer size for each // loop as this variable gets updated with the actual // number of bytes written to the buffer after each // call to DmBackupDatabase. size = sizeof(buffer); error = DmBackupUpdate(&backupState, &buffer, &size); fDone = (error == dmErrNoMoreData); if ((error == errNone) || fDone){ // Stream the database image data chunk we got back // out to some I/O channel... error = SendDatabaseImageData(&buffer, size); } // Abort the operation if we got back an error or if // the user decided to cancel the operation... fAbort = (error != errNone) || DidUserCancel(); } while(!fDone && !fAbort); // Always call DmBackupFinalize to complete the backup // operation, whether or not it completed successfully error = DmBackupFinalize(&backupState, fAbort); } if (error == errNone){ // The backup operation completed successfully... } else { if (error == dmErrOperationAborted){ // The user aborted the operation } else { // Some other fatal error occurred... } }
See Also
DmCloseDatabase Function
Purpose
Declared In
DataMgr.h
Prototype
status_t DmCloseDatabase (
DmOpenRef dbRef
)
Parameters
Returns
Returns errNone
if no error, or dmErrInvalidParam
if an error occurs. Some releases may display a fatal error message instead of returning the error code.
Comments
This function doesn't unlock any records that were left locked. Records and resources should not be left locked. If a record or 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 DmSetDatabaseProtection()
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.
DmCloseDatabase()
updates the database's modification date.
See Also
DmOpenDatabase()
, DmDeleteDatabase()
, DmOpenDatabaseByTypeCreator()
DmCloseIteratorByTypeCreator Function
Purpose
Indicate that a particular iteration loop is complete.
Declared In
DataMgr.h
Prototype
status_t DmCloseIteratorByTypeCreator (
DmSearchStatePtr stateInfoP
)
Parameters
-
→ stateInfoP
- Pointer to the
DmSearchStateType
structure supplied toDmOpenIteratorByTypeCreator()
andDmGetNextDatabaseByTypeCreator()
.
Returns
Comments
See the comments under DmGetNextDatabaseByTypeCreator()
for an example of how this function is used.
See Also
DmGetNextDatabaseByTypeCreator()
, DmOpenIteratorByTypeCreator()
DmCreateDatabase Function
Purpose
Create a new extended database with the given name, creator, and type.
Declared In
DataMgr.h
Prototype
status_t DmCreateDatabase ( const char*nameP
, uint32_tcreator
, uint32_ttype
, BooleanresDB
)
Parameters
-
→ 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. Iffalse
, create a record database.
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrInvalidDatabaseName
- The name you've specified for the database is invalid.
-
dmErrAlreadyExists
- Another database with the same name already exists.
-
memErrCardNotPresent
- The specified card can't be found.
-
dmErrMemError
- A memory error occurred.
-
memErrChunkLocked
- The associated memory chunk is locked.
-
memErrInvalidParam
- A memory error occurred.
-
memErrInvalidStoreHeader
- The specified card has no storage RAM.
-
memErrNotEnoughSpace
- A memory error occurred.
-
memErrRAMOnlyCard
- The specified card has no storage RAM.
May display a fatal error message if the master database list cannot be found.
Comments
If another database with the same name and creator already exists in RAM store, this function returns a dmErrAlreadyExists
error.
Once created, the database ID can be retrieved by calling DmFindDatabase()
. The database can be opened using the database ID.
After you create a database, you should call DmSetDatabaseInfo()
to set the version number. Databases default to version 0 if the version isn't explicitly set.
IMPORTANT: This function creates extended databases only. To create a classic database, use
DmCreateDatabaseV50()
. To create a schema database, use DbCreateDatabase()
.
See Also
DmCreateDatabaseFromImage()
, DmOpenDatabase()
, DmDeleteDatabase()
DmCreateDatabaseFromImage Function
Purpose
Create an entire database from a single resource that contains an image of the database.
Declared In
DataMgr.h
Prototype
status_t DmCreateDatabaseFromImage ( MemPtrpImage
, DatabaseID*pDbID
)
Parameters
-
→ pImage
- Pointer to locked resource containing database image.
-
← pDbID
- Pointer to a variable that will hold the ID of the newly-created database, or
NULL
if the ID isn't needed.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrInvalidParam
-
pImage
isNULL
. -
dmErrMemError
- A memory error occurred. Most likely there wasn't enough memory available to create the database.
-
dmErrCorruptDatabase
- The format of the database image is unrecognized.
-
dmErrAlreadyExists
- The database being created already exists on the device.
Comments
An image is the same as a desktop file representation of a PRC or PDB file. This function creates either an extended or a classic database, or a non-secure schema database, depending upon the image stored in the resource. To perform a similar operation for a secure schema database, see DbCreateSecureDatabaseFromImage()
.
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()
DmCreateDatabaseFromImageV50 Function
Purpose
Create an entire classic database from a single resource that contains an image of the database.
Declared In
DataMgr.h
Prototype
status_t DmCreateDatabaseFromImageV50 (
MemPtr pImage
)
Parameters
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrInvalidParam
-
pImage
isNULL
. -
dmErrMemError
- A memory error occurred. Most likely there wasn't enough memory available to create the database.
-
dmErrCorruptDatabase
- The format of the database image is unrecognized.
-
dmErrAlreadyExists
- The database being created already exists on the device.
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.
Compatibility
This function is provided for compatibility purposes. Note that it works only with classic databases—the only type of database supported in PACE and by previous versions of Palm OS. Native Palm OS Cobalt applications will likely want to use DmCreateDatabaseFromImage()
instead.
See Also
DmCreateDatabaseV50 Function
Purpose
Create a new classic database on the specified card with the given name, creator, and type.
Declared In
DataMgr.h
Prototype
status_t DmCreateDatabaseV50 ( uint16_tcardNo
, const char*nameP
, uint32_tcreator
, uint32_ttype
, BooleanresDB
)
Parameters
-
→ cardNo
- The number of the card on which to create the database. This value should always be zero.
-
→ nameP
- Name of new database, up to 32 ASCII bytes long, including the null terminator (as specified by
dmDBNameLength
). Database names must use only 7-bit ASCII characters (0x20 through 0x7E). -
→ creator
- Creator of the database.
-
→ type
- Type of the database.
-
→ resDB
- If
true
, create a resource database.
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrInvalidDatabaseName
- The name you've specified for the database is invalid.
-
dmErrAlreadyExists
- Another database with the same name already exists.
-
memErrCardNotPresent
- The specified card can't be found.
-
dmErrMemError
- A memory error occurred.
-
memErrChunkLocked
- The associated memory chunk is locked.
-
memErrInvalidParam
- A memory error occurred.
-
memErrInvalidStoreHeader
- The specified card has no storage RAM.
-
memErrNotEnoughSpace
- A memory error occurred.
-
memErrRAMOnlyCard
- The specified card has no storage RAM.
May display a fatal error message if the master database list cannot be found.
Comments
Call this function to create a new database on a specific card. If another classic database with the same name already exists in RAM store, this function 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
parameter 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.
Compatibility
This function is provided for compatibility purposes. Note that it only works with classic databases—the only type of database supported in PACE and by previous versions of Palm OS. Native Palm OS Cobalt applications may want to use DmCreateDatabase()
instead.
See Also
DmCreateDatabaseFromImage()
, DmOpenDatabase()
, DmDeleteDatabase()
DmDatabaseInfo Function
Purpose
Retrieve information about a non-schema database.
Declared In
DataMgr.h
Prototype
status_t DmDatabaseInfo ( DatabaseIDdbID
, DmDatabaseInfoPtrpDatabaseInfo
)
Parameters
-
→ dbID
- Database ID of the database.
-
→ pDatabaseInfo
- Pointer to a
DmDatabaseInfoType
structure that indicates where, or if, the database information is to be written.
Returns
Returns errNone
if the database information was successfully retrieved, or dmErrInvalidParam
if an error occurred.
Comments
Initialize the fields of the pDatabaseInfo
structure to point to variables where this function will write the information. If you don't want to retrieve data corresponding to a given field, set that field to NULL
.
See Also
DmDatabaseInfoV50()
, DmSetDatabaseInfo()
, DmDatabaseSize()
, DmOpenDatabaseInfoV50()
, DmFindDatabase()
, DmGetNextDatabaseByTypeCreator()
, TimSecondsToDateTime()
DmDatabaseInfoV50 Function
Purpose
Retrieve information about a database.
Declared In
DataMgr.h
Prototype
status_t DmDatabaseInfoV50 ( uint16_tcardNo
, LocalIDdbID
, char*nameP
, uint16_t*attributesP
, uint16_t*versionP
, uint32_t*crDateP
, uint32_t*modDateP
, uint32_t*bckUpDateP
, uint32_t*modNumP
, LocalID*appInfoIDP
, LocalID*sortInfoIDP
, uint32_t*typeP
, uint32_t*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 Attributes" 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. PassNULL
for this parameter if you don't want to retrieve it. -
← sortInfoIDP
- The local ID of the database's sort table. This is an optional field in the database header. Pass
NULL
for this parameter if you don't want to retrieve it. -
← typeP
- The database's type, specified when it is created. Pass
NULL
for this parameter if you don't want to retrieve it. -
← creatorP
- The database's creator, specified when it is created. Pass
NULL
for this parameter if you don't want to retrieve it.
Returns
Returns errNone
if no error, or dmErrInvalidParam
if an error occurs.
Comments
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()
.
Compatibility
This function is provided for compatibility purposes only; Palm OS Cobalt applications will likely want to use DmDatabaseInfo()
instead.
See Also
DmDatabaseInfo()
, DmSetDatabaseInfo()
, DmDatabaseSize()
, DmOpenDatabaseInfoV50()
, DmFindDatabase()
, DmGetNextDatabaseByTypeCreator()
, TimSecondsToDateTime()
DmDatabaseProtectV50 Function
Purpose
Increment or decrement a non-schema database's protection count.
Declared In
DataMgr.h
Prototype
status_t DmDatabaseProtectV50 ( uint16_tcardNo
, LocalIDdbID
, Booleanprotect
)
Parameters
-
→ cardNo
- Card number of database to protect/unprotect.
-
→ dbID
- Local ID of database to protect/unprotect.
-
→ protect
- If
true
, the database's protection count is incremented. Iffalse
, it is decremented.
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
memErrCardNotPresent
- The specified card can't be found.
-
dmErrROMBased
- You've attempted to delete or modify a ROM-based database.
-
dmErrCantFind
- The specified database can't be found.
-
memErrNotEnoughSpace
- A memory error occurred.
-
dmErrDatabaseNotProtected
Comments
This function 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
This function is provided for compatibility purposes only. Palm OS Cobalt functions should use DmSetDatabaseProtection()
instead.
DmDatabaseSize Function
Purpose
Retrieve size information for a database.
Declared In
DataMgr.h
Prototype
status_t DmDatabaseSize ( DatabaseIDdbID
, uint32_t*numRecordsP
, uint32_t*totalBytesP
, uint32_t*dataBytesP
)
Parameters
-
→ dbID
- Database ID of the database.
-
← numRecordsP
- The total number of records in the database. Pass
NULL
for this parameter if you don't want to retrieve it. -
← totalBytesP
- The total number of bytes used by the database including the overhead. Pass
NULL
for this parameter if you don't want to retrieve it. -
← dataBytesP
- The total number of bytes used to store just each record's data, not including overhead. Pass
NULL
for this parameter if you don't want to retrieve it.
Returns
Returns errNone
if no error, or dmErrMemError
if an error occurs.
Comments
This function operates on extended, classic, or schema databases.
See Also
DmDatabaseInfo()
, DmOpenDatabaseInfoV50()
, DmFindDatabase()
, DmGetNextDatabaseByTypeCreator()
DmDatabaseSizeV50 Function
Purpose
Retrieve size information for a database.
Declared In
DataMgr.h
Prototype
status_t DmDatabaseSizeV50 ( uint16_tcardNo
, LocalIDdbID
, uint32_t*numRecordsP
, uint32_t*totalBytesP
, uint32_t*dataBytesP
)
Parameters
-
→ cardNo
- Card number the database resides on.
-
→ dbID
- Database ID of the database.
-
← numRecordsP
- The total number of records in the database. Pass
NULL
for this parameter if you don't want to retrieve it. -
← totalBytesP
- The total number of bytes used by the database including the overhead. Pass
NULL
for this parameter if you don't want to retrieve it. -
← dataBytesP
- The total number of bytes used to store just each record's data, not including overhead. Pass
NULL
for this parameter if you don't want to retrieve it.
Returns
Returns errNone
if no error, or dmErrMemError
if an error occurs.
Compatibility
This function is provided for compatibility purposes only. Palm OS Cobalt applications should use DmDatabaseSize()
instead.
See Also
DmDatabaseInfo()
, DmOpenDatabaseInfoV50()
, DmFindDatabase()
, DmGetNextDatabaseByTypeCreator()
DmDeleteCategory Function
Purpose
Delete all records in a category. The category name is not changed.
Declared In
DataMgr.h
Prototype
status_t DmDeleteCategory ( DmOpenRefdbRef
, uint16_tcategoryNum
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ categoryNum
- Category of records to delete. Category masks such as
dmAllCategories
are invalid.
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
memErrInvalidParam
- A memory error occurred.
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
.
Example
You can use the DmGetRecordCategory()
call to obtain a category index from a given record, as shown in the following code excerpt:
DmOpenRef myDB; //assume that this is set uint16_t myRecIndex; //assume that this is set uint8_t category; status_t err; err = DmGetRecordCategory(myDB, myRecIndex, &category); err = DmDeleteCategory(myDB, category);
DmDeleteDatabase Function
Purpose
Delete a database and all of its records.
Declared In
DataMgr.h
Prototype
status_t DmDeleteDatabase (
DatabaseID dbID
)
Parameters
Returns
Returns errNone
if no error, or one of the following if an error occurred:
-
dmErrCantFind
- The specified database can't be found.
-
dmErrCantOpen
- The database cannot be opened.
-
memErrChunkLocked
- The associated memory chunk is locked.
-
dmErrDatabaseOpen
- The function cannot be performed on an open database, and the database is open.
-
dmErrROMBased
- You've attempted to delete or modify a ROM-based database.
-
memErrInvalidParam
- A memory error occurred.
-
memErrNotEnoughSpace
- A memory error occurred.
Comments
Call this function to delete a database. This function 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 function accepts a database ID as a parameter. To determine the database ID, call DmFindDatabase()
.
IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.
See Also
DmDeleteRecord()
, DmRemoveRecord()
, DmRemoveResource()
, DmCreateDatabase()
, DmGetNextDatabaseByTypeCreator()
, DmFindDatabase()
DmDeleteDatabaseV50 Function
Purpose
Delete a database and all its records.
Declared In
DataMgr.h
Prototype
status_t DmDeleteDatabaseV50 ( uint16_tcardNo
, LocalIDdbID
)
Parameters
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrCantFind
- The specified database can't be found.
-
dmErrCantOpen
- The database cannot be opened.
-
memErrChunkLocked
- The associated memory chunk is locked.
-
dmErrDatabaseOpen
- The function cannot be performed on an open database, and the database is open.
-
dmErrDatabaseProtected
- The database is marked as protected.
-
dmErrROMBased
- You've attempted to delete or modify a ROM-based database.
-
memErrInvalidParam
- A memory error occurred.
-
memErrNotEnoughSpace
- A memory error occurred.
Comments
Call this function to delete a database. This function 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 function accepts a database ID as a parameter. To determine the database ID, call either DmFindDatabase()
or DmGetDatabaseV50()
with a database index.
IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.
Compatibility
This function is provided for compatibility purposes. Palm OS Cobalt applications will likely want to use DmDeleteDatabase()
instead.
See Also
DmDeleteRecord()
, DmRemoveRecord()
, DmRemoveResource()
, DmCreateDatabase()
, DmGetNextDatabaseByTypeCreator()
, DmFindDatabase()
DmDeleteRecord Function
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 HotSync operation.
Declared In
DataMgr.h
Prototype
status_t DmDeleteRecord ( DmOpenRefdbRef
, uint16_tindex
)
Parameters
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
dmErrIndexOutOfRange
- The specified index is out of range.
-
dmErrRecordArchived
- The function requires that the record not be archived, but it is.
-
dmErrRecordDeleted
- The record has been deleted.
-
memErrInvalidParam
- A memory error occurred.
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 Function
Purpose
Detach and orphan a record from a database but don't delete the record's chunk.
Declared In
DataMgr.h
Prototype
status_t DmDetachRecord ( DmOpenRefdbRef
, uint16_tindex
, MemHandle*hDetached
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Index of the record to detach.
-
↔ hDetached
- Pointer to return handle of the detached record.
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
dmErrIndexOutOfRange
- The specified index is out of range.
-
dmErrNotRecordDB
- You've attempted to perform a record function on a resource database.
-
memErrChunkLocked
- The associated memory chunk is locked.
-
memErrInvalidParam
- A memory error occurred.
Some releases may display a fatal error message instead of returning the error code.
Comments
This function 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 *hDetached
. Unlike DmDeleteRecord()
, this function removes its entry in the database header but it does not delete the actual record.
See Also
DmAttachRecord()
, DmRemoveRecord()
, DmArchiveRecord()
, DmDeleteRecord()
DmDetachResource Function
Purpose
Detach a resource from a database and return the handle of the resource's data.
Declared In
DataMgr.h
Prototype
status_t DmDetachResource ( DmOpenRefdbRef
, uint16_tindex
, MemHandle*hDetached
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Index of resource to detach.
-
↔ hDetached
- Pointer to return handle of the detached record.
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
dmErrIndexOutOfRange
- The specified index is out of range.
-
dmErrCorruptDatabase
- The database is corrupted.
-
memErrChunkLocked
- The associated memory chunk is locked.
-
memErrInvalidParam
- A memory error occurred.
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 function 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 *hDetached
.
See Also
DmAttachResource()
, DmRemoveResource()
DmFindDatabase Function
Purpose
Return the database ID of a database given its name and creator ID.
Declared In
DataMgr.h
Prototype
DatabaseID DmFindDatabase ( const char*nameP
, uint32_tcreator
, DmFindTypefind
, DmDatabaseInfoPtrdatabaseInfoP
)
Parameters
-
→ nameP
- Name of the database to look for.
-
→ creator
- Creator ID of the database to look for.
-
→ find
- Flags indicating the type of database to be searched for: schema, extended, classic, or a combination of the three. See
DmFindType
for more information. -
← databaseInfoP
- Pointer to a
DmDatabaseInfoType
structure which is filled out appropriately for the found database, orNULL
if this information isn't needed.
Returns
Returns the database ID. If the database can't be found, this function returns 0, and DmGetLastErr()
returns an error code indicating the reason for failure.
Comments
This function first searches in RAM; if a database matching the specified criteria is not found, it then searches the device's ROM.
See Also
DmDatabaseInfo()
, DmFindDatabaseByTypeCreator()
, DmFindDatabaseV50()
, DmGetNextDatabaseByTypeCreator()
DmFindDatabaseByTypeCreator Function
Purpose
Return the database ID of a database given its type and creator ID.
Declared In
DataMgr.h
Prototype
DatabaseID DmFindDatabaseByTypeCreator ( uint32_ttype
, uint32_tcreator
, DmFindTypefind
, DmDatabaseInfoPtrdatabaseInfoP
)
Parameters
-
→ type
- Database type of the database to look for.
-
→ creator
- Creator ID of the database to look for.
-
→ find
- Flags indicating the type of database to be searched for: schema, extended, classic, or a combination of the three. See
DmFindType
for more information. -
← databaseInfoP
- Pointer to a
DmDatabaseInfoType
structure which is filled out appropriately for the found database, orNULL
if this information isn't needed.
Returns
Returns the database ID. If the database can't be found, this function returns 0, and DmGetLastErr()
returns an error code indicating the reason for failure.
Comments
This function first searches in RAM; if a database matching the specified criteria is not found, it then searches the device's ROM.
This function can be used to find extended, classic, or even schema databases.
See Also
DmDatabaseInfo()
, DmFindDatabase()
, DmGetNextDatabaseByTypeCreator()
DmFindDatabaseV50 Function
Purpose
Return the database ID of a classic database given its card number and name.
Declared In
DataMgr.h
Prototype
LocalID DmFindDatabaseV50 ( uint16_tcardNo
, const char*nameP
)
Parameters
Returns
Returns the database ID. If the database can't be found, this function returns 0, and DmGetLastErr()
returns an error code indicating the reason for failure.
Comments
This function searches only within the classic namespace. This eliminates the possibility of finding multiple databases with the same name.
Palm OS Cobalt applications should usually use DmFindDatabase()
instead of this function. In order to ensure compatibility, this function only searches for classic database. Note that this function isn't as flexible as DmFindDatabase()
since it finds databases without regard to their creator ID. This is consistent with earlier versions of Palm OS, in which databases had to be uniquely identified by name.
Compatibility
This function is provided for compatibility purposes only. Palm OS Cobalt applications should use DmFindDatabase()
instead.
See Also
DmFindDatabase()
, DmGetNextDatabaseByTypeCreator()
, DmDatabaseInfo()
, DmOpenDatabase()
DmFindRecordByID Function
Purpose
Return the index of the record with the given unique ID.
Declared In
DataMgr.h
Prototype
status_t DmFindRecordByID ( DmOpenRefdbRef
, uint32_tuniqueID
, uint16_t*pIndex
)
Parameters
Returns
Returns 0 if found, otherwise dmErrUniqueIDNotFound
. May display a fatal error message if the unique ID is invalid.
See Also
DmQueryRecord()
, DmGetRecord()
, DmRecordInfoV50()
DmFindRecordByOffsetInCategory Function
Purpose
Return the index of the record nearest the offset from the passed record index whose category matches the passed category. (The offset
parameter indicates the number of records to move forward or backward.)
Declared In
DataMgr.h
Prototype
status_t DmFindRecordByOffsetInCategory ( DmOpenRefdbRef
, uint16_t*pIndex
, uint16_toffset
, int16_tdirection
, uint16_tcategory
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
↔ pIndex
- 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 thedirection
parameter to search backwards. -
→ direction
- Must be either
dmSeekForward
ordmSeekBackward
. -
→ category
- Category index.
Returns
Returns errNone
if no error; returns dmErrIndexOutOfRange
or dmErrSeekFailed
if an error occurred.
Comments
DmFindRecordByOffsetInCategory()
searches for a record in the specified category. The search begins with the record at pIndex
. 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 DmFindRecordByOffsetInCategory()
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 pIndex
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 pIndex
value changes. If the record at pIndex
isn't in the category, you must pass an offset
of 0 to find the next record in the category. In this case, an offset
of 1 skips the first matching record.
Records that have the deleted
bit set are ignored, and if the user has specified that private records should be hidden or masked, private records are ignored as well.
See Also
DmNumRecordsInCategory()
, DmQueryNextInCategory()
, DmMoveCategory()
DmFindResource Function
Purpose
Search the given database for a resource by type and ID, or by pointer if it is non-NULL
.
Declared In
DataMgr.h
Prototype
uint16_t DmFindResource ( DmOpenRefdbRef
, DmResourceTyperesType
, DmResourceIDresID
, MemHandlehResource
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ resType
- Type of resource to search for.
-
→ resID
- ID of resource to search for.
-
→ hResource
- Pointer to locked resource, or
NULL
.
Returns
Returns index of resource in resource database, or dmInvalidRecIndex
if not found.
May display a fatal error message if the database is not a resource database.
Comments
Use this function 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
DmGet1ResourceV50()
instead of this function.
If hResource
is NULL
, the resource is searched for by type and ID.
If hResource
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 DmGetResourceByIndex()
.
See Also
DmGetResource()
, DmSearchResourceOpenDatabases()
, DmResourceInfo()
, DmGetResourceByIndex()
, DmFindResourceType()
DmFindResourceType Function
Purpose
Search the given database for a resource by type and type index.
Declared In
DataMgr.h
Prototype
uint16_t DmFindResourceType ( DmOpenRefdbRef
, DmResourceTyperesType
, uint16_ttypeIndex
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ resType
- Type of resource to search for.
-
→ typeIndex
- Index of given resource type.
Returns
Index of resource in resource database, or 0xFFFF
if not found.
May display a fatal error message if the database is not a resource database.
Comments
Use this function 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 DmGetResourceByIndex()
.
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
DmGet1ResourceV50()
instead of this function.
See Also
DmGetResource()
, DmSearchResourceOpenDatabases()
, DmResourceInfo()
, DmGetResourceByIndex()
, DmFindResource()
DmGet1ResourceV50 Function
Purpose
Search the most recently opened resource database and return a handle to a resource given the resource type and ID.
Declared In
DataMgr.h
Prototype
MemHandle DmGet1ResourceV50 ( DmResourceTyperesType
, DmResourceIDresID
)
Parameters
Returns
Handle to resource data. If unsuccessful, this function returns NULL
and DmGetLastErr()
returns an error code indicating the reason for failure.
Comments
Searches the most recently opened resource database for a resource of the given type and ID. If the database has an overlay associated with it, the overlay is searched first, and then the base database is searched if the overlay does not contain the resource. If found, the resource handle is returned. The application should call DmReleaseResource()
as soon as it finishes accessing the resource data. The resource handle is not locked by this function.
Compatibility
This function is provided for compatibility purposes only. Palm OS Cobalt applications should use DmGetResource()
or DmGetResourceByIndex()
instead.
See Also
DmGetResource()
, DmReleaseResource()
, ResLoadConstant()
DmGetAppInfo Function
Purpose
Return the handle of the specified database's application info block.
Declared In
DataMgr.h
Prototype
status_t DmGetAppInfo ( DmOpenRefdbRef
, MemHandle*pAppInfoHandle
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
← pAppInfoHandle
- Memory handle of the application info block.
Returns
Returns errNone
if the handle was returned successfully, or one of the following if an error occurred:
Compatibility
This function can be used with extended or classic databases. Note that schema databases don't have an explicit application info block.
DmGetAppInfoIDV50 Function
Purpose
Return the local ID of the specified database's application info block.
Declared In
DataMgr.h
Prototype
LocalID DmGetAppInfoIDV50 (
DmOpenRef dbRef
)
Parameters
Returns
Returns local ID of the application info block. The application info block is an optional field that the database may use to store application-specific information about the database; if the database doesn't have an application info block, DmGetAppInfoIDV50()
returns zero.
Compatibility
This function is provided for compatibility purposes only. Palm OS Cobalt applications will likely want to use DmGetAppInfo()
instead.
See Also
DmDatabaseInfo()
, DmOpenDatabase()
DmGetDatabaseLockState Function
Purpose
Return information about the number of locked and busy records in a RAM-based non-schema database.
Declared In
DataMgr.h
Prototype
status_t DmGetDatabaseLockState ( DmOpenRefdbRef
, uint8_t*pHighest
, uint32_t*pCount
, uint32_t*pBusy
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
← pHighest
- 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. -
← pCount
- The number of records that have the lock count that is returned in the
pHighest
parameter. PassNULL
for this parameter if you don't want to retrieve it. -
← pBusy
- The number of records that have the busy bit set. Pass
NULL
for this parameter if you don't want to retrieve it.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database, ordbRef
references a schema database. -
memErrInvalidParam
- A memory error occurred.
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.
Because databases stored in ROM cannot be locked, if this function is used with a ROM-based database it returns errNone
but *
pHighest
, *
pCount
, and *
pBusy
(if supplied) are all set to zero.
DmGetDatabaseV50 Function
Purpose
Get the database header ID of a database, given its index and card number.
Declared In
DataMgr.h
Prototype
LocalID DmGetDatabaseV50 ( uint16_tcardNo
, uint16_tindex
)
Parameters
Returns
Returns the database ID, or 0 if an invalid parameter is passed.
Comments
Call this function to retrieve the database ID of a database by index. The index should range from 0 to DmNumDatabases()
-1.
This function 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.
Compatibility
This function is provided for compatibility purposes. Palm OS Cobalt applications that want to iterate through all of a handheld's databases should use DmGetNextDatabaseByTypeCreator()
instead.
See Also
DmOpenDatabase()
, DmNumDatabases()
, DmDatabaseInfo()
, DmDatabaseSize()
DmGetFallbackOverlayLocale Function
Purpose
Get the fallback overlay locale: the locale used when the Data Manager attempts to open an overlay locale for which no valid overlay exists.
Declared In
DataMgr.h
Prototype
status_t DmGetFallbackOverlayLocale (
LmLocaleType *fallbackLocale
)
Parameters
Returns
Returns errNone
if the fallback locale was obtained successfully, or dmErrInvalidParam
if the fallbackLocale
parameter is invalid.
Comments
The fallback overlay locale is used by the Data Manager when it attempts to automatically open an overlay using the overlay locale, but no valid overlay exists, and the base probably has been stripped.
See Also
DmGetOverlayDatabaseLocale()
, DmGetOverlayLocale()
, DmSetFallbackOverlayLocale()
DmGetLastErr Function
Purpose
Return error code from last Data Manager call.
Declared In
DataMgr.h
Prototype
status_t DmGetLastErr ( void )
Parameters
Returns
Error code from last unsuccessful Data Manager call.
Comments
Use this function 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 Data Manager functions listed in Table 4.1 currently affect the value returned by DmGetLastErr()
.
Table 4.1 Functions that affect the value returned by DmGetLastErr()
DmGetNextDatabaseByTypeCreator Function
Purpose
Iterate to the next database that meets the criteria set forth in a previous call to DmOpenIteratorByTypeCreator()
.
Declared In
DataMgr.h
Prototype
status_t DmGetNextDatabaseByTypeCreator ( DmSearchStatePtrstateInfoP
, DatabaseID*dbIDP
, DmDatabaseInfoPtrdatabaseInfoP
)
Parameters
-
→ stateInfoP
- Pointer to the
DmSearchStateType
structure originally supplied toDmOpenIteratorByTypeCreator()
. -
← dbIDP
- Pointer to a location into which the ID of the found database is written (a value of zero is written if a database meeting the specified criteria isn't found). Pass
NULL
if the ID of the database isn't needed. -
← databaseInfoP
- Pointer to a
DmDatabaseInfoType
structure which is filled out appropriately for the found database. PassNULL
if this information isn't needed.
Returns
Returns errNone
if a database meeting the specified criteria is found, dmErrCantFind
if there are no additional databases meeting the specified criteria, or one of the following if an error occurred:
-
dmErrInvalidParam
- The
find
parameter passed toDmOpenIteratorByTypeCreator()
did not contain at least one of the defined database type flags.
Comments
Both dbIDP
and databaseInfoP
are optional; pass NULL
for both if you only need to know if there exists a database that meets your particular criteria. Otherwise, pass pointers as appropriate for one or both.
This function searches all heaps for a match.
To start the search, allocate a DmSearchStateType
structure and pass it as the stateInfoP
parameter in a call to DmOpenIteratorByTypeCreator()
. Then, call DmGetNextDatabaseByTypeCreator()
. Note that you need to call this function repeatedly to discover all databases having a specified type/creator pair. Finally, be sure to call DmCloseIteratorByTypeCreator()
to finalize the iteration.
You can pass dmSearchWildcardID
for the type
or creator
parameter to conduct searches of wider scope. If the type
parameter is dmSearchWildcardID
, this function can be called successively to return all databases of the given creator. If the creator
parameter is dmSearchWildcardID
, this function can be called successively to return all databases of the given type. You can also pass dmSearchWildcardID
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.
If onlyLatestVers
is true
, you only receive one matching database for each type/creator pair. Note that the behavior is different only when you have specified a value for both type
and creator
and onlyLatestVers
is true
.
Example
The following code excerpt illustrates how to iterate through the latest versions of all schema databases on the device that have a given type and creator.
status_t err; DmSearchStateType state; DatabaseID dbID = NULL; uint32_t creator; char name[dmDBNameLength]; DmDatabaseInfoType databaseInfo; // Initialize the DmDatabaseInfoType structure memset(&databaseInfo, 0x0, sizeof(DmDatabaseInfoType)); databaseInfo.name = name; databaseInfo.creator = &creator; err = DmOpenIteratorByTypeCreator(&state, myType, myCreator, true, dmHdrAttrSchema); while (err == errNone) { err = DmGetNextDatabaseByTypeCreator(&state, &dbID, &databaseInfo); if (err == errNone) { // a database was found; the ID is in dbID, and info // about the database is in databaseInfo. Do something // with this information here. } } DmCloseIteratorByTypeCreator(&state);
See Also
DmFindDatabase()
, DmFindDatabaseByTypeCreator()
, DmOpenIteratorByTypeCreator()
, DmCloseIteratorByTypeCreator()
DmGetNextDatabaseByTypeCreatorV50 Function
Purpose
Return the header ID and card number for a classic database or an extended resource database given the type, the creator, or both. This function searches all heaps for a match.
Declared In
DataMgr.h
Prototype
status_t DmGetNextDatabaseByTypeCreatorV50 ( BooleannewSearch
, DmSearchStatePtrstateInfoP
, uint32_ttype
, uint32_tcreator
, BooleanonlyLatestVers
, uint16_t*cardNoP
, LocalID*dbIDP
)
Parameters
-
→ newSearch
-
true
if starting a new search. -
↔ stateInfoP
- If
newSearch
isfalse
, this must point to the same data used for the previous invocation. -
→ type
- Type of database to search for. Pass
dmSearchWildcardID
to find databases with any type. -
→ creator
- Creator of database to search for. Pass
dmSearchWildcardID
to find databases with any creator. -
→ 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. Pass
NULL
if you don't need the card number (note that as in Palm OS Cobalt the card number is always zero). -
← dbIDP
- Local ID of the found database. Pass
NULL
if you don't need the database's local ID.
Returns
Returns errNone
if no error, or dmErrCantFind
if no matches were found.
Comments
You may need to call this function successively to discover all databases having a specified type/creator pair.
To start the search, pass true
for newSearch
. Allocate a DmSearchStateType
structure and pass it as the stateInfoP
parameter. DmGetNextDatabaseByTypeCreator()
stores private information in stateInfoP
and uses it if the search is continued.
To continue a search where the previous one left off, pass false
for newSearch
and pass the same stateInfoP
that you used during the previous call to this function.
You can pass dmSearchWildcardID
for the type
or creator
parameter to conduct searches of wider scope. If the type
parameter is dmSearchWildcardID
, this function can be called successively to return all databases of the given creator. If the creator
parameter is dmSearchWildcardID
, this function can be called successively to return all databases of the given type. You can also pass dmSearchWildcardID
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
DmGetNextDatabaseByTypeCreatorV50()
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.
If onlyLatestVers
is true
, you only receive one matching database for each type/creator pair. Note that the behavior is different only when you have specified a value for both type
and creator
and onlyLatestVers
is true
.
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
tofalse
if you specify both atype
andcreator
. - Specify
0
for either thetype
orcreator
parameter (or both).
Compatibility
This function is provided for compatibility purposes only. Most Palm OS Cobalt applications will want to use DmGetNextDatabaseByTypeCreator()
instead; that function (in conjunction with DmOpenIteratorByTypeCreator()
and DmCloseIteratorByTypeCreator()
) can be used to locate classic, extended, or schema databases.
See Also
DmFindDatabase()
, DmDatabaseInfo()
, DmOpenDatabaseByTypeCreator()
, DmDatabaseSize()
DmGetOpenInfo Function
Purpose
Retrieve information about an open database.
Declared In
DataMgr.h
Prototype
status_t DmGetOpenInfo ( DmOpenRefdbRef
, DatabaseID*pDbID
, uint16_t*pOpenCount
, DmOpenModeType*pOpenMode
, Boolean*pResDB
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
← pDbID
- ID of the database. Pass
NULL
for this parameter if you don't want to retrieve this information. -
← pOpenCount
- Number of applications that have this database open. Pass
NULL
for this parameter if you don't want to retrieve this information. -
← pOpenMode
- Mode used to open the database (see
DmOpenModeType
). PassNULL
for this parameter if you don't want to retrieve this information. -
← pResDB
- If
true
upon return, the database is a resource database. Otherwise, the database is a record database. PassNULL
for this parameter if you don't want to retrieve this information.
Returns
See Also
DmGetOverlayDatabaseLocale Function
Purpose
Return an overlay database's locale given its name.
Declared In
DataMgr.h
Prototype
status_t DmGetOverlayDatabaseLocale ( const char*overlayDBName
, LmLocaleType*overlayLocale
)
Parameters
-
→ overlayDBName
- The name of the overlay database.
-
← overlayLocale
- Points to an
LmLocaleType
structure into which the overlay's locale is written. Your application must allocate and pass a pointer to this structure.
Returns
Returns errNone
upon success, or one of the following if an error occurred:
-
dmErrInvalidParam
- The function received an invalid parameter.
-
dmErrBadOverlayDBName
- The
overlayDBName
parameter doesn't point to the name of an overlay database.
DmGetOverlayDatabaseName Function
Purpose
Return the overlay database's name given the base database name and the locale.
Declared In
DataMgr.h
Prototype
status_t DmGetOverlayDatabaseName ( const char*baseDBName
, const LmLocaleType*targetLocale
, char*overlayDBName
)
Parameters
-
→ baseDBName
- The name of the base database with which the overlay is associated.
-
→ targetLocale
- The locale to which this overlay applies. See
LmLocaleType
. PassNULL
to use the current locale. -
← overlayDBName
- Pointer to a buffer into which the overlay database name is written. This buffer must be at least
dmDBNameLength
bytes.
Returns
Returns errNone
upon success, or dmErrInvalidParam
if one of the parameters is invalid.
DmGetOverlayLocale Function
Purpose
Get the Data Manager's overlay locale: the locale used by the Data Manager when it attempts to automatically open overlays.
Declared In
DataMgr.h
Prototype
status_t DmGetOverlayLocale (
LmLocaleType *overlayLocale
)
Parameters
-
← overlayLocale
- Pointer to an
LmLocaleType
structure into which the overlay's locale is written. Your application must allocate and pass a pointer to this structure.
Returns
Returns errNone
upon success, or dmErrInvalidParam
if one of the parameters is invalid.
See Also
DmGetOverlayDatabaseLocale()
, DmSetOverlayLocale()
DmGetPositionInCategory Function
Purpose
Return a position of a record within the specified category.
Declared In
DataMgr.h
Prototype
uint16_t DmGetPositionInCategory ( DmOpenRefdbRef
, uint16_tindex
, uint16_tcategory
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Index of the record.
-
→ category
- Index of category to search.
Returns
Returns the position (zero-based). If the specified index is out of range, this function returns 0 and DmGetLastErr()
returns an error code indicating the reason for failure. Note that this means a 0 return value might indicate either success or failure. If this function returns 0 and DmGetLastErr()
returns errNone
, the return value indicates that this is the first record in the category.
Comments
Because this function must examine all records up to the current record, it can be slow to return, especially when called on a large database.
Records that have the deleted
bit set are ignored, and if the user has specified that private records should be hidden or masked, private records are ignored as well.
If the record is ROM-based (pointer accessed) this function makes a fake handle to it and stores this handle in the DmAccessType
structure.
To learn which category a record is in, use DmGetRecordCategory()
.
See Also
DmQueryNextInCategory()
, DmFindRecordByOffsetInCategory()
, DmMoveCategory()
DmGetRecord Function
Purpose
Return a handle to a record by index and mark the record busy.
Declared In
DataMgr.h
Prototype
MemHandle DmGetRecord ( DmOpenRefdbRef
, uint16_tindex
)
Parameters
Returns
Returns a handle to record data. If another call to DmGetRecord()
for the same record is attempted before the record is released, NULL
is returned and DmGetLastErr()
returns an error code indicating the reason for failure.
Comments
Returns a handle to given record and sets the busy
bit for the record.
If the record is ROM-based (pointer accessed), this function 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
DmSearchRecordOpenDatabases()
, DmFindRecordByID()
, DmRecordInfoV50()
, DmReleaseRecord()
, DmQueryRecord()
DmGetRecordAttr Function
Purpose
Get the attributes of a database record.
Declared In
DataMgr.h
Prototype
status_t DmGetRecordAttr ( DmOpenRefdbRef
, uint16_tindex
, uint8_t*pAttr
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Index of the record for which attributes are being retrieved.
-
← pAttr
- Pointer to a variable into which the record's attributes are written. See "Non-Schema Database Record Attributes" for a description of the attributes.
Returns
Returns errNone
if the attributes were successfully obtained, or one of the following if an error occurred:
-
dmErrNotRecordDB
- You've attempted to perform a record function on a resource database.
-
dmErrIndexOutOfRange
- The specified index is out of range.
See Also
DmRecordInfoV50()
, DmSetRecordAttr()
DmGetRecordCategory Function
Purpose
Get the category information for a record.
Declared In
DataMgr.h
Prototype
status_t DmGetRecordCategory ( DmOpenRefdbRef
, uint16_tindex
, uint8_t*pCategory
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Index of the record for which the category information is being obtained.
-
← pCategory
- Pointer to a variable into which the record's category information is written.
Returns
Returns errNone
if the category information was successfully obtained, or one of the following if an error occurred:
-
dmErrNotRecordDB
- You've attempted to perform a record function on a resource database.
-
dmErrIndexOutOfRange
- The specified index is out of range.
See Also
DmRecordInfoV50()
, DmSetRecordCategory()
DmGetRecordID Function
Purpose
Get the record ID for the record at the given index position.
Declared In
DataMgr.h
Prototype
status_t DmGetRecordID ( DmOpenRefdbRef
, uint16_tindex
, uint32_t*pUID
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Index of the record for which to retrieve the ID.
-
← pUID
- Pointer to a variable into which the record ID is written.
Returns
Returns errNone
if the category information was successfully obtained, or one of the following if an error occurred:
-
dmErrNotRecordDB
- You've attempted to perform a record function on a resource database.
-
dmErrIndexOutOfRange
- The specified index is out of range.
-
dmErrInvalidParam
- The function received an invalid parameter.
See Also
DmRecordInfoV50()
, DmSetRecordID()
DmGetRecordSortPosition Function
Purpose
Returns where in a sorted list of records a given record would be located. Useful to find where to insert a record with DmAttachRecord()
. Uses a binary search.
Declared In
DataMgr.h
Prototype
uint16_t DmGetRecordSortPosition ( DmOpenRefdbRef
, void*pNewRecord
, DmSortRecordInfoType*pNewRecordInfo
, DmCompareFunctionType*pFuncCompar
, int16_tother
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ pNewRecord
- Pointer to the new record.
-
→ pNewRecordInfo
- Sort information about the new record. See
DmSortRecordInfoType
. -
→ pFuncCompar
- Pointer to comparison function. See
DmCompareFunctionType()
. -
→ other
- Any value the application wants to pass to the comparison function. This parameter is often used to indicate a sort direction (ascending or descending).
Returns
The position where the record should be inserted.
The position should be viewed as between the record returned and the record before it. Note that the return value may be one greater than the number of records.
Comments
If pNewRecord
has the same key as another record in the database, DmGetRecordSortPosition()
assumes that pNewRecord
should be inserted after that record. If there are several records with the same key, pNewRecord
is inserted after all of them. For this reason, if you use DmGetRecordSortPosition()
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, DmGetRecordSortPosition()
only works if those records are at the end of the database. DmGetRecordSortPosition()
always assumes that a deleted record is greater than or equal to any other record.
DmGetResource Function
Purpose
Search a specified open database and return a handle to a resource, given the resource type and ID.
Declared In
DataMgr.h
Prototype
MemHandle DmGetResource ( DmOpenRefdbRef
, DmResourceTyperesType
, DmResourceIDresID
)
Parameters
-
→ dbRef
- Reference to an open database to be searched.
-
→ resType
- The resource type.
-
→ resID
- The resource ID.
Returns
Handle to resource data. If the specified resource cannot be found, this function returns NULL
and DmGetLastErr()
returns an error code indicating the reason for failure.
Comments
Searches the specified database 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 the 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
DmGet1ResourceV50()
, DmReleaseResource()
, ResLoadConstant()
DmGetResourceByIndex Function
Purpose
Return a handle to a resource, given the index of that resource.
Declared In
DataMgr.h
Prototype
MemHandle DmGetResourceByIndex ( DmOpenRefdbRef
, uint16_tindex
)
Parameters
Returns
Handle to resource data. If the specified index is out of range, this function returns NULL
and DmGetLastErr()
returns an error code indicating the reason for failure.
May display a fatal error message if the database is not a resource database.
IMPORTANT: This function accesses the resource only in the database you specify. If you pass a pointer to a base resource database, its overlay is not accessed. Therefore, you should use care when using this function to access a potentially localized resource. You can use
DmSearchResourceOpenDatabases()
to obtain a pointer to the overlay database if the resource is localized; however, it's more convenient to use DmGetResource()
or DmGet1ResourceV50()
.
See Also
DmFindResource()
, DmFindResourceType()
, DmSearchResourceOpenDatabases()
DmGetResourceV50 Function
Purpose
Search all open resource databases and return a handle to a resource, given the resource type and ID.
Declared In
DataMgr.h
Prototype
MemHandle DmGetResourceV50 ( DmResourceTyperesType
, DmResourceIDresID
)
Parameters
Returns
Handle to resource data. If the specified resource cannot be found, this function returns NULL
and DmGetLastErr()
returns an error code indicating the reason for failure.
Comments
Searches all open resource databases starting with the most recently opened one for a resource of the given type and ID. If found, the resource handle is returned. The application should call DmReleaseResource()
as soon as it finishes accessing the resource data. The resource handle is not locked by this function.
This function always returns the resource located in the overlay if any open overlay has a resource matching that type and ID. If there is no overlay version of the resource, this function returns the resource from the base database.
Compatibility
This function is provided for compatibility purposes. Because most Palm OS Cobalt applications know which resource file should contain the resource being searched for, for efficiency purposes such applications should use DmGetResource()
or DmGetResourceByIndex()
instead.
See Also
DmGet1ResourceV50()
, DmReleaseResource()
, ResLoadConstant()
DmGetStorageInfo Function
Purpose
Determine how much memory is used, and how much is free, in both secure and non-secure storage.
Declared In
DataMgr.h
Prototype
status_t DmGetStorageInfo (
DmStorageInfoPtr pStorageInfo
)
Parameters
-
→ pStorageInfo
- Pointer to a
DmStorageInfoType
structure, which upon return contains the memory usage information.
Returns
Returns errNone
if the memory information is obtained successfully, or one of the following otherwise:
-
dmErrInvalidParam
- The function received an invalid parameter.
-
dmErrMemError
- A memory error occurred.
Comments
Your application must allocate the DmStorageInfoType
structure prior to calling this function.
DmHandleFree Function
Purpose
Dispose of a movable chunk on the storage heap.
Declared In
DataMgr.h
Prototype
status_t DmHandleFree (
MemHandle handle
)
Parameters
Returns
Returns 0 if no error, or dmErrInvalidParam
if an error occurred.
Comments
Call this function to dispose of a movable chunk.
See Also
DmHandleLock Function
Purpose
Lock a storage heap chunk and obtain a pointer to the chunk's data.
Declared In
DataMgr.h
Prototype
MemPtr DmHandleLock (
MemHandle handle
)
Parameters
Returns
Returns a pointer to the chunk.
Comments
Call this function to lock a chunk and obtain a pointer to it. Call MemHandleLock()
to lock a chunk allocated on the dynamic heap.
DmHandleLock()
and DmHandleUnlock()
should be used in pairs.
See Also
DmHandleResize Function
Purpose
Declared In
DataMgr.h
Prototype
status_t DmHandleResize ( MemHandlehandle
, uint32_tnewSize
)
Parameters
Returns
Returns errNone
if the chunk was successfully resized, or one of the following if an error occurred:
-
dmErrInvalidParam
- Invalid parameter passed.
-
memErrNotEnoughSpace
- A memory error occurred.
-
memErrChunkLocked
- The associated memory chunk is locked.
Comments
Call this function to resize a chunk. This function is always successful when shrinking the size of a chunk, even if the chunk is locked. When growing a chunk, it first attempts to grab free space immediately following the chunk so that the chunk does not have to move. If the chunk has to move to another free area of the heap to grow, it must be movable and have a lock count of 0.
See Also
MemHandleNew()
, DmHandleSize()
DmHandleSize Function
Purpose
Return the requested size of a storage heap chunk.
Declared In
DataMgr.h
Prototype
uint32_t DmHandleSize (
MemHandle handle
)
Parameters
Returns
Returns the requested size of the chunk.
Comments
Call this function to get the size originally requested for a chunk.
See Also
DmHandleUnlock Function
Purpose
Unlock a storage heap chunk given a chunk handle.
Declared In
DataMgr.h
Prototype
status_t DmHandleUnlock (
MemHandle handle
)
Parameters
Returns
Returns errNone
if the handle was successfully unlocked, or dmErrInvalidParam
if the passed handle was invalid.
Comments
Call this function to decrement the lock count for a chunk.
DmHandleLock()
and DmHandleUnlock()
should be used in pairs.
DmInitiateAutoBackupOfOpenDatabase Function
Purpose
Update the automatic backup file for a given open database.
Declared In
DataMgr.h
Prototype
status_t DmInitiateAutoBackupOfOpenDatabase (
DmOpenRef dbRef
)
Parameters
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrInvalidParam
-
dbRef
doesn't reference a valid open database. -
dmErrReadOnly
-
dbRef
references a non-schema database that is open in read-only mode. Non-schema databases must be open for writing -
dmErrOperationAborted
- The Palm OS device doesn't support the automatic database backup feature.
Comments
Use this function to cause an open database to be backed up.
Many devices running Palm OS Cobalt version 6.1 will back up the contents of the RAM storage heaps to some sort of non-volatile NAND flash. In the event that the RAM storage heaps are corrupted or are lost for some reason, the storage heaps can then be restored to their saved state. Backup is automatically triggered on a limited set of events: database close, database create, a call to DmSetDatabaseInfo()
, or upon device sleep (open databases only). Developers can explicitly cause a database to be backed up by calling DmInitiateAutoBackupOfOpenDatabase()
.
For additional information on this feature, see "Automatic Database Backup and Restore."
DmInsertionSort Function
Purpose
Declared In
DataMgr.h
Prototype
status_t DmInsertionSort ( const DmOpenRefdbR
, DmCompareFunctionType*compar
, int16_tother
)
Parameters
-
→ dbR
- Database access pointer.
-
→ compar
- Comparison function. See
DmCompareFunctionType()
. -
→ other
- Any value the application wants to pass to the comparison function. This parameter is often used to indicate a sort direction (ascending or descending).
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
dmErrNotRecordDB
- You've attempted to perform a record function on a resource database.
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
DmMoveCategory Function
Purpose
Move all records in a category to another category.
Declared In
DataMgr.h
Prototype
status_t DmMoveCategory ( DmOpenRefdbRef
, uint16_ttoCategory
, uint16_tfromCategory
, BooleanfDirty
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ toCategory
- Category to which the records should be added.
-
→ fromCategory
- Category from which to remove records.
-
→ fDirty
- If
true
, set the dirty bit.
Returns
Returns errNone
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 fDirty
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 DmGetRecordCategory()
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; //assume that this is set uint16_t rec1Index, rec2Index; //assume that these are set status_t err; uint8_t category1, category2; err = DmGetRecordCategory(myDb, rec1Index, &category1); err = DmGetRecordCategory(myDb, rec2Index, &category2); if (category1 != category2) DmMoveCategory(myDB, category1, category2, true);
DmMoveRecord Function
Purpose
Move a record from one index to another.
Declared In
DataMgr.h
Prototype
status_t DmMoveRecord ( DmOpenRefdbRef
, uint16_tfrom
, uint16_tto
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ from
- Index of record to move.
-
→ to
- Where to move the record.
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
dmErrIndexOutOfRange
- The specified index is out of range.
-
dmErrNotRecordDB
- You've attempted to perform a record function on a resource database.
-
dmErrMemError
- A memory error occurred.
-
memErrInvalidParam
- A memory error occurred.
-
memErrChunkLocked
- The associated memory chunk is locked.
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 Function
Purpose
Attempt to allocate a new chunk in the storage heap.
Declared In
DataMgr.h
Prototype
MemHandle DmNewHandle ( DmOpenRefdbRef
, uint32_tsize
)
Parameters
Returns
Returns a handle to the 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. You can attach the handle to the database as a record to obtain and save its record ID 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 Function
Purpose
Return a handle to a new record in the database and mark the record busy.
Declared In
DataMgr.h
Prototype
MemHandle DmNewRecord ( DmOpenRefdbRef
, uint16_t*atP
, uint32_tsize
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
↔ atP
- Pointer to index where new record should be placed. Specify the value
dmMaxRecordIndex
to add the record to the end of the database. -
→ size
- Size of new record.
Returns
Handle to record data. If an error occurs, this function returns 0 and DmGetLastErr()
returns an error code indicating the reason for failure.
Some releases may display a fatal error message if the database is opened in read-only mode or it is a resource database.
Comments
Allocates a new record of the given size, and returns a handle to the record data. The parameter atP
points to an index variable. The new record is inserted at index *
atP
and all record indices that follow are shifted down. If *
atP
is greater than the number of records currently in the database, the new record is appended to the end and its index is returned in *
atP
.
Both the busy
and dirty
bits are set for the new record and a unique ID is automatically created.
DmReleaseRecord()
should be called as soon as the caller finishes viewing or editing the record.
See Also
DmAttachRecord()
, DmRemoveRecord()
, DmDeleteRecord()
DmNewResource Function
Purpose
Allocate and add a new resource to a resource database.
Declared In
DataMgr.h
Prototype
MemHandle DmNewResource ( DmOpenRefdbRef
, DmResourceTyperesType
, DmResourceIDresID
, uint32_tsize
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ resType
- Type of the new resource.
-
→ resID
- ID of the new resource.
-
→ size
- Desired size of the new resource.
Returns
Returns a handle to the new resource. If an error occurs, this function returns NULL
and DmGetLastErr()
returns an error code indicating the reason for failure.
May display a fatal error message if the database is not a resource database.
Comments
Allocates a memory chunk for a new resource and adds it to the given resource database. The new resource has the given type and ID. If successful, the application should call DmReleaseResource()
as soon as it finishes initializing the resource.
See Also
DmAttachResource()
, DmRemoveResource()
DmNextOpenDatabase Function
Purpose
Return a DmOpenRef
to the next open database for the current task.
Declared In
DataMgr.h
Prototype
DmOpenRef DmNextOpenDatabase (
DmOpenRef dbRef
)
Parameters
Returns
DmOpenRef
to the next open database, or NULL
if there are no more.
Comments
Call this function successively to get the DmOpenRefs
of all open databases. Pass NULL
for dbRef
to get the first one. Applications don't usually call this function, but is useful for system information.
Note that unlike DmNextOpenDatabaseV50()
, this function doesn't find databases that have been added to the resource search chain using functions such as DmOpenDatabaseV50()
.
IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.
See Also
DmDatabaseInfo()
, DmOpenDatabaseInfoV50()
DmNextOpenDatabaseV50 Function
Purpose
Return DmOpenRef
to the next open database in the current task's search chain.
Declared In
DataMgr.h
Prototype
DmOpenRef DmNextOpenDatabaseV50 (
DmOpenRef dbRef
)
Parameters
Returns
DmOpenRef
to next open database, or NULL
if there are no more.
Comments
Call this function successively to get the DmOpenRefs
of all open databases. Pass NULL
for dbRef
to get the first one. Applications don't usually call this function, but is useful for system information.
This function is provided for backwards compatibility with 68K-based applications. Unlike DmNextOpenDatabase()
, this function does find databases that have been added to the resource search chain using functions such as DmOpenDatabaseV50()
.
IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.
Compatibility
This function—and the concept of a resource search chain—are provided to ease the porting of applications from an earlier version of Palm OS. Palm OS Cobalt applications should use DmNextOpenDatabase()
instead.
See Also
DmDatabaseInfo()
, DmOpenDatabaseInfoV50()
DmNextOpenResDatabase Function
Purpose
Return an access pointer to next open resource database in the current task.
Declared In
DataMgr.h
Prototype
DmOpenRef DmNextOpenResDatabase (
DmOpenRef dbRef
)
Parameters
Returns
Pointer to next open resource database.
Comments
Returns a pointer to next open resource database. To get a pointer to the first one in the list, pass NULL
for dbRef
.
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 overlay 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 DmGet1ResourceV50()
to obtain a resource. Both of those functions search both the overlay databases and their associated base databases.
IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.
DmNextOpenResDatabaseV50 Function
Purpose
Return access pointer to next open resource database in the current task's search chain.
Declared In
DataMgr.h
Prototype
DmOpenRef DmNextOpenResDatabaseV50 (
DmOpenRef dbRef
)
Parameters
Returns
Pointer to next open resource database.
Comments
Returns pointer to next open resource database. To get a pointer to the first one in the search chain, pass NULL
for dbRef
. This is the database that is searched when DmGet1ResourceV50()
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 DmGet1ResourceV50()
to obtain a resource. Both of those functions search both the overlay databases and their associated base databases.
IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.
Compatibility
This function—and the concept of a resource search chain—are provided to ease the porting of applications from an earlier version of Palm OS. Palm OS Cobalt applications should use DmNextOpenResDatabase()
instead.
DmNumDatabases Function
Purpose
Determine how many databases reside in memory.
Declared In
DataMgr.h
Prototype
uint16_t DmNumDatabases ( void )
Parameters
Returns
The number of databases found.
Comments
The returned value doesn't include databases on expansion media (such as an SD card).
See Also
DmGetNextDatabaseByTypeCreator()
DmNumDatabasesV50 Function
Purpose
Determine how many classic databases or extended resource database reside in either RAM or ROM.
Declared In
DataMgr.h
Prototype
uint16_t DmNumDatabasesV50 (
uint16_t cardNo
)
Parameters
Returns
The number of databases found.
Comments
This function is helpful for getting a directory of all databases on a card. DmGetDatabaseV50()
accepts an index from 0 to DmNumDatabases()
-1 and returns a database ID by index.
Compatibility
This function only returns the number of classic databases residing in RAM. Palm OS Cobalt applications should use DmNumDatabases()
instead.
See Also
DmNumRecords Function
Purpose
Return the number of records in a database.
Declared In
DataMgr.h
Prototype
uint16_t DmNumRecords (
DmOpenRef dbRef
)
Parameters
Returns
The number of records in a database.
Comments
Records that have that have the deleted
bit set (that is, records that will be deleted during the next HotSync operation 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()
, DmRecordInfoV50()
, DmSetRecordInfoV50()
DmNumRecordsInCategory Function
Purpose
Return the number of records of a specified category in a database.
Declared In
DataMgr.h
Prototype
uint16_t DmNumRecordsInCategory ( DmOpenRefdbRef
, uint16_tcategory
)
Parameters
Returns
The number of records in the category.
Comments
Because this function must examine all records in the database, it can be slow to return, especially when called on a large database.
Records that have the deleted
bit set are not counted, and if the user has specified to hide or mask private records, private records are not counted either.
You can use the DmGetRecordCategory()
call to obtain a category index from a given record. For example:
DmOpenRef myDB; //assume that this is set uint16_t recIndex; //assume that this is set status_t err; uint8_t category; uint16_t total; err = DmGetRecordCategory(myDb, recIndex, &category); total = DmNumRecordsInCategory(myDB, category);
See Also
DmNumRecords()
, DmQueryNextInCategory()
, DmGetPositionInCategory()
, DmFindRecordByOffsetInCategory()
, DmMoveCategory()
DmNumResources Function
Purpose
Return the total number of resources in a given resource database.
Declared In
DataMgr.h
Prototype
uint16_t DmNumResources (
DmOpenRef dbRef
)
Parameters
Returns
The total number of resources in the given database.
May display a fatal error message if the database is not a resource database.
Comments
DmNumResources()
counts only 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 returns only the number of resources in the base database, not in the overlay.
DmOpenDatabase Function
Purpose
Open a non-schema database and return a reference to it. If the database is a resource database, also open its overlay for the current locale.
Declared In
DataMgr.h
Prototype
DmOpenRef DmOpenDatabase ( DatabaseIDdbID
, DmOpenModeTypemode
)
Parameters
-
→ dbID
- Database ID of the database.
-
→ mode
- Which mode to open the database in (see
DmOpenModeType
).
Returns
Returns a DmOpenRef
to the open database. On error, unlike DmOpenDatabaseV50()
, no fatal error is displayed; this function simply returns 0 and DmGetLastErr()
returns an error code indicating the reason for failure.
Comments
Call this function to open a database for reading or writing.
This function 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 function 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 DmGetOverlayLocale()
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 DmGet1ResourceV50()
, 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.
IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.
See Also
DbOpenDatabase()
, DmCloseDatabase()
, DmCreateDatabase()
, DmFindDatabase()
, DmOpenDatabaseByTypeCreator()
, DmDeleteDatabase()
, DmOpenDBNoOverlay()
DmOpenDatabaseByTypeCreator Function
Purpose
Open the most recent revision of a database with the given type and creator. If the database is a resource database, also open its overlay for the current locale.
Declared In
DataMgr.h
Prototype
DmOpenRef DmOpenDatabaseByTypeCreator ( uint32_ttype
, uint32_tcreator
, DmOpenModeTypemode
)
Parameters
-
→ type
- Type of database.
-
→ creator
- Creator of database.
-
→ mode
- Which mode to open database in (see
DmOpenModeType
).
Returns
DmOpenRef
to open database. Unlike DmOpenDatabaseByTypeCreatorV50()
, no fatal error message is displayed; if the database couldn't be found this function simply returns 0 and DmGetLastErr()
returns an error code indicating the reason for failure.
Comments
If you use this function 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.
IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.
See Also
DmFindDatabaseByTypeCreator()
, DmOpenDatabase()
DmOpenDBNoOverlay()
DmOpenIteratorByTypeCreator()
DmOpenDatabaseByTypeCreatorV50 Function
Purpose
Opens the most recent revision of a classic database or extended resource database with the given type and creator. If the database is a resource database, either classic or extended, this function also opens its overlay for the current locale.
Declared In
DataMgr.h
Prototype
DmOpenRef DmOpenDatabaseByTypeCreatorV50 ( uint32_ttype
, uint32_tcreator
, DmOpenModeTypemode
)
Parameters
-
→ type
- Type of database.
-
→ creator
- Creator of database.
-
→ mode
- Which mode to open database in (see
DmOpenModeType
).
Returns
DmOpenRef
to open database. If the database couldn't be found this function returns 0 and DmGetLastErr()
returns an error code indicating the reason for failure.
Comments
If you use this function 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.
IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.
Compatibility
This function operates only on classic databases, and exists for compatibility purposes only. Palm OS Cobalt applications should use DmOpenDatabaseByTypeCreator()
instead.
See Also
DmOpenDatabaseByTypeCreator()
, DmCreateDatabase()
, DmOpenDatabase()
, DmOpenDatabaseInfoV50()
, DmCloseDatabase()
, DmOpenDBNoOverlay()
DmOpenDatabaseInfoV50 Function
Purpose
Retrieve information about an open database.
Declared In
DataMgr.h
Prototype
status_t DmOpenDatabaseInfoV50 ( DmOpenRefdbRef
, LocalID*pDbID
, uint16_t*pOpenCount
, DmOpenModeType*pMode
, uint16_t*pCardNo
, Boolean*pResDB
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
← pDbID
- The ID of the database. Pass
NULL
for this parameter if you don't want to retrieve this information. -
← pOpenCount
- The number of applications that have this database open. Pass
NULL
for this parameter if you don't want to retrieve this information. -
← pMode
- The mode used to open the database (see
DmOpenModeType
). PassNULL
for this parameter if you don't want to retrieve this information. -
← pCardNo
- The number of the card on which this database resides. Pass
NULL
for this parameter if you don't want to retrieve this information. -
← pResDB
- If
true
upon return, the database is a resource database,false
otherwise. PassNULL
for this parameter if you don't want to retrieve this information.
Returns
Compatibility
This function is provided only to ease the porting of applications from previous versions of Palm OS. Palm OS Cobalt applications will want to use DmGetOpenInfo()
instead.
See Also
DmOpenDatabaseV50 Function
Purpose
Open a non-schema database and return a reference to it. If the database is a resource database, also open its overlay for the current locale.
Declared In
DataMgr.h
Prototype
DmOpenRef DmOpenDatabaseV50 ( uint16_tcardNo
, LocalIDdbID
, DmOpenModeTypemode
)
Parameters
-
→ cardNo
- Card number database resides on.
-
→ dbID
- The database ID of the database.
-
→ mode
- Which mode to open database in (see
DmOpenModeType
).
Returns
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 function to open a database for reading or writing.
This function 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 function 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 DmGetOverlayLocale()
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 DmGet1ResourceV50()
, 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. DmOpenDatabaseV50()
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, DmOpenDatabaseV50()
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
.
When DmOpenDatabaseV50()
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.
IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.
Compatibility
This function is provided only to ease the porting of applications from previous versions of Palm OS. Palm OS Cobalt applications will want to use DmOpenDatabase()
instead.
See Also
DmOpenDatabase()
, DmCloseDatabase()
, DmCreateDatabase()
, DmFindDatabase()
, DmOpenDatabaseByTypeCreator()
, DmDeleteDatabase()
, DmOpenDBNoOverlay()
DmOpenDBNoOverlay Function
Purpose
Open a non-schema database and return a reference to it.
Declared In
DataMgr.h
Prototype
DmOpenRef DmOpenDBNoOverlay ( DatabaseIDdbID
, DmOpenModeTypemode
)
Parameters
-
→ dbID
- Database ID of the database.
-
→ mode
- Which mode to open database in (see
DmOpenModeType
).
Returns
Returns a DmOpenRef
to the open database. Unlike DmOpenDBNoOverlayV50()
, no fatal error message is displayed; on error, this function simply returns 0 and DmGetLastErr()
returns an error code indicating the reason for failure.
Comments
Call this function to open a database for reading or writing, while ignoring any overlay databases that might be associated with it.
This function 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()
.
IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.
See Also
DmCloseDatabase()
, DmCreateDatabase()
, DmFindDatabase()
, DmOpenDatabaseByTypeCreator()
, DmDeleteDatabase()
, DmOpenDatabase()
DmOpenDBNoOverlayV50 Function
Purpose
Open a non-schema database and return a reference to it.
Declared In
DataMgr.h
Prototype
DmOpenRef DmOpenDBNoOverlayV50 ( uint16_tcardNo
, LocalIDdbID
, DmOpenModeTypemode
)
Parameters
-
→ cardNo
- Card number database resides on.
-
→ dbID
- The database ID of the database.
-
→ mode
- Which mode to open database in (see
DmOpenModeType
).
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 function to open a database for reading or writing, while ignoring any overlay databases that might be associated with it.
This function 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()
.
IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.
Compatibility
This function is provided only to ease the porting of applications from previous versions of Palm OS. Palm OS Cobalt applications will want to use DmOpenDBNoOverlay()
instead.
See Also
DmOpenDBNoOverlay()
, DmCloseDatabase()
, DmCreateDatabase()
, DmFindDatabase()
, DmOpenDatabaseByTypeCreator()
, DmDeleteDatabase()
, DmOpenDatabase()
DmOpenIteratorByTypeCreator Function
Purpose
Mark the start of an iteration through those databases that match a specified set of criteria.
Declared In
DataMgr.h
Prototype
status_t DmOpenIteratorByTypeCreator ( DmSearchStatePtrstateInfoP
, uint32_ttype
, uint32_tcreator
, BooleanonlyLatestVers
, DmFindTypefind
)
Parameters
-
→ stateInfoP
- Pointer to a
DmSearchStateType
structure that you have allocated. The iteration process uses this opaque structure to maintain its state. -
→ type
- Type of database to search for, pass
dmSearchWildcardID
to iterate through databases of all types. -
→ creator
- Creator of database to search for, pass
dmSearchWildcardID
to iterate through databases with all creator IDs. -
→ onlyLatestVers
- If
true
, only the latest version of a database with a given type and creator is returned. -
→ find
- Flags indicating the type of database to be searched for: schema, extended, classic, or a combination of the three. See
DmFindType
for more information.
Returns
Comments
See the comments under DmGetNextDatabaseByTypeCreator()
for an example of how this function is used.
See Also
DmGetNextDatabaseByTypeCreator()
, DmCloseIteratorByTypeCreator()
DmPtrResize Function
Purpose
Resize a storage heap chunk given a pointer to its data.
Declared In
DataMgr.h
Prototype
status_t DmPtrResize ( MemPtrp
, uint32_tnewSize
)
Parameters
Returns
Returns errNone
if the chunk was successfully resized, or one of the following if an error occurred:
-
dmErrInvalidParam
- The function received an invalid parameter.
-
memErrNotEnoughSpace
- A memory error occurred.
-
memErrChunkLocked
- The associated memory chunk is locked.
Comments
Call this function to resize a locked chunk. This function is always successful when shrinking the size of a chunk. When growing a chunk, it attempts to use free space immediately following the chunk.
See Also
DmPtrSize Function
Purpose
Return the size of a storage heap chunk given a pointer to its data.
Declared In
DataMgr.h
Prototype
uint32_t DmPtrSize (
MemPtr p
)
Parameters
Returns
The requested size of the chunk.
Comments
Call this function to get the original requested size of a chunk.
DmPtrUnlock Function
Purpose
Unlock a storage heap chunk, given a pointer to its data.
Declared In
DataMgr.h
Prototype
status_t DmPtrUnlock (
MemPtr p
)
Parameters
Returns
Returns errNone
if the chunk was successfully unlocked, or dmErrInvalidParam
if there was a problem with the chunk pointer.
Comments
A chunk must not be unlocked more times than it was locked.
See Also
DmQueryNextInCategory Function
Purpose
Return a handle to the next record in the specified category for reading only (does not set the busy
bit).
Declared In
DataMgr.h
Prototype
MemHandle DmQueryNextInCategory ( DmOpenRefdbRef
, uint16_t*pIndex
, uint16_tcategory
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
↔ pIndex
- Index of a known record (often retrieved with
DmGetPositionInCategory()
). If a "next" record is found, this index is updated to indicate that record. -
→ category
- Index of category to query, or
dmAllCategories
to find the next record in any category.
Returns
Returns a handle to the record, 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 *
pIndex
for a record that is in the specified category. If the record at *
pIndex
belongs to that category, then a handle to it is returned. If not, the function continues searching until it finds a record in the category.
Records that have the deleted
bit set are skipped, and if the user has specified that private records should be hidden or masked, private records are skipped as well.
Because this function begins searching the database at the record with the supplied index, 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; //assume that this is set uint16_t recIndex; //assume that this is set uint8_t category; status_t err; uint16_t pos; MemHandle newRecH; err = DmGetRecordCategory(myDb, recIndex, &category); pos = DmGetPositionInCategory(myDB, recIndex, category); pos++; //advance to next record newRecH = DmQueryNextInCategory(myDB, &pos, category);
See Also
DmNumRecordsInCategory()
, DmGetPositionInCategory()
, DmFindRecordByOffsetInCategory()
DmQueryRecord Function
Purpose
Return a handle to a record for reading only (does not set the busy
bit).
Declared In
DataMgr.h
Prototype
MemHandle DmQueryRecord ( DmOpenRefdbRef
, uint16_tindex
)
Parameters
Returns
Returns a record handle. If an error occurs, this function returns NULL
, and DmGetLastErr()
returns an error code indicating the reason for failure.
Some releases may display a fatal error message if the specified index is out of range.
Comments
Returns a handle to the given record. Use this function only when viewing the record. This function successfully returns a handle to the record even if the record is busy.
If the record is ROM-based (pointer accessed) this function returns the fake handle to it.
DmQuickSort Function
Purpose
Declared In
DataMgr.h
Prototype
status_t DmQuickSort ( const DmOpenRefdbR
, DmCompareFunctionType*compar
, int16_tother
)
Parameters
-
→ dbR
- Database access pointer.
-
→ compar
- Comparison function. See
DmCompareFunctionType()
. -
→ other
- Any value the application wants to pass to the comparison function. This parameter is often used to indicate a sort direction (ascending or descending).
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
dmErrNotRecordDB
- You've attempted to perform a record function on a resource database.
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 DmSortRecordInfoType
structure).
DmQuickSort()
contains its own stack to limit uncontrolled recursion. When the stack is full DmQuickSort()
instead performs an insertion sort. An insertion sort is also performed when the number of records is low, avoiding the noticeable overhead of a quick sort with a small number of records. Finally, if the records seem mostly sorted an insertion sort is performed to move only those records that need moving.
See Also
DmRecordInfoV50 Function
Purpose
Retrieve the record information stored in the database header.
Declared In
DataMgr.h
Prototype
status_t DmRecordInfoV50 ( DmOpenRefdbRef
, uint16_tindex
, uint16_t*pAttr
, uint32_t*pUID
, LocalID*pChunkID
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Index of the record.
-
← pAttr
- The record's attributes. See "Non-Schema Database Record Attributes." Pass
NULL
for this parameter if you don't want to retrieve this value. -
← pUID
- The record's unique ID. Pass
NULL
for this parameter if you don't want to retrieve this value. -
← pChunkID
- The record's local ID. Pass
NULL
for this parameter if you don't want to retrieve this value.
Returns
Returns errNone
if no error or dmErrIndexOutOfRange
if the specified record can't be found. Some releases may display a fatal error message instead of returning the error code.
Compatibility
This function is provided for compatibility purposes only. Palm OS Cobalt applications should use one or more of the functions listed in the See Also section, below, instead.
See Also
DmGetRecordAttr()
, DmGetRecordCategory()
, DmGetRecordID()
, DmQueryNextInCategory()
DmRecoverHandle Function
Purpose
Recover the handle of a storage heap chunk, given a pointer to its data.
Declared In
DataMgr.h
Prototype
MemHandle DmRecoverHandle (
MemPtr pChunk
)
Parameters
Returns
Returns the handle of the chunk, or 0 if unsuccessful.
Comments
Don't call this function for pointers in ROM.
DmReleaseRecord Function
Purpose
Clear the busy
bit for the given record and set the dirty
bit if fDirty
is true
.
Declared In
DataMgr.h
Prototype
status_t DmReleaseRecord ( DmOpenRefdbRef
, uint16_tindex
, BooleanfDirty
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- The record to unlock.
-
→ fDirty
- If
true
, set thedirty
bit.
Returns
Returns errNone
if no error, or dmErrIndexOutOfRange
if the specified index is out of range. Some releases may display a fatal error message instead of returning the error code.
Comments
Call this function when you finish modifying or reading a record that you've called DmGetRecord()
on or created using DmNewRecord()
.
See Also
DmReleaseResource Function
Purpose
Release a resource acquired with DmGetResource()
.
Declared In
DataMgr.h
Prototype
status_t DmReleaseResource (
MemHandle hResource
)
Parameters
Returns
Comments
Marks a resource as being no longer needed by the application.
See Also
DmGet1ResourceV50()
, DmGetResource()
DmRemoveRecord Function
Purpose
Remove a record from a database and dispose of its data chunk.
Declared In
DataMgr.h
Prototype
status_t DmRemoveRecord ( DmOpenRefdbRef
, uint16_tindex
)
Parameters
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
dmErrIndexOutOfRange
- The specified index is out of range.
-
dmErrNotRecordDB
- You've attempted to perform a record function on a resource database.
-
memErrChunkLocked
- The associated memory chunk is locked.
-
memErrInvalidParam
- A memory error occurred.
Some releases may display a fatal error message instead of returning the error code.
Comments
Disposes of the record's data chunk and removes the record's entry from the database header. DmRemoveRecord()
should only be used for newly-created records that have just been deleted or records that have never been synchronized.
See Also
DmDetachRecord()
, DmDeleteRecord()
, DmArchiveRecord()
, DmNewRecord()
DmRemoveResource Function
Purpose
Delete a resource from a resource database.
Declared In
DataMgr.h
Prototype
status_t DmRemoveResource ( DmOpenRefdbRef
, uint16_tindex
)
Parameters
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrCorruptDatabase
- The database is corrupted.
-
dmErrIndexOutOfRange
- The specified index is out of range.
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
memErrChunkLocked
- The associated memory chunk is locked.
-
memErrInvalidParam
- A memory error occurred.
-
memErrNotEnoughSpace
- A memory error occurred.
May display a fatal error message if the database is not a resource database.
Comments
This function disposes of the Memory Manager chunk that holds the given resource and removes its entry from the database header.
See Also
DmDetachResource()
, DmRemoveResource()
, DmAttachResource()
DmRemoveSecretRecords Function
Purpose
Declared In
DataMgr.h
Prototype
status_t DmRemoveSecretRecords (
DmOpenRef dbRef
)
Parameters
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
dmErrNotRecordDB
- You've attempted to perform a record function on a resource database.
Some releases may display a fatal error message instead of returning the error code.
See Also
DmRemoveRecord()
, DmRecordInfoV50()
, DmSetRecordInfoV50()
DmResetRecordStates Function
Purpose
For each record in a non-schema database, unlocks the record and clears the busy bit.
Declared In
DataMgr.h
Prototype
status_t DmResetRecordStates (
DmOpenRef dbRef
)
Parameters
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database, ordbRef
references a schema database. -
dmErrReadOnly
- The specified database isn't open for writing.
-
dmErrROMBased
- The specified database is located in ROM.
-
memErrInvalidParam
- A memory error occurred.
See Also
DmResizeRecord Function
Purpose
Declared In
DataMgr.h
Prototype
MemHandle DmResizeRecord ( DmOpenRefdbRef
, uint16_tindex
, uint32_tnewSize
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Which record to retrieve.
-
→ newSize
- New size of record.
Returns
Handle to resized record. Returns NULL
if there is not enough space to resize the record, and DmGetLastErr()
returns an error code indicating the reason for failure. Some releases may display a fatal error message instead of returning the error code.
Comments
As this function reallocates the record, the handle may change, so be sure to use the returned handle to access the resized record.
DmResizeResource Function
Purpose
Resize a resource and return the new handle.
Declared In
DataMgr.h
Prototype
MemHandle DmResizeResource ( MemHandlehResource
, uint32_tsize
)
Parameters
Returns
Returns a handle to newly sized resource. Returns NULL
if there is not enough space to resize the resource, and DmGetLastErr()
returns an error code indicating the reason for failure. Some releases may display a fatal error message instead of returning the error code.
Comments
Resizes the resource and returns a new handle.
The handle may change if the resource had to be reallocated in a different data heap because there was not enough space in its present data heap.
DmResourceInfo Function
Purpose
Retrieve information on a given resource.
Declared In
DataMgr.h
Prototype
status_t DmResourceInfo ( DmOpenRefdbRef
, uint16_tindex
, DmResourceType*pResType
, DmResourceID*pResID
, MemHandle*pChunkHandle
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Index of resource to get info on.
-
← pResType
- The resource type. Pass
NULL
if you don't want to retrieve this information. -
← pResID
- The resource ID. Pass
NULL
if you don't want to retrieve this information. -
← pChunkHandle
- Handle for the resource data. Pass
NULL
if you don't want to retrieve this information.
Returns
Returns errNone
if no error or dmErrIndexOutOfRange
if an error occurred. Unlike DmResourceInfoV50()
, no fatal error message is displayed if the database is not a resource database.
Comments
If dbRef
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()
, DmGet1ResourceV50()
, DmSetResourceInfo()
, DmFindResource()
, DmFindResourceType()
DmResourceInfoV50 Function
Purpose
Retrieve information on a given resource.
Declared In
DataMgr.h
Prototype
status_t DmResourceInfoV50 ( DmOpenRefdbRef
, uint16_tindex
, DmResourceType*pResType
, DmResourceID*pResID
, LocalID*pChunkLocalID
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Index of resource to get info on.
-
← pResType
- The resource type. Pass
NULL
if you don't want to retrieve this information. -
← pResID
- The resource ID. Pass
NULL
if you don't want to retrieve this information. -
← pChunkLocalID
- The Memory Manager local ID of the resource data. Pass
NULL
if you don't want to retrieve this information.
Returns
Returns errNone
if no error or dmErrIndexOutOfRange
if an error occurred. May display a fatal error message if the database is not a resource database.
Comments
If dbRef
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.
Compatibility
This function is provided for compatibility purposes only. Palm OS Cobalt applications should use DmResourceInfo()
instead.
See Also
DmResourceInfo()
, DmGetResource()
, DmGet1ResourceV50()
, DmSetResourceInfo()
, DmFindResource()
, DmFindResourceType()
DmRestoreFinalize Function
Purpose
Complete or abort an on-going database restore operation.
Declared In
DataMgr.h
Prototype
status_t DmRestoreFinalize ( DmBackupRestoreStatePtrpState
, BooleanfAbort
, BooleanfOverwrite
, DatabaseID*pDbID
)
Parameters
-
→ pState
- Pointer to a
DmBackupRestoreStateType
structure allocated by the caller and initialized withDmBackupInitialize()
. -
→ fAbort
- Set to
true
to abort an on-going backup operation, orfalse
to clean up after a successful backup. -
→ fOverwrite
- Set to
true
to overwrite an existing matching database (if there is one), orfalse
to leave the existing matching database intact. -
← pDbID
- Pointer to a variable that receives the identifier for the restored database, or
NULL
if the database identifier isn't needed.
Returns
Returns errNone
if the database image was successfully restored, dmErrOperationAborted
if the restore operation was cancelled, or one of the following errors otherwise:
-
dmErrInvalidParam
- One of the parameters is invalid or corrupt.
-
dmErrMemError
- A memory error occurred.
-
dmErrAlreadyExists
- The database being restored already exists, and the
fOverwrite
parameter was set tofalse
.
Comments
This function allows the Data Manager to perform a final clean up of the internal structures it allocated for the operation. Applications should always call this function after having started a restore operation, whether or not the restore completed successfully. See DmRestoreUpdate()
for sample code illustrating this function's use.
The restore operation can be used with schema, extended, or classic databases.
See Also
DmBackupFinalize()
, DmRestoreInitialize()
DmRestoreInitialize Function
Purpose
Initialize the Data Manager prior to starting a restore operation on the specified database.
Declared In
DataMgr.h
Prototype
status_t DmRestoreInitialize ( DmBackupRestoreStatePtrpState
, DmDatabaseInfoPtrpDbInfo
)
Parameters
-
→ pState
- Pointer to a
DmBackupRestoreStateType
structure allocated by the caller. -
→ pDbInfo
- Pointer to a
DmDatabaseInfoType
structure that will receive information about the database being restored. This structure will receive its information after you callDmRestoreUpdate()
. Set toNULL
if you don't want to receive this information.
Returns
Returns errNone
if the initialization was successful, or one of the following if an error occurred:
-
dmErrAccessDenied
- The caller was not authorized to perform a restore operation for the specified database.
-
dmErrInvalidParam
- One of the parameters is invalid or corrupt.
-
dmErrMemError
- A memory error occurred.
Comments
Use DmRestoreInitialize()
to start a database backup operation. See DmRestoreUpdate()
for sample code illustrating this function's use.
The restore operation can be used with schema, extended, or classic databases.
IMPORTANT: When called from the main application thread, this function may block. While blocked, the application will not receive events and won't redraw its windows. As well, deferred sublaunches and notifications won't execute while the main application thread is blocked.
See Also
DmBackupInitialize()
, DmRestoreFinalize()
DmRestoreUpdate Function
Purpose
Reassemble a database within the storage heap from a database image stream held within the specified buffer.
Declared In
DataMgr.h
Prototype
status_t DmRestoreUpdate ( DmBackupRestoreStatePtrpState
, MemPtrpBuffer
, uint32_tsize
, BooleanendOfData
, Boolean*pfDbInfoAvailable
)
Parameters
-
→ pState
- Pointer to a
DmBackupRestoreStateType
structure allocated by the caller and initialized withDmRestoreInitialize()
. -
→ pBuffer
- Pointer to a buffer to hold the backed-up database image that is being restored.
-
→ size
- Size, in bytes, of the database image data held within
pBuffer
. -
→ endOfData
- Set this parameter to
true
to indicate that there is no additional data (beyond what is inpBuffer
). Set it tofalse
if you will be making additional calls toDmRestoreUpdate()
. -
← pfDbInfoAvailable
- Pointer to a Boolean variable that is to indicate whether the information about the database being restored is available, or
NULL
if you don't need the database information. If true, the information was written to theDmDatabaseInfoType
structure you specified when callingDmRestoreInitialize()
.
Returns
Returns errNone
if the operation was successful, or one of the following if an error occurred:
-
dmErrInvalidParam
- One of the parameters is invalid or corrupt.
-
dmErrMemError
- A memory error occurred which prevented the restore operation from continuing.
Comments
Use this function, along with DmRestoreInitialize()
and DmRestoreFinalize()
, to restore a schema, extended, or classic database from its serial image.
If the serial image doesn't reside in a single buffer, you'll need to call this function several times before you've completely restored the complete database. Call DmRestoreUpdate()
as many times as required until all of the database image data has been successfully processed by this function. For all but the last call to this function, endOfData
must be set to false
. The last time you call it, set endOfData
to true
(note that the last call needn't contain any data in pBuffer
; see the example, below, for code that does this). Finally, call DmRestoreFinalize()
to complete the operation and have the database once again accessible from the Data Manager's database directory list.
If pfDbInfoAvailable
is not NULL
, DmRestoreUpdate()
sets the pointed-to Boolean variable to true
when it has received enough of the database image to be able to return information about it. The actual database information is returned through the DmDatabaseInfoType
structure that you specified when calling DmRestoreInitialize()
.
If DmRestoreUpdate()
returns an error code other than errNone
, the operation has been aborted due to a fatal error. You must still perform a call to DmRestoreFinalize()
to let the Data Manager perform a final cleanup of the internal structures it allocated for the operation.
Example
This sample code shows how to use DmRestoreInitialize()
, DmRestoreUpdate()
, and DmRestoreFinalize()
to restore database from a serial image. This code employs a fictitious DoesUserWantToOverwrite()
function to let the user decide whether to overwrite a matching database (if any).
status_t error; DatabaseID dbID; DmBackupRestoreStateType restoreState; char buffer[BUFFER_SIZE]; uint32_t size; Boolean fAbort; Boolean fGotDbInfo; Boolean fDone = false; Boolean fOverwrite = false; Boolean fAlreadyAsked = false; DmDatabaseInfoType databaseInfo; char dbName[dmDBNameLength]; uint32_t type; uint32_t creator; uint16_t attributes; // Set up the DmDatabaseInfoType structure so that we will // get the information we want about the database being // restored... MemSet(&databaseInfo, sizeof(databaseInfo), 0); databaseInfo.pName = dbName; databaseInfo.pType = &type; databaseInfo.pCreator = &creator; databaseInfo.pAttributes = &attributes; error = DmRestoreInitialize(&restoreState, &databaseInfo); if (error == errNone) { do { size = sizeof(buffer); // Get a chunk from the database image data out of some // I/O channel. We assume this function returns false // when there is no more data to receive for the // database image. if (GetDatabaseImageData(buffer, &size)) { error = DmRestoreUpdate(&restoreState, buffer, size, false, &fGotDbInfo); // Set the abort flag if we got back an error or if // the user decided to cancel the operation... fAbort = (error != errNone) | DidUserCancel(); if (!fAbort && fGotDbInfo && !fAlreadyAsked) { // We just got the database info we asked so now // we ask the user whether they want to // overwrite the existing database with this // one... fOverwrite = DoesUserWantToOverwrite(&pDbInfo, &fFoundDb); // If the user doesn't want to overwrite and we // found an existing database in the storage // heap, then set the abort flag to break out of // the loop. fAbort = !fOverwrite && fFoundDb; // Use this flag to make sure we don't ask the // user twice (or more) the same question in case // where we didn't find a matching database or // they wanted to overwrite anyway... fAlreadyAsked = true; } } else fDone = true; } while(!fDone && !fAbort); // call DmRestoreUpdate one last time with no data and // with the endOfData flag set to mark the end of data error = DmRestoreUpdate(&restoreState, buffer, size, true, &fGotDbInfo); // Always call DmRestoreFinalize to complete the restore // operation ... error = DmRestoreFinalize(&restoreState, fAbort, fOverwrite, &dbID); } if (error == errNone) { // Restore operation completed successfully... // Now we can use the dbID we got back to operate on the // newly-restored database. Note also that we can also use // the database information we got back during the restore // operation. } else { // A fatal error occurred... if (error == dmErrOperationAborted) { // The user aborted. Handle it. } else if (error == dmErrAlreadyExists) { // The database already exists! Handle this. } else { // Some other error occurred. } }
See Also
DmBackupUpdate()
, DmCreateDatabaseFromImage()
DmSearchRecordOpenDatabases Function
Purpose
Search all open record databases for a record with the handle passed.
Declared In
DataMgr.h
Prototype
uint16_t DmSearchRecordOpenDatabases ( MemHandlehRecord
, DmOpenRef*pDbRef
)
Parameters
Returns
Returns the index of the record and database access pointer; if not found, returns -1 and *
pDbRef
is 0.
See Also
DmGetRecord()
, DmFindRecordByID()
, DmRecordInfoV50()
DmSearchResourceOpenDatabases Function
Purpose
Search all open resource databases for a resource by type and ID, or by pointer if it is non-NULL
.
Declared In
DataMgr.h
Prototype
uint16_t DmSearchResourceOpenDatabases ( DmResourceTyperesType
, DmResourceIDresID
, MemHandlehResource
, DmOpenRef*pDbRef
)
Parameters
-
→ resType
- Type of resource to search for.
-
→ resID
- ID of resource to search for.
-
→ hResource
- Handle of locked resource, or
NULL
. -
← pDbRef
- The resource database that contains the specified resource.
Returns
Returns the index of the resource, stores DmOpenRef
in *
pDbRef
.
Comments
This function can be used to find a resource in all open resource databases by type and ID or by pointer. If hResource
is NULL
, the resource is searched for by type and ID. If hResource
is not NULL
, resType
and resID
is ignored and the index of the resource handle is returned. On return, *
pDbRef
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 DmGetResourceByIndex()
.
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 pDbRef
return value is a pointer to the overlay database, not the base resource database.
See Also
DmGetResource()
, DmFindResourceType()
, DmResourceInfo()
, DmFindResource()
DmSet Function
Purpose
Write a specified value into a section of a record. This function also checks the validity of the pointer for the record and makes sure the writing of the record information doesn't exceed the bounds of the record.
Declared In
DataMgr.h
Prototype
status_t DmSet ( void*pRecord
, uint32_toffset
, uint32_tbytes
, uint8_tvalue
)
Parameters
-
→ pRecord
- Pointer to locked data record (chunk pointer).
-
→ offset
- Offset within record to start writing.
-
→ bytes
- Number of bytes to write.
-
→ value
- Byte value to write.
Returns
Returns errNone
if no error. May display a fatal error message if the record pointer is invalid or the function overwrites the record.
Comments
Must be used to write to Data Manager records because the data storage area is write-protected.
See Also
DmSetDatabaseInfo Function
Purpose
Set information about a database.
Declared In
DataMgr.h
Prototype
status_t DmSetDatabaseInfo ( DatabaseIDdbID
, DmDatabaseInfoPtrpDatabaseInfo
)
Parameters
-
→ dbID
- Database ID of the database.
-
→ pDatabaseInfo
- Pointer to a structure that contains references to the new database information. See
DmDatabaseInfoType
for a description of the data structure.
Returns
Returns errNone
if no error or one of the following if an error occurred:
-
dmErrInvalidDatabaseName
- The name you've specified for the database is invalid.
-
dmErrAlreadyExists
- Another database with the same name already exists.
-
dmErrInvalidParam
- The function received an invalid parameter.
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 un-orphaned. Consequently, you shouldn't replace an existing appInfoID
or sortInfoID
if that chunk has already been attached to another database.
Call this function to set any or all information about a database except for the database ID. This function sets the new value for any non-NULL
field in the pDatabaseInfo
structure.
See Also
DmDatabaseInfo()
, DmOpenDatabaseInfoV50()
, DmFindDatabase()
, DmGetNextDatabaseByTypeCreator()
, TimDateTimeToSeconds()
DmSetDatabaseInfoV50 Function
Purpose
Set information about a database.
Declared In
DataMgr.h
Prototype
status_t DmSetDatabaseInfoV50 ( uint16_tcardNo
, LocalIDdbID
, const char*nameP
, uint16_t*attributesP
, uint16_t*versionP
, uint32_t*crDateP
, uint32_t*modDateP
, uint32_t*bckUpDateP
, uint32_t*modNumP
, LocalID*appInfoIDP
, LocalID*sortInfoIDP
, uint32_t*typeP
, uint32_t*creatorP
)
Parameters
-
→ cardNo
- Card number the database resides on.
-
→ dbID
- Database ID of the database.
-
→ nameP
- Pointer to the new name of the database, or
NULL
. A database name can be up to 32 ASCII bytes long, including the null terminator (as specified bydmDBNameLength
). Database names must use only 7-bit ASCII characters (0x20 through 0x7E). -
→ attributesP
- Pointer to new attributes variable, or
NULL
. See "Database Attributes" 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
, orNULL
. -
→ sortInfoIDP
- Pointer to new
sortInfoID
, orNULL
. -
→ typeP
- Pointer to new
type
, orNULL
. -
→ creatorP
- Pointer to new
creator
, orNULL
.
Returns
Returns errNone
if no error or one of the following if an error occurred:
-
dmErrInvalidDatabaseName
- The name you've specified for the database is invalid.
-
dmErrAlreadyExists
- Another database with the same name already exists.
-
dmErrInvalidParam
- The function received an invalid parameter.
Comments
When this call changes appInfoID
or sortInfoID
, the old chunk ID (if any) is marked as an orphaned chunk2 and the new chunk ID is un-orphaned. Consequently, you shouldn't replace an existing appInfoID
or sortInfoID
if that chunk has already been attached to another database.
Call this function to set any or all information about a database except for the card number and database ID. This function sets the new value for any non-NULL
parameter.
When setting database attributes, note that the following are system attributes that cannot be set—they are read-only:
Compatibility
This function is provided for compatibility purposes only. Although it could be used to set information in an extended database, it operates as on previous versions of Palm OS in that the given database name must be unique. Palm OS Cobalt applications—particularly those that are operating on extended databases—will most likely want to use DmSetDatabaseInfo()
instead.
See Also
DmSetDatabaseInfo()
, DmDatabaseInfo()
, DmOpenDatabaseV50()
, DmFindDatabase()
, DmGetNextDatabaseByTypeCreator()
, TimDateTimeToSeconds()
DmSetDatabaseProtection Function
Purpose
Increment or decrement the database's protection count.
Declared In
DataMgr.h
Prototype
status_t DmSetDatabaseProtection ( DatabaseIDdbID
, Booleanprotect
)
Parameters
-
→ dbID
- Database ID of the database.
-
→ protect
- If
true
, the protection count is incremented. Iffalse
, the protection count is decremented.
Returns
Returns errNone
if the protection count was updated, or one of the following if an error occurred:
-
memErrCardNotPresent
- The specified card can't be found.
-
dmErrROMBased
- You've attempted to delete or modify a ROM-based database.
-
dmErrCantFind
- The specified database can't be found.
-
memErrNotEnoughSpace
- A memory error occurred.
-
dmErrDatabaseNotProtected
Comments
This function can be used to prevent a database from being deleted (pass true
for the protect
parameter). All "true" calls should be balanced by "false" calls before the application terminates.
Use this function to keep a particular record or resource in a database locked down without having to keep the database open. Note that because protection counts are kept in the dynamic heap, 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 function.
DmSetFallbackOverlayLocale Function
Purpose
Set the fallback overlay locale: the locale used when the Data Manager attempts to open an overlay locale for which no valid overlay exists.
Declared In
DataMgr.h
Prototype
status_t DmSetFallbackOverlayLocale (
const LmLocaleType *fallbackLocale
)
Parameters
Returns
Returns errNone
if the fallback overlay locale was successfully set, or one of the following if an error occurred:
-
dmErrInvalidParam
- The function received an invalid parameter.
-
dmErrUnknownLocale
- The specified locale is unknown to the operating system.
Comments
The fallback overlay locale is used by the Data Manager when it attempts to automatically open an overlay using the overlay locale, but no valid overlay exists, and the base probably has been stripped.
See Also
DmGetFallbackOverlayLocale()
, DmSetOverlayLocale()
DmSetOverlayLocale Function
Purpose
Set the Data Manager's overlay locale: the locale used by the Data Manager when it attempts to automatically open overlays.
Declared In
DataMgr.h
Prototype
status_t DmSetOverlayLocale (
const LmLocaleType *overlayLocale
)
Parameters
Returns
Returns errNone
if the overlay locale was successfully set, or one of the following if an error occurred:
-
dmErrInvalidParam
- The function received an invalid parameter.
-
dmErrUnknownLocale
- The specified locale is unknown to the operating system.
See Also
DmGetOverlayLocale()
, DmSetFallbackOverlayLocale()
DmSetRecordAttr Function
Purpose
Set the attributes of a record.
Declared In
DataMgr.h
Prototype
status_t DmSetRecordAttr ( DmOpenRefdbRef
, uint16_tindex
, uint8_t*pAttr
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Index of the record for which attributes are being set.
-
→ pAttr
- Pointer to the new attributes for the record. See "Non-Schema Database Record Attributes" for a description of the attributes. Note that you can only set those attributes not included in the definition of
dmSysOnlyRecAttrs
.
Returns
Returns errNone
if the attributes were successfully set, or one of the following if an error occurred:
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
dmErrNotRecordDB
- You've attempted to perform a record function on a resource database.
-
dmErrIndexOutOfRange
- The specified index is out of range.
See Also
DmSetRecordCategory Function
Purpose
Set the category information for a record.
Declared In
DataMgr.h
Prototype
status_t DmSetRecordCategory ( DmOpenRefdbRef
, uint16_tindex
, uint8_t*pCategory
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Index of the record for which the category information is being set.
-
→ pCategory
- Pointer to the new category information for the record.
Returns
Returns errNone
if the category information was successfully set, or one of the following if an error occurred:
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
dmErrNotRecordDB
- You've attempted to perform a record function on a resource database.
-
dmErrIndexOutOfRange
- The specified index is out of range.
See Also
DmSetRecordID Function
Purpose
Set the unique ID of a record.
Declared In
DataMgr.h
Prototype
status_t DmSetRecordID ( DmOpenRefdbRef
, uint16_tindex
, uint32_t*pUID
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Record index for which to set the unique ID.
-
→ pUID
- Pointer to the new unique ID.
Returns
Returns errNone
if the record ID was set successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
- The function received an invalid parameter.
-
dmErrNotRecordDB
- You've attempted to perform a record function on a resource database.
-
dmErrIndexOutOfRange
- The specified index is out of range.
-
dmErrInvalidID
- The supplied record ID is already in use.
Comments
The Data Manager guarantees that a record ID's uniqueness is maintained after such a call. If the supplied record ID is already in use by another record, this function returns dmErrInvalidID
.
See Also
DmGetRecordID()
, DmSetRecordInfoV50()
DmSetRecordInfoV50 Function
Purpose
Set record information stored in the database header.
Declared In
DataMgr.h
Prototype
status_t DmSetRecordInfoV50 ( DmOpenRefdbRef
, uint16_tindex
, uint16_t*pAttr
, uint32_t*pUID
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Index of record.
-
→ pAttr
- Pointer to new attribute variable, or
NULL
if you don't want to change any of the record's attributes. See "Non-Schema Database Record Attributes" for a list of possible values. -
→ pUID
- Pointer to new unique ID, or
NULL
if you don't want to change the record's unique ID.
Returns
Returns errNone
if no error, or one of the following if an error occurred:
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
dmErrNotRecordDB
- You've attempted to perform a record function on a resource database.
-
dmErrIndexOutOfRange
- The specified index is out of range.
Some releases may display a fatal error message instead of returning the error code.
Comments
Sets information about a record. This function cannot be used to set the dmRecAttrBusy
bit; instead, use DmGetRecord()
to set the bit and DmReleaseRecord()
to clear it.
Normally, the unique ID for a record is automatically created by the Data Manager when a record is created using DmNewRecord()
, so an application would not typically change the unique ID.
Compatibility
Provided for compatibility purposes only. Palm OS Cobalt applications should use DmSetRecordAttr()
and/or DmSetRecordID()
instead.
See Also
DmSetRecordAttr()
, DmSetRecordID()
, DmGetRecordAttr()
, DmGetRecordID()
, DmRecordInfoV50()
DmSetResourceInfo Function
Purpose
Set information on a given resource.
Declared In
DataMgr.h
Prototype
status_t DmSetResourceInfo ( DmOpenRefdbRef
, uint16_tindex
, DmResourceType*pResType
, DmResourceID*pResID
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Index of resource to set info for.
-
→ pResType
- Pointer to new
resType
(resource type), orNULL
. -
→ pResID
- Pointer to new resource ID, or
NULL
.
Returns
Returns errNone
if no error, or one of the following if an error occurred:
-
dmErrIndexOutOfRange
- The specified index is out of range.
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
May display a fatal error message if the database is not a resource database.
Comments
Use this function 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 *
pResType
and *
pResID
.
DmStrCopy Function
Purpose
Copies a string to a record within a database that is open for writing.
Declared In
DataMgr.h
Prototype
status_t DmStrCopy ( void*pRecord
, uint32_toffset
, const void*pSrc
)
Parameters
-
↔ pRecord
- Pointer to data record (chunk pointer).
-
→ offset
- Offset within record to start writing.
-
→ pSrc
- Pointer to null-terminated string.
Returns
Returns errNone
if no error. May display a fatal error message if the record pointer is invalid or the function overwrites the record.
Comments
This is one of the functions 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 function checks the validity of the chunk pointer for the record to ensure 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
DmWrite Function
Purpose
Copies a specified number of bytes to a record within a database that is open for writing.
Declared In
DataMgr.h
Prototype
status_t DmWrite ( void*pRecord
, uint32_toffset
, const void*pSrc
, uint32_tbytes
)
Parameters
-
↔ pRecord
- Pointer to locked data record (chunk pointer).
-
→ offset
- Offset within record to start writing.
-
→ pSrc
- Pointer to data to copy into record.
-
→ bytes
- Number of bytes to write.
Returns
Returns errNone
if no error. May display a fatal error message if the record pointer is invalid or the function overwrites the record.
Comments
This is one of the functions 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 function checks the validity of the chunk pointer for the record to ensure that writing the record will not exceed the chunk bounds.
See Also
DmWriteCheckV50 Function
Purpose
Check the parameters of a write operation to a classic database data storage chunk before actually performing the write.
Declared In
DataMgr.h
Prototype
status_t DmWriteCheckV50 ( void*pRecord
, uint32_toffset
, uint32_tbytes
)
Parameters
-
→ pRecord
- Locked pointer to the record handle.
-
→ offset
- Offset into record to start writing.
-
→ bytes
- Number of bytes to write.
Returns
Returns errNone
if no error; returns dmErrNotValidRecord
or dmErrWriteOutOfBounds
if an error occurred.
Compatibility
This function operates only with classic databases, and is provided only for compatibility purposes. Palm OS Cobalt applications should go ahead and write the data using a function such as DmWrite()
, checking the returned status code to determine if an error occurred.
Application-Defined Functions
DmCompareFunctionType Function
Purpose
Compares two records in a classic database.
Declared In
DataMgr.h
Prototype
int16_t DmCompareFunctionType ( void*rec1P
, void*rec2P
, int16_tother
, DmSortRecordInfoPtrrec1SortInfoP
, DmSortRecordInfoPtrrec2SortInfoP
, MemHandleappInfoH
)
Parameters
-
→ rec1P
- Pointer to the first record to compare.
-
→ rec2P
- Pointer to the second record 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).
-
→ rec1SortInfoP
- Pointer to a
DmSortRecordInfoType
structure that specifies unique sorting information for the first record. -
→ rec2SortInfoP
- Pointer to a
DmSortRecordInfoType
structure that specifies unique sorting information for the second record. -
→ appInfoH
- A handle to the database's Application Info block.
Returns
Your implementation of this function should return:
Comments
This function is used to sort the records in a database. It is specifically called by DmGetRecordSortPosition()
, DmInsertionSort()
, and DmQuickSort()
.
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 Application Info block, or the like, and if the application doesn't keep track of it—in a global variable, perhaps—it could get lost. If the application doesn't get around to freeing the chunk before it quits or crashes, or before the device is reset, that storage will be forever unusable: the user can't delete it since the user only deletes databases.
1.
1. During a soft reset, the OS walks through the storage heap and frees any orphaned chunks that it finds. Since most users reset only rarely, however, you shouldn't rely on this happening.
2. 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 Application Info 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.
2.
2. 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.