This chapter describes the schema database APIs: those structures, constants, and functions that operate on schema databases. This chapter is divided into the following sections:
Schema Databases Structures and Types
Schema Databases Constants
Schema Databases Functions and Macros
The header file SchemaDatabases.h
declares the API that this chapter describes.
For more information on Palm OS® databases, see Chapter 2, "Palm OS Databases."
Schema Databases Structures and Types
DbColumnPropertySpecType Struct
Purpose
Used in conjunction with DbGetColumnPropertyValues()
to specify column properties for selective value retrieval.
Declared In
SchemaDatabases.h
Prototype
typedef struct { uint32_t columnID; DbSchemaColumnProperty propertyID; uint8_t padding[3]; } DbColumnPropertySpecType, *DbColumnPropertySpecPtr
Fields
-
columnID
- The ID of the column for which the property is being retrieved.
-
propertyID
- The ID of the property being retrieved. See
DbSchemaColumnProperty
. -
padding
- Padding bytes used for structure alignment purposes.
DbColumnPropertyValueType Struct
Purpose
Container that identifies a single column property and contains its value.
Declared In
SchemaDatabases.h
Prototype
typedef struct { uint32_t columnID; uint32_t dataSize; void *data; status_t errCode; DbSchemaColumnProperty propertyID; uint8_t padding[3]; } DbColumnPropertyValueType, *DbColumnPropertyValuePtr
Fields
-
columnID
- The ID of the column for which the property is being retrieved or set.
-
dataSize
- The size, in bytes, of the property value.
-
data
- The property value.
-
errCode
- Set by the Data Manager to
errNone
if the property value was set or retrieved successfully, or one of the Data Manager error codes otherwise. -
propertyID
- The ID of the property being retrieved or set.
-
padding
- Padding bytes used for structure alignment purposes only.
Comments
You work with an array of these structures when getting or setting column property values with DbGetAllColumnPropertyValues()
, DbGetColumnPropertyValues()
, and DbSetColumnPropertyValues()
.
DbMatchModeType Typedef
Purpose
Define how a row's category membership should match a supplied set of categories.
Declared In
SchemaDatabases.h
Prototype
typedef uint32_t DbMatchModeType
Constants
-
#define DbMatchAll ((DbMatchModeType)2)
- (AND) Match rows for which membership includes all of the specified categories, including rows with additional category membership.
-
#define DbMatchAny ((DbMatchModeType)1)
- (OR) Match rows for which membership includes any of the specified categories.
-
#define DbMatchExact ((DbMatchModeType)3)
- Match rows for which membership exactly matches the specified categories.
DbSchemaColumnData Typedef
Purpose
Generic type for any kind of column data.
Declared In
SchemaDatabases.h
Prototype
typedef void DbSchemaColumnData;
Fields
Comments
The DbSchemaColumnValueType
structure uses this data type for the column's data.
DbSchemaColumnDefnType Struct
Purpose
Defines a single table column.
Declared In
SchemaDatabases.h
Prototype
typedef struct { uint32_t id; uint32_t maxSize; char name[dbDBNameLength]; DbSchemaColumnType type; uint8_t attrib; uint16_t reserved; status_t errCode; } DbSchemaColumnDefnType, *DbSchemaColumnDefnPtr
Fields
-
id
- User-defined column identifier.
-
maxSize
- Size specification for the column data. For variable-length string vectors, it specifies the size upper-bound and for fixed-length strings, the actual size. For vectors, it specifies the upper-bound in terms of byte count. For all other types, the actual size of the type.
-
name
- User-defined column name.
-
type
- The column type. See the definition of
DbSchemaColumnType
for a list of supported column types. -
attrib
- Column attributes. See "Table Column Attributes" for a list of supported column attributes.
-
reserved
- Reserved for future use.
-
errCode
- Set by the Data Manager to an error code in the course of a value retrieval operation.
errNone
represents a no-error condition.
Comments
You work with these structures both singly and in arrays when adding columns and getting column definitions with DbAddColumn()
, DbGetAllColumnDefinitions()
, and DbGetColumnDefinitions()
. A table definition contains an array of these structures; see "DbTableDefinitionType."
DbSchemaColumnProperty Typedef
Purpose
Container for a column property's type.
Declared In
SchemaDatabases.h
Prototype
typedef uint8_t DbSchemaColumnProperty
Constants
-
#define dbColumnAttribProperty ((DbSchemaColumnProperty)0x04)
- The column's attributes.
-
#define dbColumnDatatypeProperty ((DbSchemaColumnProperty)0x02)
- The column's data type.
-
#define dbColumnNameProperty ((DbSchemaColumnProperty)0x01)
- The column's name.
-
#define dbColumnSizeProperty ((DbSchemaColumnProperty)0x03)
- The column's size.
Comments
Pass these values directly when setting or getting a single table column property value with DbSetColumnPropertyValue()
or DbGetColumnPropertyValue()
, or when removing a column property with DbRemoveColumnProperty()
. When getting or setting multiple property values, you use these values in conjunction with one or more DbColumnPropertyValueType
structures.
DbSchemaColumnType Typedef
Purpose
Contains a value identifying the type of a table column.
Declared In
SchemaDatabases.h
Prototype
typedef uint8_t DbSchemaColumnType
Constants
-
#define dbBlob ((DbSchemaColumnType)0x11)
- A blob. This data type supports offset-based reads and writes.
-
#define dbBoolean ((DbSchemaColumnType)0x0B)
- A Boolean.
-
#define dbChar ((DbSchemaColumnType)0x0F)
- A char.
-
#define dbDate ((DbSchemaColumnType)0x0D)
- A date.
-
#define dbDateTime ((DbSchemaColumnType)0x0C)
- A date and time, not including seconds.
-
#define dbDateTimeSecs ((DbSchemaColumnType)0x12)
- A date and time, including seconds.
-
#define dbDouble ((DbSchemaColumnType)0x0A)
- A double.
-
#define dbFloat ((DbSchemaColumnType)0x09)
- A float.
-
#define dbInt16 ((DbSchemaColumnType)0x06)
- A signed 16-bit integer.
-
#define dbInt32 ((DbSchemaColumnType)0x07)
- A signed 32-bit integer.
-
#define dbInt64 ((DbSchemaColumnType)0x08)
- A signed 64-bit integer.
-
#define dbInt8 ((DbSchemaColumnType)0x05)
- A signed 8-bit integer.
-
#define dbStringVector ((DbSchemaColumnType)0xC0)
- A string vector.
-
#define dbTime ((DbSchemaColumnType)0x0E)
- A time.
-
#define dbUInt16 ((DbSchemaColumnType)0x02)
- An unsigned 16-bit integer.
-
#define dbUInt32 ((DbSchemaColumnType)0x03)
- An unsigned 32-bit integer.
-
#define dbUInt64 ((DbSchemaColumnType)0x04)
- An unsigned 64-bit integer.
-
#define dbUInt8 ((DbSchemaColumnType)0x01)
- An unsigned 8-bit integer.
-
#define dbVarChar ((DbSchemaColumnType)0x10)
- A VarChar. This data type supports offset-based reads and writes.
-
#define dbVector ((DbSchemaColumnType)0x80)
- A vector. This data type supports offset-based reads and writes.
Comments
These constants are used when adding columns to a table or getting table column definitions.
DbSchemaColumnValueType Struct
Purpose
Identifies a table column and acts as a container for the column's data. You use this structure primarily when reading and writing multiple column values in a database row.
Declared In
SchemaDatabases.h
Prototype
typedef struct { DbSchemaColumnData *data; uint32_t dataSize; uint32_t columnID; uint32_t columnIndex; status_t errCode; uint32_t reserved; } DbSchemaColumnValueType, *DbSchemaColumnValuePtr
Fields
-
data
- The column data.
-
dataSize
- The size, in bytes, of the column data being read or written. For variable-length string types, it specifies the actual size to be read or written. For vectors, it specifies the actual byte count to be read or written. When writing,
*data
must, at a minimum, have storage corresponding todataSize
. -
columnID
- The column ID.
-
columnIndex
- The column index. This field is only used when reading column data.
-
errCode
- Set by the Data Manager to an error code in the course of a value retrieval operation.
errNone
represents a no-error condition. -
reserved
- Reserved for future use.
Comments
Use this structure when reading or writing multiple data columns in a single operation with the following functions:
You also use this data structure with DbInsertRow()
.
DbShareModeType Typedef
Purpose
Container for the share mode type, which controls how others can access a database that your application has opened using either DbOpenDatabase()
or DbOpenDatabaseByName()
.
Declared In
SchemaDatabases.h
Prototype
typedef uint16_t DbShareModeType
Constants
-
#define dbShareNone ((DbShareModeType)0x0000)
- While the database is open, don't let anyone else open it.
-
#define dbShareRead ((DbShareModeType)0x0001)
- While the database is open, others can open it in read-only mode.
-
#define dbShareReadWrite ((DbShareModeType)0x0002)
- While the database is open, others can open it in read-only, read-write, or write-only mode.
DbTableDefinitionType Struct
Purpose
Defines a database table. This structure contains the table's name, and acts as a container for an array of DbSchemaColumnDefnType
structures, each element of which defines an individual column.
Declared In
SchemaDatabases.h
Prototype
typedef struct { char name[dbDBNameLength]; uint32_t numColumns; DbSchemaColumnDefnType *columnListP; } DbTableDefinitionType
Fields
-
name
- Table name.
-
numColumns
- Number of columns in the table, which is also the number of elements in the
columnListP
array. -
columnListP
- Pointer to the first of a set of data structures that each define a single table column.
Comments
You use this structure when creating a database with either DbCreateDatabase()
or DbCreateSecureDatabase()
, when adding a new table to a database (with DbAddTable()
) and when querying a database table for schema information (DbGetTableSchema()
).
Schema Databases Constants
Schema Database Row Attributes
Purpose
Define the set of attributes that a row can have. Use DbGetRowAttr()
to obtain a row's attributes.
Declared In
DataMgr.h
Constants
-
#define dbRecAttrArchive 0x01
- The row is marked for archiving: it is treated like a deleted row, but the chunk is not freed and the row ID is preserved so that upon the next HotSync operation the desktop computer saves the row data before it permanently removes the row entry and data from the Palm Powered™ handheld.
-
#define dbRecAttrDelete 0x80
- The row has been deleted.
-
#define dbRecAttrReadOnly 0x02
- The row is read-only, and cannot be written to. Note that the Data Manager does not place any semantics on the read-only attribute. It is up to the application to enforce the read-only semantics.
-
#define dbRecAttrSecret 0x10
- The row is private.
-
#define dbAllRecAttrs (dbRecAttrDelete | dbRecAttrSecret | dbRecAttrArchive | dbRecAttrReadOnly)
- The complete set of schema database row attributes.
-
#define dbSysOnlyRecAttrs (dbRecAttrDelete | dbRecAttrArchive)
- System-only attributes. These attributes are maintained by the operating system and cannot be set with
DbSetRowAttr()
.
Table Column Attributes
Purpose
Identify the various attributes of a table column.
Declared In
DataMgr.h
Constants
-
#define dbSchemaColDynamic 0x01
- The column was added after the table was created.
-
#define dbSchemaColNonSyncable 0x02
- The column's data won't be synchronized. Modifications made to a "non-syncable" column's data don't change the modification state for the row, and thus by themselves don't cause the row to be synchronized during a HotSync operation.
-
#define dbSchemaColWritable 0x04
- The column's data can be modified. Writable columns are relevant for read-only rows and are required for sharing.
-
#define dbAllSchemaColAttrs (dbSchemaColDynamic | dbSchemaColNonSyncable | dbSchemaColWritable)
- The complete set of table column attributes.
Comments
These constants are used when adding columns to a table or getting table column definitions. See "DbSchemaColumnDefnType" for more information.
Schema Database Access Rule Action Types
Purpose
Database actions that can have access rules set in a secure database.
Declared In
DataMgr.h
Constants
-
#define dbActionBackup ((AzmActionType)0x00000008)
- Database backup is permitted.
-
#define dbActionDelete ((AzmActionType)0x00000004)
- Database contents can be deleted.
-
#define dbActionEditSchema ((AzmActionType)0x00000020)
- Database schemas can be altered.
-
#define dbActionRead ((AzmActionType)0x00000001)
- The database can be read.
-
#define dbActionRestore ((AzmActionType)0x00000010)
- Database restore is permitted.
-
#define dbActionWrite ((AzmActionType)0x00000002)
- The database can be written to.
Comments
Use a combination of these values (or'd together) to create the action
parameter you supply to AzmAddRule()
.
Cursor Open Flags
Purpose
Flags used to specify how a database cursor is created. Supply any combination of these (OR'd together) to DbCursorOpen()
or DbCursorOpenWithCategory()
; in most cases you supply none of these flags (that is, you supply a flags
value of zero).
Declared In
SchemaDatabases.h
Constants
-
#define dbCursorEnableCaching 0x00010000
- Enable the caching of row data locally in the cursor.
-
#define dbCursorIncludeDeleted 0x00000001
- The cursor should contain rows that are marked as deleted or archived.
-
#define dbCursorOnlyDeleted 0x00000002
- The cursor should contain only those rows that are marked as deleted or archived.
-
#define dbCursorOnlySecret 0x00000004
- The cursor should contain only those rows that are marked as secret.
-
#define dbCursorSortByCategory 0x10000000
- Sort rows by category. Rows with multiple categories appear in the cursor multiple times.
Miscellaneous Schema Database Constants
Purpose
The header file SchemaDatabases.h
also declares these constants.
Declared In
SchemaDatabases.h
Constants
-
#define dbColumnPropertyUpperBound ((DbSchemaColumnProperty)0x0A)
- Identifies the upper bound of the range of built-in property type IDs.
-
#define DbCursorBOFPos 0xFFFFFFFF
- Cursor row position signifying BOF (Beginning Of File).
-
#define dbCursorEOFPos 0xFFFFFFFE
- Cursor row position signifying EOF (End Of File).
-
#define dbDBNameLength 32
- Maximum length, including the
NUL
terminator, of a schema database name. -
#define dbInvalidCursorID 0x0
- Cursor ID returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
if the open failed. -
#define dbInvalidRowID dbInvalidCursorID
- Row ID returned from
DbCursorGetCurrentRowID()
,DbCursorGetPositionForRowID()
, orDbInsertRow()
if the operation failed. -
#define DbMaxRecordCategories 255
- Maximum number of categories to which a row can be assigned.
-
#define dbMaxRowIndex 0x00FFFFFEL
- Highest possible row index.
DbFetchType Enum
Purpose
Specifies how the cursor is to be repositioned when using DbCursorMove()
.
Declared In
SchemaDatabases.h
Constants
-
dbFetchRelative
- Moves the cursor forward by the specified number of rows if the offset is positive, or backward by the specified number of rows if the offset is negative.
-
dbFetchAbsolute
- Moves the cursor onto the row with the specified index. The macro
DbCursorSetAbsolutePosition()
callsDbCursorMove()
with a fetch type ofdbFetchAbsolute
. -
dbFetchNext
- Moves the cursor forward one row. The macro
DbCursorMoveNext()
callsDbCursorMove()
with a fetch type ofdbFetchNext
. Note that theoffset
parameter toDbCursorMove()
is ignored when the fetch type isdbFetchNext
. -
dbFetchPrior
- Moves the cursor backward one row. The macro
DbCursorMovePrev()
callsDbCursorMove()
with a fetch type ofdbFetchPrior
. Note that theoffset
parameter toDbCursorMove()
is ignored when the fetch type isdbFetchPrior
. -
dbFetchFirst
- Moves the cursor onto the first row. The macro
DbCursorMoveFirst()
callsDbCursorMove()
with a fetch type ofdbFetchFirst
. -
dbFetchLast
- Moves the cursor onto the last row. The macro
DbCursorMoveLast()
callsDbCursorMove()
with a fetch type ofdbFetchLast
. -
dbFetchRowID
- Moves the cursor onto the row with the specified row ID. The macro
DbCursorMoveToRowID()
callsDbCursorMove()
with a fetch type ofdbFetchRowID
.
Comments
Any attempt to move the current row position beyond the set of rows in the cursor results in an error. DbCursorMove()
returns dmErrCursorBOF
if you attempt to move before the first row in the cursor, and dmErrCursorEOF
if you attempt to move beyond the last row in the cursor. These conditions can also be detected with the use of the DbCursorIsBOF()
and DbCursorIsEOF()
functions.
Schema Databases Functions and Macros
DbAddCategory Function
Purpose
Make the specified row a member of one or more additional categories.
Declared In
DataMgr.h
Prototype
status_t DbAddCategory ( DmOpenRefdbRef
, uint32_trowID
, uint32_tnumToAdd
, const CategoryIDcategoryIDs[]
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row to which categories are to be added.
-
→ numToAdd
- Number of categories in the
categoryIDs
array. -
→ categoryIDs
- Array of category IDs.
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database, the specified row or cursor ID is not valid, ornumToAdd
is nonzero andcategoryIDs
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrIndexOutOfRange
- The specified row or cursor ID doesn't reference a row within the table.
-
dmErrRecordDeleted
- The specified row is marked as deleted.
-
dmErrRecordBusy
- The specified row is in use and cannot be updated.
-
dmErrMemError
- A memory error occurred.
-
dmErrInvalidCategory
- The allowed number of categories has been exceeded, or a category ID doesn't correspond to a defined category.
Comments
The database must be opened with write access.
The category IDs passed through the categoryIDs
parameter must be valid category IDs. If any of the array values is not a valid category ID, this function returns dmErrInvalidCategory
.
If a given category ID value appears more than once in the categoryIDs
array, the category membership is only added once. If the row already has membership in a category specified in the categoryIDs
array, the array value is ignored and the row remains a member of that category.
See Also
DbRemoveCategory()
, DbSetCategory()
DbAddColumn Function
Purpose
Adds a column to a database table.
Declared In
SchemaDatabases.h
Prototype
status_t DbAddColumn ( DmOpenRefdbRef
, const char*table
, const DbSchemaColumnDefnType*addColumnP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ table
- Name of the table to which the column is to be added.
-
→ addColumnP
- Pointer to a
DbSchemaColumnDefnType
structure defining the column to be added.
Returns
Returns errNone
if successful, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,table
isNULL
, oraddColumnP
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrInvalidColType
- The specified column type is not a valid column type.
-
dmErrAccessDenied
- The database is a secure database and you don't have permission to edit its schemas.
-
dmErrInvalidColSpec
- At least one of the specified column attributes is not a valid column attribute.
-
dmErrInvalidColumnName
- The supplied column name is not a valid column name.
-
dmErrInvalidVectorType
- The column is a vector column but the column type isn't appropriate for a vector column.
-
dmErrInvalidSizeSpec
- The column is a vector column but the column size is zero.
-
dmErrInvalidTableName
- The supplied table name doesn't identify a table in the specified database.
-
dmErrColumnDefinitionsLocked
- The table's column definitions are locked.
-
dmErrColumnIDAlreadyExists
- A column with the specified ID already exists.
-
dmErrColumnNameAlreadyExists
- The table already contains a column with the specified name.
-
dmErrMemError
- A memory error occurred.
Comments
The database must be opened in write mode.
See Also
DbGetAllColumnDefinitions()
, DbGetColumnDefinitions()
DbAddSortIndex Function
Purpose
Adds a new sort index to a database.
Declared In
SchemaDatabases.h
Prototype
status_t DbAddSortIndex ( DmOpenRefdbRef
, const char*orderBy
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ orderBy
- The sort index, which identifies both the table containing the rows to select from and the manner in which the cursor's rows should be sorted. See "The SELECT Statement" for the format of this parameter.
Returns
Returns errNone
if successful, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrAccessDenied
- You do not have authorization to modify the database.
-
dmErrSQLParseError
- The specified table name or the sort information specified in the sort index is invalid.
-
dmErrInvalidTableName
- The specified table doesn't exist within the database.
-
dmErrInvalidSortDefn
- The sort index contains no column IDs, or all of the columns in the sort index aren't of the same type.
-
dmErrInvalidColumnID
- One or more of the specified column IDs doesn't correspond to a column in the specified table.
-
dmErrAlreadyExists
- The specified sort index already exists.
-
dmErrMemError
- A memory error occurred.
Comments
While sorting is enabled, the operating system keeps schema databases sorted according to each of the database's sort indices. This function adds a new sort index to a schema database. When the new sort index is added, the database is immediately sorted according to the new sort index.
Before you can open a cursor with a given sort index, the sort index must have already been added to the database.
The orderBy
parameter is an SQL statement of the form described under "The SELECT Statement." The optional WHERE clause allows you to filter the rows to be included in the cursor. The column specified in the WHERE clause can only be one of the following types:
With dbVarChar
columns, the operator (op) can be "LIKE
" (and the argument must be a string); this uses TxtFindString()
to identify all rows where the supplied string is found in the row.
See Also
DbCursorOpen()
, DbCursorOpenWithCategory()
, DbHasSortIndex()
, DbRemoveSortIndex()
DbAddTable Function
Purpose
Adds a table to an existing database.
Declared In
SchemaDatabases.h
Prototype
status_t DbAddTable ( DmOpenRefdbRef
, const DbTableDefinitionType*schemaP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ schemaP
- Pointer to a structure that represents the table to be added.
Returns
Returns errNone
if successful, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database, orschemaP
isNULL
. -
dmErrNotSchemaDatabase
- The database referenced by
dbRef
isn't a schema database. -
dmErrReadOnly
- The database is read-only.
-
dmErrInvalidSchemaDefn
- The supplied
DbTableDefinitionType
structure is invalid. -
dmErrTableNameAlreadyExists
- The database already contains a table with the specified name.
-
dmErrColumnIDAlreadyExists
- The table definition contains multiple columns with the same ID.
-
dmErrColumnNameAlreadyExists
- The table definition contains multiple columns with the same name.
-
dmErrInvalidColType
- A column data type is invalid.
-
dmErrAccessDenied
- You do not have authorization to modify the database.
Comments
The database must be opened in write mode.
See Also
DbArchiveRow Function
Purpose
Mark a row as archived. This function leaves the row's data intact.
Declared In
SchemaDatabases.h
Prototype
status_t DbArchiveRow ( DmOpenRefdbRef
, uint32_trowID
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row to be archived.
Returns
Returns errNone
if successful, 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.
-
dmErrIndexOutOfRange
- The specified index is out of range.
-
dmErrRecordArchived
- The function requires that the row not be archived, but it is.
-
dmErrRecordDeleted
- The row has been deleted.
Comments
When a row is archived, the archive bit is set but the data chunks are not freed and the row ID is preserved. The next time the handheld is synchronized with the desktop computer, a conduit can save the row data on the desktop and then remove the row entry and data from the handheld.
See Also
DbCursorArchiveAllRows()
, DbDeleteRow()
, DbRemoveRow()
DbCloseDatabase Function
Purpose
Declared In
SchemaDatabases.h
Prototype
status_t DbCloseDatabase (
DmOpenRef dbRef
)
Parameters
Returns
Returns errNone
if successful, or dmErrInvalidParam
if the dbRef
parameter doesn't indicate an open schema database.
Comments
This function doesn't unlock any rows that were left locked. Applications should not leave rows locked when closing a schema database.
See Also
DbOpenDatabase()
, DbOpenDatabaseByName()
DbCopyColumnValue Function
Purpose
Obtains the value of a single schema database column for a specified row.
Declared In
SchemaDatabases.h
Prototype
status_t DbCopyColumnValue ( DmOpenRefdbRef
, uint32_trowID
, uint32_tcolumnID
, uint32_toffset
, void*valueP
, uint32_t*valueSizeP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row for which column values are being retrieved.
-
→ columnID
- ID of the column being retrieved.
-
→ offset
- Column value offset from which the data is retrieved. This parameter is treated as a byte offset. See the Comments section, below, for more information.
-
↔ valueP
- Pointer to a pre-allocated buffer into which the row's column value is copied, or
NULL
to determine how large the buffer should be. -
↔ valueSizeP
- Size of the
valueP
buffer.
Returns
Returns errNone
if successful, or one of the following if an error occurred:
-
dmErrInvalidParam
-
rowID
is not a row or cursor ID, orvalueSizeP
isNULL
. -
dmErrCursorBOF
- The supplied cursor ID is BOF.
-
dmErrCursorEOF
- The supplied cursor ID is EOF.
-
dmErrUniqueIDNotFound
- The supplied cursor ID represents an invalid row.
-
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrUniqueIDNotFound
- The supplied row or cursor ID doesn't correspond to a row within the database.
-
dmErrRecordDeleted
- The specified row is marked as deleted.
-
dmErrInvalidColSpec
- There are no columns defined for the specified table.
-
dmErrInvalidColumnID
- The supplied column ID is invalid.
-
dmErrNoColumnData
- The specified row has no data for the column.
-
dmErrReadOutOfBounds
- The specified offset exceeds the bounds of the column.
-
dmErrBufferNotLargeEnough
- The supplied buffer isn't large enough to contain the column value.
-
dmErrMemError
- A memory error occurred.
Comments
This function returns a copy of the column data. Offset-based reads are not supported for fixed-length column data types; the offset
parameter is ignored for those data types. The list of column data types supporting offset-based reads are:
If valueP
is NULL
, this function returns the actual size needed to hold the column data through valueSizeP
.
See Also
DbCopyColumnValues()
, DbGetColumnValue()
, DbWriteColumnValue()
DbCopyColumnValues Function
Purpose
Obtains the value of one or more schema database columns for a specified row.
Declared In
SchemaDatabases.h
Prototype
status_t DbCopyColumnValues ( DmOpenRefdbRef
, uint32_trowID
, uint32_tnumColumns
, DbSchemaColumnValueType*columnValuesP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row for which column values are being retrieved.
-
→ numColumns
- Number of elements in the
columnValuesP
array. -
↔ columnValuesP
- Pointer to a pre-allocated array of
DbSchemaColumnValueType
structures. Prior to calling this function, the data field of each structure must be initialized with a pointer to a buffer of appropriate size for the column, or set toNULL
, which results in the actual size of the column data being returned in theactualDataSize
field of the structure.
Returns
Returns errNone
if successful, or one of the following if an error occurred:
-
dmErrInvalidParam
-
rowID
is not a row or cursor ID,dbRef
doesn't reference an open database,numColumns
is zero, orcolumnValuesP
isNULL
. -
dmErrCursorBOF
- The supplied cursor ID is BOF.
-
dmErrCursorEOF
- The supplied cursor ID is EOF.
-
dmErrUniqueIDNotFound
- The supplied cursor ID represents an invalid row.
-
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrUniqueIDNotFound
- The supplied row or cursor ID doesn't correspond to a row within the database.
-
dmErrRecordDeleted
- The specified row is marked as deleted.
-
dmErrInvalidColSpec
- There are no columns defined for the specified table.
-
dmErrInvalidColumnID
- The one or more of the specified column IDs is invalid.
-
dmErrNoColumnData
- The specified row has no data.
-
dmErrBufferNotLargeEnough
- At least one of the supplied buffers isn't large enough to contain the corresponding column value.
-
dmErrMemError
- A memory error occurred.
See Also
DbCopyColumnValue()
, DbGetColumnValues()
, DbWriteColumnValues()
DbCreateDatabase Function
Purpose
Creates a new schema database.
Declared In
SchemaDatabases.h
Prototype
status_t DbCreateDatabase ( const char*name
, uint32_tcreator
, uint32_ttype
, uint32_tnumTables
, const DbTableDefinitionTypeschemaListP[]
, DatabaseID*dbIDP
)
Parameters
-
→ name
- Name of the new database. The name should be up to 32 ASCII bytes long, including the
NULL
terminator, as specified bydmDBNameLength
. The name should be constructed only of 7-bit ASCII characters (0x20
through0x7E
). -
→ creator
- Database creator ID.
-
→ type
- Database type.
-
→ numTables
- Number of elements in
schemaListP
. This parameter can be zero, which creates a new database with no tables defined. -
→ schemaListP
- Array of structures. Each element defines the schema for the newly-created database table.
-
← dbIDP
- ID of the newly-created database. Pass this ID to
DbOpenDatabase()
when opening the database.
Returns
Returns errNone
if successful, or one of the following if an error occurred:
-
dmErrInvalidDatabaseName
- The specified database name is nonexistent, exceeds
dmDBNameLength
, or is otherwise invalid. -
dmErrInvalidSchemaDefn
-
schemaListP
isNULL
, no table name was supplied, one or more column names are missing. -
dmErrTableNameAlreadyExists
- One of the supplied table names occurs in more than one
schemaListP
entry. -
dmErrColumnIDAlreadyExists
- One of the supplied column IDs is already defined for this database.
-
dmErrColumnNameAlreadyExists
- One of the supplied column names is already defined for this database.
-
dmErrInvalidColType
- One of the supplied column types is not a valid column type.
-
dmErrInvalidVectorType
- A one of the supplied vector column types isn't a valid vector column type.
-
dmErrInvalidSizeSpec
- At least one of the vector column sizes is zero.
-
dmErrInvalidColSpec
- One of the supplied column attributes is not a valid column attribute.
-
dmErrInvalidColumnName
- One or more table or column names was invalid.
-
dmErrAccessDenied
- You don't have permission to create a database of this type.
-
dmErrAlreadyExists
- Another database with this name already exists.
-
dmErrMemError
- A memory error occurred. Sufficient memory must be available to create a new database.
-
memErrNotEnoughSpace
- A memory error occurred.
Comments
Prior to calling this function, the database must not already exist. Sufficient memory must be available to create a new database. If numTables
is nonzero, the supplied DbTableDefinitionType
structures must have been previously initialized.
See Also
DbCreateSecureDatabase()
, DbCreateSecureDatabaseFromImage()
, DbOpenDatabase()
DbCreateSecureDatabase Function
Purpose
Create a new secure schema database.
Declared In
SchemaDatabases.h
Prototype
status_t DbCreateSecureDatabase ( const char*name
, uint32_tcreator
, uint32_ttype
, uint32_tnumSchemas
, const DbTableDefinitionTypeschemaList[]
, AzmRuleSetType*ruleset
, DatabaseID*id
)
Parameters
-
→ name
- Name of the new database. The name should be up to 32 ASCII bytes long, including the
NULL
terminator, as specified bydmDBNameLength
. The name should be constructed only of 7-bit ASCII characters (0x20
through0x7E
). -
→ creator
- Database creator ID.
-
→ type
- Database type.
-
→ numSchemas
- Number of elements in
schemaList
. This parameter can be zero, which creates a secure database with no tables defined. -
→ schemaList
- Array of structures. Each element defines the schema for the newly-created database table.
-
← ruleset
- Handle to the database's access rules.
-
← id
- ID of the newly-created database. Pass this ID to
DbOpenDatabase()
when opening the database.
Returns
Returns errNone
if the database was successfully created, or one of the following if there was an error:
-
dmErrInvalidDatabaseName
- The specified database name is nonexistent, exceeds
dmDBNameLength
, or is otherwise invalid. -
dmErrInvalidSchemaDefn
-
schemaListP
isNULL
, no table name was supplied, one or more column names are missing. -
dmErrTableNameAlreadyExists
- One of the supplied table names occurs in more than one
schemaListP
entry. -
dmErrColumnIDAlreadyExists
- One of the supplied column IDs is already defined for this database.
-
dmErrColumnNameAlreadyExists
- One of the supplied column names is already defined for this database.
-
dmErrInvalidColType
- One of the supplied column types is not a valid column type.
-
dmErrInvalidVectorType
- A one of the supplied vector column types isn't a valid vector column type.
-
dmErrInvalidSizeSpec
- At least one of the vector column sizes is zero.
-
dmErrInvalidColSpec
- One of the supplied column attributes is not a valid column attribute.
-
dmErrInvalidColumnName
- One or more column names was invalid.
-
dmErrInvalidTableName
- One or more table names was invalid.
-
dmErrAccessDenied
- You don't have permission to create a database of this type.
-
dmErrAlreadyExists
- Another database with this name already exists.
-
dmErrMemError
- A memory error occurred. Sufficient memory must be available to create a new database.
-
memErrNotEnoughSpace
- A memory error occurred.
-
azmErrOutOfMemory
- A memory error occurred.
Comments
Prior to calling this function, the database must not already exist. Sufficient memory must be available to create a new database. If numSchemas
is nonzero, the supplied DbTableDefinitionType
structures must have been previously initialized.
Once the database is created, it is initially protected with all actions (Read, Write, Delete, Schema Edit, Backup, and Restore) denied. Before using the database you must specify access rules for the Read, Write, and Delete actions using Authorization Manager and Authentication Manager functions (see Exploring Palm OS: Security and Cryptography for documentation on these functions). Until access rules are specified, all access to the database is denied.
See Also
DbCreateDatabase()
, DbCreateSecureDatabaseFromImage()
, DbOpenDatabase()
DbCreateSecureDatabaseFromImage Function
Purpose
Create a secure schema database from a single resource that contains an image of the database.
Declared In
SchemaDatabases.h
Prototype
status_t DbCreateSecureDatabaseFromImage ( const void*bufferP
, DatabaseID*pDbID
, AzmRuleSetType*pRuleSet
)
Parameters
-
→ bufferP
- Pointer to a locked resource containing the database image.
-
← pDbID
- Pointer to a variable that receives the ID of the newly-created database, or
NULL
if the ID isn't needed. -
← pRuleSet
- Pointer to the Authorization Manager rule set for the newly-created secure database.
Returns
Returns errNone
if the database was successfully created. Otherwise, this function returns an error code such as (but not limited to) the following:
-
dmErrInvalidParam
-
bufferP
isNULL
orpRuleSet
isNULL
. -
dmErrCorruptDatabase
- The format of the supplied database image isn't recognizable as a schema database.
-
dmErrMemError
- A memory error occurred.
Comments
This function is typically used by applications to install a default database.
See Also
DbCreateDatabase()
, DbCreateSecureDatabase()
, DbOpenDatabase()
DbCursorArchiveAllRows Function
Purpose
Mark all rows in the cursor for archiving.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorArchiveAllRows (
uint32_t cursorID
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrInvalidParam
- The specified cursor ID isn't valid.
-
dmErrRecordBusy
- One of the rows is in use and cannot be updated.
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
Comments
When a row is archived, the archive bit is set but the data chunks are not freed and the row ID is preserved. The next time the handheld is synchronized with the desktop computer, a conduit can save the row data on the desktop and then remove the row entry and data from the handheld.
See Also
DbArchiveRow()
, DbCursorDeleteAllRows()
, DbCursorRemoveAllRows()
DbCursorBindData Function
Purpose
Bind a variable to a cursor column.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorBindData ( uint32_tcursorID
, uint32_tcolumnID
, void*dataBufferP
, uint32_tdataBufferLength
, uint32_t*dataSizeP
, status_t*errCodeP
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
. -
→ columnID
- ID of the column to be bound.
-
← dataBufferP
- Pointer to a buffer that receives the bound field data.
-
→ dataBufferLength
- Size, in bytes, of the data buffer specified in
dataBufferP
. -
← dataSizeP
- The size of the data written to the data buffer.
-
← errCodeP
- An error code that is updated whenever the data buffer is updated.
Returns
Returns errNone
if the data buffer is successfully bound to the column, or one of the following otherwise:
-
dmErrInvalidParam
- The function received an invalid parameter.
-
dmErrMemError
- A memory error occurred.
Comments
When a variable is bound to column, that variable is automatically updated to hold the field value of the cursor's current row. Using the DbCursorMove...
functions and macros to change the current row in the cursor automatically updates any bound variables.
When the bound variable is updated, *dataSizeP
is set to the size of the data stored in the data buffer. This is useful for columns of varying length types (VarChar
and Blob
), but is not needed for fixed length types. The error code is also set each time the variable is updated, indicating success (errNone
), no data for that column (dmErrNoColumnData
), or some other failure error code.
See Also
DbCursorBindDataWithOffset()
, DbCursorMove()
, DbCursorOpen()
, DbCursorOpenWithCategory()
, DbCursorUpdate()
DbCursorBindDataWithOffset Function
Purpose
Bind a variable to a cursor column, offset by a specified amount.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorBindDataWithOffset ( uint32_tcursorID
, uint32_tcolumnID
, void*dataBufferP
, uint32_tdataBufferLength
, uint32_t*dataSizeP
, uint32_tfieldDataOffset
, status_t*errCodeP
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
. -
→ columnID
- ID of the column to be bound.
-
← dataBufferP
- Pointer to a buffer that receives the bound field data.
-
→ dataBufferLength
- Size, in bytes of the data buffer specified in
dataBufferP
. -
← dataSizeP
- The size of the data written to the data buffer.
-
→ fieldDataOffset
- Byte offset into the column.
-
← errCodeP
- An error code that is updated whenever the data buffer is updated.
Returns
Returns errNone
if the data buffer is successfully bound to the column, or one of the following otherwise:
-
dmErrInvalidParam
- The function received an invalid parameter.
-
dmErrMemError
- A memory error occurred.
Comments
This function is similar to DbCursorBindData()
, but adds an extra parameter to allow you to specify an offset into the database field data. The data copied to the buffer is taken from the database field at the specified offset. This allows you to bind a subset of the field data to a variable.
See Also
DbCursorMove()
, DbCursorOpen()
, DbCursorOpenWithCategory()
, DbCursorUpdate()
DbCursorClose Function
Purpose
Free all resources associated with a cursor.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorClose (
uint32_t cursorID
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
.
Returns
Returns errNone
if the resources were successfully freed, or one of the following otherwise:
Comments
When a cursor is no longer needed, call DbCursorClose()
to free all of the resources associated with the cursor.
See Also
DbCursorOpen()
, DbCursorOpenWithCategory()
DbCursorDeleteAllRows Function
Purpose
Mark all rows in the cursor as deleted.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorDeleteAllRows (
uint32_t cursorID
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrInvalidParam
- The specified cursor ID isn't valid.
-
dmErrRecordBusy
- One of the rows is in use and cannot be updated.
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
Comments
For each row in the cursor, this function deletes the row's chunk from the database but leaves the row entry in the header and marks the row as deleted. During the next HotSync operation, a conduit can save the row data on the desktop and then remove the row entries in the header that are marked as deleted.
See Also
DbCursorArchiveAllRows()
, DbCursorRemoveAllRows()
, DbDeleteRow()
DbCursorFlushCache Function
Purpose
Flush the contents of the cursor cache. This function should only be called for cursors that were created with caching enabled.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorFlushCache ( uint32_t cursorID )
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrInvalidParam
- The specified cursor ID is not valid.
-
dmErrAccessDenied
- The specified cursor wasn't created with caching enabled. That is, the dbCursorEnableCaching flag was not specified when the cursor was created.
-
dmErrRecordBusy
- The specified cursor is in use.
DbCursorGetCurrentPosition Function
Purpose
Get the index of the cursor's current row.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorGetCurrentPosition ( uint32_tcursorID
, uint32_t*position
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
. -
← position
- The row index of the current row within the cursor.
Returns
Returns errNone
if *position
was set to a valid row index, or one of the following otherwise:
-
dmErrInvalidParam
- The specified cursor ID is not valid.
-
dmErrCursorBOF
- The current position is before the first cursor row.
-
dmErrCursorEOF
- The current position is after the last cursor row.
Comments
The first row within a cursor has an index value of 1.
See Also
DbCursorGetCurrentRowID()
, DbCursorGetPositionForRowID()
, DbCursorGetRowIDForPosition()
DbCursorGetCurrentRowID Function
Purpose
Get the row ID of the cursor's current row.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorGetCurrentRowID ( uint32_tcursorID
, uint32_t*rowIDP
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
. -
← rowIDP
- Pointer to a variable that receives the row ID. If the cursor isn't currently positioned at a valid row,
*
rowIDP
is set todbInvalidRowID
.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database, or the specified cursor ID is not valid. -
dmErrCursorBOF
- The current position is before the first cursor row.
-
dmErrCursorEOF
- The current position is after the last cursor row.
-
dmErrUniqueIDNotFound
- The current row's ID is invalid.
See Also
DbCursorGetCurrentPosition()
, DbCursorGetPositionForRowID()
, DbCursorGetRowIDForPosition()
, DbGetTableForRow()
DbCursorGetPositionForRowID Function
Purpose
Get the index of a specified row within the cursor.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorGetPositionForRowID ( uint32_tcursorID
, uint32_trowID
, uint32_t*positionP
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
. -
→ rowID
- ID of a row within the cursor.
-
← positionP
- The index of the specified row within the cursor, or 0 if an error occurred.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrInvalidParam
- The specified cursor ID is not valid, the specified row ID isn't a valid row ID, or
positionP
isNULL
. -
dmErrCantFind
- The specified row ID doesn't match any of the cursor's rows.
Comments
The first row within a cursor has an index value of 1.
See Also
DbCursorGetCurrentPosition()
, DbCursorGetCurrentRowID()
, DbCursorGetRowIDForPosition()
DbCursorGetRowCount Function
Purpose
Get the total number of rows in the cursor.
Declared In
SchemaDatabases.h
Prototype
uint32_t DbCursorGetRowCount (
uint32_t cursorID
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
.
Returns
Returns the number of rows in the cursor.
DbCursorGetRowIDForPosition Function
Purpose
Get a row's ID given its index.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorGetRowIDForPosition ( uint32_tcursorID
, uint32_tposition
, uint32_t*rowIDP
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
. -
→ position
- Index of the row for which the ID is to be retrieved.
-
← rowIDP
- The row's ID. If row ID cannot be determined,
*
rowIDP
is set todbInvalidRowID
.
Returns
Returns errNone
if the ID was successfully retrieved, or one of the following if an error occurred:
-
dmErrInvalidParam
- The specified cursor ID is not valid, the specified position doesn't indicate a valid row within the cursor, or
rowIDP
isNULL
. -
dmErrRecordDeleted
- The row at the specified position is marked for deletion.
Comments
The first row within a cursor has an index value of 1.
See Also
DbCursorGetCurrentPosition()
, DbCursorGetCurrentRowID()
, DbCursorGetPositionForRowID()
DbCursorIsBOF Function
Purpose
Determine if the cursor's BOF (beginning of file) property is true.
Declared In
SchemaDatabases.h
Prototype
Boolean DbCursorIsBOF (
uint32_t cursorID
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
.
Returns
Returns true
if the cursor is at BOF, false
otherwise.
Comments
BOF is the position immediately before the first row in the cursor. Attempting to move before the first row in the cursor sets BOF to true
and returns a dmErrCursorBOF
. If BOF is true
, moving to the next row moves to the first row in the cursor.
See Also
DbCursorIsEOF()
, DbCursorMove()
, DbCursorMoveFirst()
, DbCursorMoveNext()
DbCursorIsDeleted Function
Purpose
Determine if the cursor's current row is marked for deletion.
Declared In
SchemaDatabases.h
Prototype
Boolean DbCursorIsDeleted (
uint32_t cursorID
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
.
Returns
Returns true
if the current row is marked for deletion, false
otherwise. Note that this function returns false
if the supplied cursor ID isn't valid, or if the cursor's current position doesn't represent a valid row (for instance, if the current position is at BOF).
See Also
DbCursorIsEOF Function
Purpose
Determine whether the cursor's EOF (end of file) property is true.
Declared In
SchemaDatabases.h
Prototype
Boolean DbCursorIsEOF (
uint32_t cursorID
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
.
Returns
Returns true
if the cursor is at EOF, false
otherwise.
Comments
EOF is the position immediately after the last row in the cursor. Attempting to move past the last row in the cursor sets EOF (end of file) to true
and returns a dmErrCursorEOF
. If EOF is true
, moving to the previous row moves to the last row in the cursor.
See Also
DbCursorIsBOF()
, DbCursorMove()
, DbCursorMoveLast()
, DbCursorMovePrev()
DbCursorMove Function
Purpose
Move a cursor's current row position.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorMove ( uint32_tcursorID
, int32_toffset
, DbFetchTypefetchType
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
. -
→ offset
- Number of rows to move the current row selector. Negative numbers move backward.
-
→ fetchType
- One of the values defined by the
DbFetchType
enum specifying how the cursor is to move (forward one row, backward a specified number of rows, to an absolute position, etc.).
Returns
Returns errNone
if the current row position was moved to a valid row within the cursor, or one of the following otherwise:
-
dmErrInvalidParam
- The specified cursor ID is invalid.
-
dmErrCursorBOF
- An attempt was made to move to a position before the first row in the cursor.
-
dmErrCursorEOF
- An attempt was made to move to a position after the last row in the cursor.
Comments
When fetchType
is dbFetchRelative
, positive values move the current row position forward, while negative values move the current row position backward. Attempting to move before the first row in the cursor, or attempting to move past the last row in the cursor generates an error, and the cursor's BOF or EOF property, as appropriate, is set.
When moving through the cursor, note that rows that were modified are not moved to their new sort position until DbCursorRequery()
is called. Similarly, any new rows are not available to the cursor until DbCursorRequery()
is called.
Upon successful completion of the move, any bound variables are updated with corresponding field values for the new current row.
See Also
DbCursorMoveFirst()
, DbCursorMoveLast()
, DbCursorMoveNext()
, DbCursorMovePrev()
, DbCursorMoveToRowID()
, DbCursorSetAbsolutePosition()
DbCursorMoveFirst Macro
Purpose
Set the current row position of the cursor to the first row in the cursor.
Declared In
SchemaDatabases.h
Prototype
#define DbCursorMoveFirst (
i
)
Parameters
-
→ i
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
.
Returns
Returns errNone
if the current row position was moved to a valid row within the cursor, or one of the following otherwise:
Comments
Upon successful completion of the move, any bound variables are updated with corresponding field values for the new current row.
See Also
DbCursorMoveLast Macro
Purpose
Set the current row position of the cursor to the last row in the cursor.
Declared In
SchemaDatabases.h
Prototype
#define DbCursorMoveLast (
i
)
Parameters
-
→ i
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
.
Returns
Returns errNone
if the current row position was moved to a valid row within the cursor, or one of the following otherwise:
Comments
Upon successful completion of the move, any bound variables are updated with corresponding field values for the new current row.
See Also
DbCursorMoveNext Macro
Purpose
Move the cursor's current row position forward to the next row in the cursor.
Declared In
SchemaDatabases.h
Prototype
#define DbCursorMoveNext (
i
)
Parameters
-
→ i
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
.
Returns
Returns errNone
if the current row position was moved to a valid row within the cursor, or one of the following otherwise:
-
dmErrInvalidParam
- The specified cursor ID is invalid.
-
dmErrCursorEOF
- An attempt was made to move to a position after the last row in the cursor.
Comments
An attempt to move past the last row in the cursor generates a dmErrCursorEOF
error and sets the cursor's EOF property.
When moving through the cursor, note that rows that were modified are not moved to their new sort position until DbCursorRequery()
is called. Similarly, any new rows are not available to the cursor until DbCursorRequery()
is called.
Upon successful completion of the move, any bound variables are updated with corresponding field values for the new current row.
See Also
DbCursorMovePrev Macro
Purpose
Move the cursor's current row position backward to the previous row in the cursor.
Declared In
SchemaDatabases.h
Prototype
#define DbCursorMovePrev (
i
)
Parameters
-
→ i
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
.
Returns
Returns errNone
if the current row position was moved to a valid row within the cursor, or one of the following otherwise:
-
dmErrInvalidParam
- The specified cursor ID is invalid.
-
dmErrCursorBOF
- An attempt was made to move to a position before the first row in the cursor.
Comments
An attempt to move before the first row in the cursor generates a dmErrCursorBOF
error and sets the cursor's BOF property.
When moving through the cursor, note that rows that were modified are not moved to their new sort position until DbCursorRequery()
is called. Similarly, any new rows are not available to the cursor until DbCursorRequery()
is called.
Upon successful completion of the move, any bound variables are updated with corresponding field values for the new current row.
See Also
DbCursorRelocateRow Function
Purpose
Relocate a row within a cursor that was opened using the default sort index.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorRelocateRow ( uint32_tcursorID
, uint32_tfrom
, uint32_tto
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
. -
→ from
- The index of the row to be moved.
-
→ to
- The index of the position to which the row is to be moved.
Returns
Returns errNone
if the current row position was moved to a valid row within the cursor, or one of the following otherwise:
-
dmErrInvalidParam
- The specified cursor ID is invalid, or the cursor's sort index is not the default sort index.
-
dmErrIndexOutOfRange
- Either
from
orto
exceeds the number of rows in the cursor.
Comments
This function can only be used with cursors opened using the default sort index (that is, a cursor opened without an ORDER BY clause). It allows you to "manually" rearrange the order of the rows in the cursor.
If the row being moved is the current row, the cursor is updated so that the current row position is set to the new location of the moved row.
Cursor row positions are one-based. That is the first row in the cursor has an index value of 1. The last row in the cursor has an index value of DbCursorGetRowCount()
.
See Also
DbCursorMoveToRowID Macro
Purpose
Position the cursor at the row with the specified row ID.
Declared In
SchemaDatabases.h
Prototype
#define DbCursorMoveToRowID (i
,r
)
Parameters
-
→ i
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
. -
→ r
- The ID of the row to which the cursor is to be positioned.
Returns
Returns errNone
if the current row position was changed to a valid row within the cursor, or one of the following otherwise:
Comments
Upon successful completion, any bound variables are updated with corresponding field values for the new current row.
See Also
DbCursorMove()
, DbCursorSetAbsolutePosition()
DbCursorOpen Function
Purpose
Creates and opens a cursor containing all rows in the specified table that conform to a specified set of flags, ordered as specified. No filtering of rows based upon category membership is performed.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorOpen ( DmOpenRefdbRef
, const char*sql
, uint32_tflags
, uint32_t*cursorID
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ sql
- A sort index identifying both the table containing the rows to select from and the manner in which the cursor's rows should be sorted. The sort index must have already been added to the table prior to its use here; see "The SELECT Statement" for the format of this parameter.
-
→ flags
- Zero or more flags (OR'd together) that specify how the cursor is to be opened. See "Cursor Open Flags" for the set of flags defined for this operation.
-
← cursorID
- The ID of the newly-opened cursor. If there was an error opening the cursor,
*cursorID
is set todbInvalidCursorID
.
Returns
Returns errNone
if the cursor was successfully opened, or one of the following otherwise:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,sql
isNULL
, orcursorID
isNULL
. -
dmErrInvalidSortIndex
- One of the sort IDs specified in the supplied SQL isn't valid for the specified database table.
-
dmErrMemError
- The operation couldn't be completed due to insufficient memory.
-
dmErrNotSchemaDatabase
- The database specified by
dbRef
isn't a schema database. -
dmErrSQLParseError
- The SQL specified in the
sql
parameter is invalid. -
dmErrCursorEOF
- The cursor was successfully created but the table contains no rows that match the specified criteria.
Comments
If the ORDER BY clause is omitted (that is, if the SQL string consists solely of the table name, and perhaps a WHERE clause) the cursor rows are not sorted. Such a cursor is said to be opened using the default sort index.
When a cursor is no longer needed, call DbCursorClose()
to free all resources associated with the cursor.
See Also
DbCursorClose()
, DbCursorOpenWithCategory()
DbCursorOpenWithCategory Function
Purpose
Creates and opens a cursor containing all rows in the specified table that conform to a specified set of flags, ordered as specified. Rows are filtered based upon category membership.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorOpenWithCategory ( DmOpenRefdbRef
, const char*sql
, uint32_tflags
, uint32_tnumCategories
, const CategoryIDcategoryIDs[]
, DbMatchModeTypematchMode
, uint32_t*cursorID
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ sql
- A sort index identifying both the table containing the rows to select from and the manner in which the cursor's rows should be sorted. See "The SELECT Statement" for the format of this parameter.
-
→ flags
- Zero or more flags (OR'd together) that specify how the cursor is to be opened. See "Cursor Open Flags" for the set of flags defined for this operation.
-
→ numCategories
- Number of categories in the
categoryIDs
array. -
→ categoryIDs
- Array of category IDs used to filter the cursor. If no categories are specified (that is, if
numCategories
is 0), no filtering based upon categories is done. -
→ matchMode
- One of the following values, indicating how the categories in the
categoryIDs
array are applied to the cursor: -
DbMatchAny
- (OR): Include rows with categories matching any of the specified categories.
-
DbMatchAll
- (AND): Include rows with categories matching all of the specified categories, including rows with additional category membership.
-
DbMatchExact
- Include rows with categories matching exactly the specified categories.
-
← cursorID
- The ID of the newly-opened cursor. If there was an error opening the cursor,
*cursorID
is set todbInvalidCursorID
.
Returns
Returns errNone
if the cursor was successfully opened, or one of the following otherwise:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,sql
isNULL
, orcursorID
isNULL
. -
dmErrInvalidCategory
- One or more of the specified category IDs is invalid.
-
dmErrInvalidSortIndex
- One of the sort IDs specified in the supplied SQL isn't valid for the specified database table.
-
dmErrMemError
- The operation couldn't be completed due to insufficient memory.
-
dmErrNotSchemaDatabase
- The database specified by
dbRef
isn't a schema database. -
dmErrSQLParseError
- The SQL specified in the
sql
parameter is invalid. -
dmErrCursorEOF
- The cursor was successfully created but the table contains no rows that match the specified criteria.
Comments
The sql
, flags
, categoryIDs
, and matchMode
parameters allow your application to specify a subset of the database rows that belong to the cursor. Only the rows that match the specified SQL, flags, and categories (the match mode determines how category matches are applied) will exist in the cursor; those rows are sorted as specified by the sort index.
See Also
DbCursorClose()
, DbCursorOpen()
DbCursorRemoveAllRows Function
Purpose
Remove all of the cursor's rows from the database.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorRemoveAllRows (
uint32_t cursorID
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrInvalidParam
- The specified cursor ID isn't valid.
-
dmErrRecordBusy
- One of the rows is in use and cannot be updated.
-
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
Comments
For each row in the cursor, this function deletes the row's chunk from the database and removes the row entry from the database header.
See Also
DbCursorArchiveAllRows()
, DbCursorDeleteAllRows()
, DbRemoveRow()
DbCursorRequery Function
Purpose
Refresh a cursor to reflect any changes made to the database since the last query. If the cursor's contents change, the cursor is repositioned at the first row.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorRequery (
uint32_t cursorID
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
.
Returns
Returns errNone
if the cursor was successfully refreshed, or one of the following otherwise:
-
dmErrInvalidParam
-
cursorID
isn't a valid cursor ID or doesn't reference an open cursor. -
dmErrInvalidSortIndex
- The sort index is no longer valid.
-
dmErrMemError
- A memory error occurred.
-
dmErrCursorEOF
- The cursor contains no rows.
-
dmErrIndexOutOfRange
- One or more bindings are no longer valid.
Comments
When the cursor is created a snapshot of the row IDs is taken that is used when iterating the cursor's rows. This snapshot of the IDs is not affected by sorting updates due to row modifications or the addition of new rows. DbCursorRequery()
refreshes the snapshot to reflect any new row additions or sorting changes.
Note that when a refresh occurs the current row may move to a new position (the first row, if the cursor contents change), and future move operations will move from the new position instead of the old position.
See Also
DbCursorOpen()
, DbCursorUpdate()
DbCursorSetAbsolutePosition Macro
Purpose
Moves the cursor onto the row with the specified index.
Declared In
SchemaDatabases.h
Prototype
#define DbCursorSetAbsolutePosition (i
,o
)
Parameters
-
→ i
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
. -
→ o
- Index of the row to which the cursor should be positioned.
Returns
Returns errNone
if the current row position was moved to a valid row within the cursor, or one of the following otherwise:
-
dmErrInvalidParam
- The specified cursor ID is invalid.
-
dmErrCursorBOF
- An attempt was made to move to a position before the first row in the cursor.
-
dmErrCursorEOF
- An attempt was made to move to a position after the last row in the cursor.
Comments
The first row within a cursor has an index value of 1.
Attempting to move before the first row in the cursor or attempting to move past the last row in the cursor generates an error, and the cursor's BOF or EOF property, as appropriate, is set.
When moving through the cursor, rows that have been modified are not moved to their new sort position until DbCursorRequery()
is called. Similarly any new rows are not available to the cursor until DbCursorRequery()
is called.
Upon successful completion of the move, any bound variables are updated with corresponding field values for the new current row.
See Also
DbCursorMove()
, DbCursorMoveToRowID()
DbCursorUpdate Function
Purpose
Write the values in the bound variables to the row at the cursor's current position.
Declared In
SchemaDatabases.h
Prototype
status_t DbCursorUpdate (
uint32_t cursorID
)
Parameters
-
→ cursorID
- ID of a valid cursor, as returned from
DbCursorOpen()
orDbCursorOpenWithCategory()
.
Returns
Returns errNone
if the current row position was successfully moved to the specified row within the cursor, or one of the following otherwise:
-
dmErrInvalidParam
-
cursorID
isn't a valid cursor ID or doesn't reference an open cursor. -
dmErrCursorBOF
- The cursor's current position is at BOF, which is not a valid row.
-
dmErrCursorEOF
- The cursor's current position is at EOF, which is not a valid row.
-
dmErrRecordDeleted
- The current row is marked as deleted.
-
dmErrRecordBusy
- The current row is in use and cannot be updated.
-
dmErrMemError
- A memory error occurred.
-
dmErrWriteOutOfBounds
- The write operation exceeded the bounds of the row.
-
dmErrOperationAborted
- The write could not be performed.
Comments
Prior to calling DbCursorUpdate()
, set the bound variables to the desired values. All values are written to the database for the current row. Note that for varying length types (VarChar
and Blob
), you should also set the corresponding data size variable (specified when the cursor column was bound to a variable) to indicate the size of the data to be written back to that field.
See Also
DbCursorBindData()
, DbCursorBindDataWithOffset()
, DbCursorRequery()
DbDeleteRow Function
Purpose
Delete a row's chunk from a database but leave the row entry in the header and mark the row as deleted for the next HotSync operation.
Declared In
SchemaDatabases.h
Prototype
status_t DbDeleteRow ( DmOpenRefdbRef
, uint32_trowID
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row to be deleted.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database, orrowID
isn't a valid cursor or row ID. -
dmErrNotSchemaDatabase
-
dbRef
doesn't reference a schema database. -
dmErrReadOnly
- The specified database is opened in read-only mode.
-
dmErrUniqueIDNotFound
-
rowID
doesn't identify a valid row within the database. -
dmErrIndexOutOfRange
-
rowID
doesn't identify a valid row within the database. -
dmErrRecordDeleted
- The specified record is already marked as deleted.
-
dmErrRecordArchived
- The specified record is marked as archived.
-
dmErrRecordBusy
- The specified record is in use.
-
dmErrCorruptDatabase
- The database is corrupt.
Comments
This function deletes the row's chunk from the database but leaves the row entry in the header and marks the row as deleted. During the next HotSync operation, a conduit can save the row data on the desktop and then remove those row entries in the header that are marked as deleted.
See Also
DbArchiveRow()
, DbCursorDeleteAllRows()
, DbInsertRow()
, DbRemoveRow()
DbEnableSorting Function
Purpose
Turn automatic sorting on or off for a given database.
Declared In
SchemaDatabases.h
Prototype
status_t DbEnableSorting ( DmOpenRefdbRef
, Booleanenable
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ enable
- If
true
, sorting is enabled. Iffalse
, sorting is disabled.
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrInvalidOperation
- The specified database has no sort indices defined.
Comments
If enable
is to true
and automatic sorting was previously turned off, the database is resorted, making all current row indices invalid.
If you don't have authorization to modify the database, this function does nothing.
This function sorts the database according to each defined sort index.
See Also
DbAddSortIndex()
, DbIsSortingEnabled()
DbGetAllColumnDefinitions Function
Purpose
Retrieve all of a table's column definitions.
Declared In
SchemaDatabases.h
Prototype
status_t DbGetAllColumnDefinitions ( DmOpenRefdbRef
, const char*table
, uint32_t*numColumnsP
, DbSchemaColumnDefnType**columnDefnsPP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ table
- Table name.
-
← numColumnsP
- Number of elements in the *
columnDefnsPP
array. -
← columnDefnsPP
- Pointer to an array of
DbSchemaColumnDefnType
structures, each representing a single column definition. The Data Manager allocates the array and returns a pointer to it.
Returns
Returns errNone
if the operation completed successfully, or one of the following if there was an error:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,numColumnsP
isNULL
,columnDefnsPP
isNULL
, ortable
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrMemError
- The function was unable to allocate sufficient memory to contain the column definitions.
-
dmErrInvalidTableName
- The database doesn't contain a table with the specified name.
-
dmErrNoData
- The specified table has no columns defined.
-
dmErrOneOrMoreFailed
- At least one of the column definitions could not be retrieved.
Comments
Your application is responsible for releasing the array allocated by this call. To do this, use DbReleaseStorage()
. After DbReleaseStorage()
is called, the references returned by DbGetAllColumnDefinitions()
must be considered invalid since the underlying storage may have been relocated.
See Also
DbAddColumn()
, DbGetColumnDefinitions()
DbGetAllColumnPropertyValues Function
Purpose
Retrieve all of a table's column property values.
Declared In
SchemaDatabases.h
Prototype
status_t DbGetAllColumnPropertyValues ( DmOpenRefdbRef
, const char*table
, BooleancustomPropsOnly
, uint32_t*numPropsP
, DbColumnPropertyValueType**propValuesPP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ table
- Table name.
-
→ customPropsOnly
- If
true
, only user-defined custom column property values are retrieved. Otherwise, all default (built-in) and custom column property values are retrieved. -
← numPropsP
- Number of elements in the
*propValuesPP
array. -
← propValuesPP
- Pointer to an array of
DbColumnPropertyValueType
structures, each representing a single column property value. The Data Manager allocates the array and returns a pointer to it.
Returns
Returns errNone
if the property value was successfully retrieved, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,numPropsP
isNULL
,propValuesPP
isNULL
, ortable
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrInvalidTableName
- The database doesn't contain a table with the specified name.
-
dmErrMemError
- A memory error occurred.
-
dmErrInvalidColumnID
- The specified table has no defined columns.
-
memErrNotEnoughSpace
- A memory error occurred.
Comments
The customPropsOnly
argument controls whether all properties or just custom properties are retrieved. Default properties include: dbColumnNameProperty
, dbColumnDatatypeProperty
, dbColumnSizeProperty
and dbColumnAttribProperty
.
Your application is responsible for releasing the array allocated by this call. To do this, use DbReleaseStorage()
. After DbReleaseStorage()
is called, the references returned by DbGetAllColumnPropertyValues()
must be considered invalid since the underlying storage may have been relocated.
See Also
DbGetColumnPropertyValue()
, DbGetColumnPropertyValues()
, DbSetColumnPropertyValues()
DbGetAllColumnValues Function
Purpose
Retrieve all column values for a specified row.
Declared In
SchemaDatabases.h
Prototype
status_t DbGetAllColumnValues ( DmOpenRefdbRef
, uint32_trowID
, uint32_t*numColumnsP
, DbSchemaColumnValueType**columnValuesPP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row for which column values are to be retrieved.
-
← numColumnsP
- The number of retrieved column values.
-
← columnValuesPP
- Pointer to an array of structures, each representing a single column value. The Data Manager allocates the array and returns a pointer to it.
Returns
Returns errNone
if successful, or one of the following if an error occurred:
-
dmErrInvalidParam
-
rowID
is not a row or cursor ID,dbRef
doesn't reference an open database, orcolumnValuesPP
isNULL
. -
dmErrCursorBOF
- The supplied cursor ID is BOF.
-
dmErrCursorEOF
- The supplied cursor ID is EOF.
-
dmErrUniqueIDNotFound
- The supplied cursor ID represents an invalid row.
-
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrUniqueIDNotFound
- The supplied row or cursor ID doesn't correspond to a row within the database.
-
dmErrRecordDeleted
- The specified row is marked as deleted.
-
dmErrInvalidColSpec
- There are no columns defined for the specified table.
-
dmErrNoColumnData
- The specified row has no data.
-
dmErrMemError
- A memory error occurred.
Comments
Your application is responsible for releasing the array allocated by this call. To do this, use DbReleaseStorage()
. After DbReleaseStorage()
is called, the references returned by DbGetAllColumnValues()
must be considered invalid since the underlying storage may have been relocated.
See Also
DbCopyColumnValues()
, DbGetColumnValue()
, DbGetColumnValues()
, DbWriteColumnValues()
DbGetCategory Function
Purpose
Retrieve the category membership for the specified row.
Declared In
SchemaDatabases.h
Prototype
status_t DbGetCategory ( DmOpenRefdbRef
, uint32_trowID
, uint32_t*pNumCategories
, CategoryID*pCategoryIDs[]
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row for which to get categories.
-
← pNumCategories
- The number of elements in the
pCategoryIDs
array. -
← pCategoryIDs
- Array of category IDs. The specified row is a member of each of the categories in this list. Pass
NULL
for this parameter if all you want is the number of categories of which this row is a member.
Returns
Returns errNone
if no error, or one of the following if an error occurs:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database, or the specified row or cursor ID is not valid. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrIndexOutOfRange
- The specified row or cursor ID doesn't reference a row within the table.
-
dmErrRecordDeleted
- The specified row is marked as deleted.
-
dmErrMemError
- A memory error occurred.
Comments
Your application is responsible for releasing the array allocated by this call. To do this, use DbReleaseStorage()
. After DbReleaseStorage()
is called, the references returned by DbGetCategory()
must be considered invalid since the underlying storage may have been relocated.
If the specified row isn't a member of any categories, this function sets *pNumCategories
to 0 and *
pCategoryIDs
to NULL
.
See Also
DbAddCategory()
, DbIsRowInCategory()
, DbSetCategory()
DbGetColumnDefinitions Function
Purpose
Retrieve one or more table column definitions.
Declared In
SchemaDatabases.h
Prototype
status_t DbGetColumnDefinitions ( DmOpenRefdbRef
, const char*table
, uint32_tnumColumns
, const uint32_tcolumnIDs[]
, DbSchemaColumnDefnType**columnDefnsPP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ table
- Table name.
-
→ numColumns
- The number of columns in the
columnIDs
array. -
→ columnIDs
- Array of column IDs, indicating the columns for which definitions are to be retrieved.
-
← columnDefnsPP
- Pointer to an array of
DbSchemaColumnDefnType
structures; each array element contains the definition for a column.
Returns
Returns errNone
if the operation completed successfully, or one of the following if there was an error:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,columnIDs
isNULL
,columnDefnsPP
isNULL
, ortable
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrMemError
- The function was unable to allocate sufficient memory to contain the column definitions.
-
dmErrInvalidTableName
- The database doesn't contain a table with the specified name.
-
dmErrInvalidColumnID
- The specified table has no columns defined.
-
dmErrOneOrMoreFailed
- At least one of the column definitions could not be retrieved.
Comments
Your application is responsible for releasing the array allocated by this call. To do this, use DbReleaseStorage()
. After DbReleaseStorage()
is called, the references returned by DbGetColumnDefinitions()
must be considered invalid since the underlying storage may have been relocated.
See Also
DbAddColumn()
, DbGetAllColumnDefinitions()
DbGetColumnID Function
Purpose
Retrieve the column ID for a column index.
Declared In
SchemaDatabases.h
Prototype
status_t DbGetColumnID ( DmOpenRefdbRef
, const char*table
, uint32_tcolumnIndex
, uint32_t*columnIDP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ table
- Table name.
-
→ columnIndex
- The index of the column for which the ID is being retrieved.
-
← columnIDP
- The column ID.
Returns
Returns errNone
if the column ID was successfully retrieved, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database, ortable
isNULL
. -
dmErrNotSchemaDatabase
- The specified database isn't a schema database.
-
dmErrInvalidTableName
- The database doesn't contain a table with the specified name.
-
dmErrColumnIndexOutOfRange
- The supplied column index exceeds the number of columns in the table.
Comments
See the Comments section under DbNumColumns()
for an example of how you use this function.
See Also
DbGetColumnPropertyValue Function
Purpose
Retrieve the value of a specified table column property.
Declared In
SchemaDatabases.h
Prototype
status_t DbGetColumnPropertyValue ( DmOpenRefdbRef
, const char*table
, uint32_tcolumnID
, DbSchemaColumnPropertypropID
, uint32_t*numBytesP
, void**propValuePP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ table
- Table name.
-
→ columnID
- The ID of the column for which the property is being retrieved.
-
→ propID
- The ID of the property being retrieved.
-
← numBytesP
- The size, in bytes, of the retrieved property value.
-
← propValuePP
- The retrieved property value.
Returns
Returns errNone
if the property value was successfully retrieved, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,numBytesP
isNULL
,propValuePP
isNULL
, ortable
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrInvalidTableName
- The database doesn't contain a table with the specified name.
-
dmErrInvalidColumnID
- The specified table has no defined columns, or the specified column index is not a defined column.
-
dmErrInvalidPropID
- The column doesn't have a property with the specified property ID.
-
memErrNotEnoughSpace
- A memory error occurred.
Comments
Your application is responsible for releasing the memory allocated by this call to contain the property value. To do this, use DbReleaseStorage()
. After DbReleaseStorage()
is called, the references returned by DbGetColumnPropertyValue()
must be considered invalid since the underlying storage may have been relocated.
See Also
DbGetAllColumnPropertyValues()
, DbGetColumnPropertyValues()
, DbSetColumnPropertyValue()
DbGetColumnPropertyValues Function
Purpose
Retrieve the value of one or more table column properties.
Declared In
SchemaDatabases.h
Prototype
status_t DbGetColumnPropertyValues ( DmOpenRefdbRef
, const char*table
, uint32_tnumProps
, const DbColumnPropertySpecTypepropSpecs[]
, DbColumnPropertyValueType**propValuesPP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ table
- Table name.
-
→ numProps
- The number of elements in the
propSpecs
array. -
→ propSpecs
- Array of column ID/property ID pairs. See "DbColumnPropertySpecType."
-
← propValuesPP
- Array of property values. See "DbColumnPropertyValueType."
Returns
Returns errNone
if the property value was successfully retrieved, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,numProps
is zero,propSpecs
isNULL
,propValuePP
isNULL
, ortable
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrInvalidTableName
- The database doesn't contain a table with the specified name.
-
dmErrMemError
- A memory error occurred.
-
dmErrInvalidColumnID
- The specified table has no defined columns, or the at least one of the specified column indices is not a defined column.
-
dmErrInvalidPropID
- At least one column doesn't have a property with the specified property ID.
-
memErrNotEnoughSpace
- A memory error occurred.
Comments
Your application is responsible for releasing the array allocated by this call. To do this, use DbReleaseStorage()
. After DbReleaseStorage()
is called, the references returned by DbGetColumnPropertyValues()
must be considered invalid since the underlying storage may have been relocated.
See Also
DbGetAllColumnPropertyValues()
, DbGetColumnPropertyValue()
, DbSetColumnPropertyValues()
DbGetColumnValue Function
Purpose
Retrieve a single column value for a row.
Declared In
SchemaDatabases.h
Prototype
status_t DbGetColumnValue ( DmOpenRefdbRef
, uint32_trowID
, uint32_tcolumnID
, uint32_toffset
, void**valuePP
, uint32_t*valueSizeP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row for which the column value is to be retrieved.
-
→ columnID
- The column ID.
-
→ offset
- For variable-length columns, the column value offset from which data is retrieved. This value is interpreted as a byte offset.
-
← valuePP
- The column value.
-
← valueSizeP
- The size of the column value, in bytes.
Returns
Returns errNone
if successful, or one of the following if an error occurred:
-
dmErrInvalidParam
-
rowID
is not a row or cursor ID, orvaluePP
isNULL
. -
dmErrCursorBOF
- The supplied cursor ID is BOF.
-
dmErrCursorEOF
- The supplied cursor ID is EOF.
-
dmErrUniqueIDNotFound
- The supplied cursor ID represents an invalid row.
-
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrUniqueIDNotFound
- The supplied row or cursor ID doesn't correspond to a row within the database.
-
dmErrRecordDeleted
- The specified row is marked as deleted.
-
dmErrInvalidColSpec
- There are no columns defined for the specified table.
-
dmErrInvalidColumnID
- The supplied column ID is invalid.
-
dmErrNoColumnData
- The specified row has no data for the column.
-
dmErrReadOutOfBounds
- The specified offset exceeds the bounds of the column.
-
dmErrBufferNotLargeEnough
- The supplied buffer isn't large enough to contain the column value.
-
dmErrMemError
- A memory error occurred.
Comments
This function returns a reference to the column data. Offset-based reads are not supported for fixed-length column data types; the offset parameter is ignored for these data types. The column data types that support offset-based reads are:
Your application is responsible for releasing the column value buffer allocated by this call. To do this, use DbReleaseStorage()
.
See Also
DbCopyColumnValue()
, DbGetAllColumnValues()
, DbGetColumnValues()
, DbWriteColumnValue()
DbGetColumnValues Function
Purpose
Retrieve one or more column values for a row.
Declared In
SchemaDatabases.h
Prototype
status_t DbGetColumnValues ( DmOpenRefdbRef
, uint32_trowID
, uint32_tnumColumns
, const uint32_tcolumnIDs
, DbSchemaColumnValueType**columnValuesPP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row for which the column values are to be retrieved.
-
→ numColumns
- The number of elements in the
columnIDs
array. -
→ columnIDs
- Array of one or more column IDs indicating the columns for which values are to be retrieved.
-
← columnValuesPP
- An array of data structures containing the retrieved column values.
Returns
Returns errNone
if successful, or one of the following if an error occurred:
-
dmErrInvalidParam
-
rowID
is not a row or cursor ID,dbRef
doesn't reference an open database,numColumns
is zero, orcolumnValuesPP
isNULL
. -
dmErrCursorBOF
- The supplied cursor ID is BOF.
-
dmErrCursorEOF
- The supplied cursor ID is EOF.
-
dmErrUniqueIDNotFound
- The supplied cursor ID represents an invalid row.
-
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrUniqueIDNotFound
- The supplied row or cursor ID doesn't correspond to a row within the database.
-
dmErrRecordDeleted
- The specified row is marked as deleted.
-
dmErrInvalidColSpec
- There are no columns defined for the specified table.
-
dmErrInvalidColumnID
- The one or more of the specified column IDs is invalid.
-
dmErrNoColumnData
- The specified row has no data.
-
dmErrBufferNotLargeEnough
- At least one of the supplied buffers isn't large enough to contain the corresponding column value.
-
dmErrMemError
- A memory error occurred.
Comments
Your application is responsible for releasing the array allocated by this call. To do this, use DbReleaseStorage()
. After DbReleaseStorage()
is called, the references returned by DbGetColumnValues()
must be considered invalid since the underlying storage may have been relocated.
See Also
DbCopyColumnValues()
, DbGetAllColumnValues()
, DbGetColumnValue()
, DbWriteColumnValues()
DbGetRowAttr Function
Purpose
Declared In
SchemaDatabases.h
Prototype
status_t DbGetRowAttr ( DmOpenRefdbRef
, uint32_trowID
, uint16_t*attrP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row for which attributes are to be retrieved.
-
← attrP
- The row's attributes. See "Schema Database Row Attributes" for the set of attributes that can be retrieved.
Returns
Returns errNone
if the row's attributes were successfully retrieved, or one of the following if an error occurred:
-
dmErrNotRecordDB
- You've attempted to perform a row function on a resource database.
-
dmErrIndexOutOfRange
- The specified index is out of range.
See Also
DbGetTableForRow()
, DbSetRowAttr()
DbGetRuleSet Function
Purpose
Get the current access rules for a secure database.
Declared In
SchemaDatabases.h
Prototype
status_t DbGetRuleSet ( DatabaseIDdbID
, AzmRuleSetType*ruleset
)
Parameters
-
→ dbID
- ID of the secure database for which access rules are to be retrieved.
-
← ruleset
- Handle to the database's access rules.
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbID
doesn't reference a database orruleset
isNULL
. -
dmErrNotSecureDatabase
- The specified database is not a secure database.
-
dmErrAccessDenied
- You don't have sufficient privileges to obtain the database's access rules.
Comments
The database must exist, and must be a secure database.
This function requires that the calling application to be authorized for the Modify action as defined by the Authorization Manager (that is, it must be the application that created the secure database). If the application does not have modification rights, the function fails with dmErrAccessDenied
.
See Also
DbCreateSecureDatabase()
, DbCreateSecureDatabaseFromImage()
DbGetSortDefinition Function
Purpose
Get a sort index given its position in the list of sort indices defined for a database.
Declared In
SchemaDatabases.h
Prototype
status_t DbGetSortDefinition ( DmOpenRefdbRef
, uint32_tsortIndex
, char**orderByPP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ sortIndex
- An integer index value, ranging from 0 to one less than the value returned from
DbNumSortIndexes()
, indicating which sort index is desired. -
← orderByPP
- Upon return,
*
orderByPP
points to the SQL string that makes up the sort index.
Returns
Returns errNone
if the operation succeeded, or one of the following otherwise:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrInvalidIndex
- The
sortIndex
parameter is greater than the highest sort index value defined for this database.
Comments
See the Comments section under DbNumSortIndexes()
for an example of how you use this function.
DbGetTableForRow Function
Purpose
Obtain the name of the table that contains a specified row.
Declared In
SchemaDatabases.h
Prototype
status_t DbGetTableForRow ( DmOpenRefdbRef
, uint32_trowID
, char*buf
, size_tbufSize
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row for which the table is to be determined.
-
← buf
- Pass a pointer to the buffer into which the table name is to be written.
-
→ bufSize
- The size of
buf
, in bytes.
Returns
Returns errNone
if the operation succeeded, or one of the following otherwise:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,rowID
isn't a row or cursor ID,buf
isNULL
, orbufSize
is zero. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrUniqueIDNotFound
- The specified row or cursor ID doesn't correspond to a row in the database.
-
dmErrMemError
- The supplied buffer isn't large enough to contain the table name, or another memory error occurred.
See Also
DbGetTableName Function
Purpose
Obtain a table's name, given the index of the table within a database.
Declared In
SchemaDatabases.h
Prototype
status_t DbGetTableName ( DmOpenRefdbRef
, uint32_tindex
, char*table
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ index
- Index of the table within the database.
-
← table
- Table name.
Returns
Returns errNone
if the operation succeeded, or one of the following otherwise:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database, ortable
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrSchemaIndexOutOfRange
- The specified index is greater than the number of tables in the database.
Comments
Table indices are zero-based. That is, the first table in a database has an index value of zero.
See Also
DbGetTableSchema Function
Purpose
Get the schema for a table, including the definitions and properties for all of the table's columns.
Declared In
SchemaDatabases.h
Prototype
status_t DbGetTableSchema ( DmOpenRefdbRef
, const char*table
, DbTableDefinitionType**schemaPP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ table
- Table name.
-
← schemaPP
- The schema. Allocate a pointer to a
DbTableDefinitionType
structure and supply the address of this pointer when callingDbGetTableSchema()
. Upon return, your pointer variable contains the address of aDbTableDefinitionType
structure containing the table name, the number of columns in the table, and a pointer to the first element in an array of column definition.
Returns
Returns errNone
if the schema was successfully retrieved, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open databases, no table name was specified, orschemaPP
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrInvalidTableName
- The database doesn't contain a table with the specified name.
-
dmErrMemError
- A memory error occurred.
Comments
Your application is responsible for releasing the buffer pointed to by *schemaPP
. To do this, use DbReleaseStorage()
. After DbReleaseStorage()
is called, the references returned by DbGetTableSchema()
must be considered invalid since the underlying storage may have been relocated.
See Also
DbGetTableName()
, DbHasTable()
DbHasSortIndex Function
Purpose
Determine whether a particular sort index has been defined for a database.
Declared In
SchemaDatabases.h
Prototype
Boolean DbHasSortIndex ( DmOpenRefdbRef
, const char*orderBy
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ orderBy
- The sort index being checked for. See "The SELECT Statement" for the format of this parameter.
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrSQLParseError
- The specified table name or the sort information specified in the sort index is invalid.
See Also
DbAddSortIndex()
, DbRemoveSortIndex()
DbHasTable Function
Purpose
Determine whether a specific table exists in a particular database.
Declared In
SchemaDatabases.h
Prototype
Boolean DbHasTable ( DmOpenRefdbRef
, const char*table
)
Parameters
Returns
Returns true
if the specified database contains the named table. Returns false
if either the table doesn't exist in the database, dbRef
is not a valid reference to an open database, or the specified database is not a schema database.
See Also
DbGetTableName()
, DbGetTableSchema()
DbInsertRow Function
Purpose
Add a row to a specified database table.
Declared In
SchemaDatabases.h
Prototype
status_t DbInsertRow ( DmOpenRefdbRef
, const char*table
, uint32_tnumColumnValues
, DbSchemaColumnValueType*columnValuesP
, uint32_t*rowIDP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ table
- Table name.
-
→ numColumnValues
- Number of column values in the
columnValuesP
array. -
→ columnValuesP
- Array of column values, where each value represents a column value for the new row.
-
← rowIDP
- Row ID of the newly added row, or
dbInvalidRowID
if the row couldn't be added.
Returns
Returns errNone
if the row was added successfully, or one of the following otherwise:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database. -
dmErrInvalidTableName
- The specified table name is invalid.
-
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrInvalidColSpec
- One or more column values doesn't fit in the corresponding column.
-
dmErrInvalidColumnID
- The number of column values supplied exceeds the number of columns in the table.
-
dmErrMemError
- A memory error occurred.
Comments
The new row is added to the end of the database. Any open cursors are not updated; use DbCursorRequery()
to update a particular cursor's contents.
If numColumnValues
is zero or columnValuesP
is NULL
, an empty row is created which may subsequently be written into using either DbWriteColumnValue()
or DbWriteColumnValues()
.
See Also
DbArchiveRow()
, DbDeleteRow()
, DbRemoveRow()
DbIsCursorID Function
Purpose
Determine whether a specified ID is a cursor ID.
Declared In
SchemaDatabases.h
Prototype
Boolean DbIsCursorID (
uint32_t uniqueID
)
Parameters
Returns
Returns true
if uniqueID
is a cursor ID, false
otherwise.
Comments
Cursor IDs can generally be used interchangeably with row IDs. If you are using a cursor, however, it is more efficient to use a cursor ID.
See Also
DbIsRowID Function
Purpose
Determine whether a specified ID is a row ID.
Declared In
SchemaDatabases.h
Prototype
Boolean DbIsRowID (
uint32_t uniqueID
)
Parameters
Returns
Returns true
if uniqueID
is a row ID, false
otherwise.
Comments
Cursor IDs can generally be used interchangeably with row IDs. If you are using a cursor, however, it is more efficient to use a cursor ID.
See Also
DbIsRowInCategory Function
Purpose
Determine whether a row is a member of the specified categories, depending on the given match mode criteria.
Declared In
SchemaDatabases.h
Prototype
status_t DbIsRowInCategory ( DmOpenRefdbRef
, uint32_trowID
, uint32_tnumCategories
, const CategoryIDcategoryIDs[]
, DbMatchModeTypematchMode
, Boolean*pIsInCategory
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row for which category membership is to be checked.
-
→ numCategories
- Number of categories in the
categoryIDs
array. -
→ categoryIDs
- Array of category ID values.
-
→ matchMode
- One of the following values:
-
DbMatchAny
- (OR) Set
pIsInCategory
totrue
if the row membership includes any of the categories specified in thecategoryIDs
array. -
DbMatchAll
- (AND) Set
pIsInCategory
totrue
if the row membership includes all of the categories specified in thecategoryIDs
array, including rows with additional category membership. -
DbMatchExact
- Set
pIsInCategory
totrue
if the row membership exactly matches the categories specified in thecategoryIDs
array. -
← pIsInCategory
-
true
if the row at the given index position has membership in the given category set according to the supplied match mode value.false
otherwise.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,rowID
isn't a row or cursor ID,numCategories
is zero andcategoryIDs
is notNULL
,numCategories
is nonzero andcategoryIDs
isNULL
, ormatchMode
isn't one of the allowable values. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrUniqueIDNotFound
- The specified row ID doesn't reference a row within the database.
-
dmErrRecordDeleted
- The indicated row is marked as deleted.
-
dmErrMemError
- A memory error occurred.
Comments
To check whether a row has no category membership (that is, it belongs to the "Unfiled" category), set numCategories
to 0 and categoryIDs
to NULL
.
This function might always return false
if
- none of the supplied category IDs is a valid category ID, and the supplied match mode criteria value is
DbMatchAny
. - any of the supplied category IDs is not a valid category ID, and the supplied match mode criteria value is either
DbMatchAll
orDbMatchExact
.
See Also
DbIsSortingEnabled Function
Purpose
Determine whether a given database keeps its contents sorted according to one or more sort indices.
Declared In
SchemaDatabases.h
Prototype
status_t DbIsSortingEnabled ( DmOpenRefdbP
, Boolean*enableP
)
Parameters
-
→ dbP
-
DmOpenRef
to an open database. -
← enableP
-
true
if the database contents are kept sorted,false
otherwise.
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
See Also
DbMoveCategory Function
Purpose
Change the category membership for rows meeting a set of category criteria to a specified category.
Declared In
SchemaDatabases.h
Prototype
status_t DbMoveCategory ( DmOpenRefdbRef
, CategoryIDtoCategory
, uint32_tnumFromCategories
, const CategoryIDfromCategoryIDs[]
, DbMatchModeTypematchMode
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ toCategory
- Category ID to which row membership should be moved.
-
→ numFromCategories
- Number of elements in the
fromCategoryIDs
array. -
→ fromCategoryIDs
- Array of category ID values from which row membership is to be moved.
-
→ matchMode
- One of the following values:
-
DbMatchAny
- (OR) Replace category membership for rows with membership that includes any of the categories specified in the
fromCategoryIDs
array. -
DbMatchAll
- (AND) Replace category membership for rows with membership that includes all of the categories specified in the
fromCategoryIDs
array, including rows with additional category membership. -
DbMatchExact
- Replace category membership for rows with membership that exactly matches the categories specified in the
fromCategoryIDs
array.
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,numCategories
is zero andfromCategoryIDs
is notNULL
,numCategories
is nonzero andfromCategoryIDs
isNULL
, ormatchMode
isn't one of the allowable values. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The specified database is a read-only database or is open in read-only mode.
-
dmErrMemError
- A memory error occurred.
-
dmErrInvalidCategory
- One or more of the specified categories is not a valid category.
-
dmErrRecordBusy
- At least one of the database's rows is in use and cannot be updated.
Comments
The database must be opened with write access.
An application can also move row membership from no membership ("Unfiled") to membership in a single category by
- specifying a valid category ID value for the
toCategory
parameter, AND - specifying
NULL
for thefromCategoryIDs
parameter and 0 fornumFromCategories
. In this case, thematchMode
parameter is ignored.
This function might perform no action if
- none of the category IDs in
fromCategoryIDs
are valid and the match mode criteria value isDbMatchAny
. - any of the category IDs in
fromCategoryIDs
are not valid and the match mode criteria value is eitherDbMatchAll
orDbMatchExact
.
See Also
DbNumCategory Function
Purpose
Determine how many categories a specified row is a member of.
Declared In
SchemaDatabases.h
Prototype
status_t DbNumCategory ( DmOpenRefdbRef
, uint32_trowID
, uint32_t*pNumCategories
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row being analyzed.
-
← pNumCategories
- The number of categories of which the row is a member.
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,rowID
isn't a row or cursor ID, orpNumCategories
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrUniqueIDNotFound
- The specified row ID doesn't reference a row within the database.
-
dmErrRecordDeleted
- The indicated row is marked as deleted.
-
dmErrMemError
- A memory error occurred.
See Also
DbNumColumns Function
Purpose
Get the number of columns in a specified table.
Declared In
SchemaDatabases.h
Prototype
status_t DbNumColumns ( DmOpenRefdbRef
, const char*table
, uint32_t*columnCountP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ table
- Table name.
-
← columnCountP
- The number of columns in the table.
Returns
Returns errNone
if the operation completed successfully, or one of the following if there was an error:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database ortable
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrInvalidTableName
- The database doesn't contain a table with the specified name.
Comments
Column IDs are zero-based. That is, they range from zero to one less than the value returned by this function.
Example
You can easily iterate through all of the columns in a table by doing something like this:
uint32_t numCols; uint32_t idx; uint32_t colID; err = DbNumColumns(myDatabase, myTableName, &numCols); for(idx = 0; idx < numCols; idx++){ err = DbGetColumnID(myDatabase, myTableName, idx, &colID); // do something based upon colID here }
See Also
DbGetAllColumnDefinitions()
, DbGetColumnDefinitions()
, DbGetColumnID()
DbNumSortIndexes Function
Purpose
Get the number of sort indices defined for a given database.
Declared In
SchemaDatabases.h
Prototype
status_t DbNumSortIndexes ( DmOpenRefdbRef
, uint32_t*countP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
← countP
- The number of sort indices defined for the database.
Returns
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
Comments
This function returns the number of sort indices that are defined for a specified database. The index values of those sort indices range from 0 to one less than the value that this function returns. Most functions that take a sort index as an argument require the SQL statement used to create the sort index.
Example
Code that iterates through all of the sort indices in a database might look something like this:
uint32_t numSortIndexes, idx; char *sortIndex; err = DbNumSortIndexes(myDatabase, &numSortIndexes); if (err == errNone){ for (idx = 0; idx < numSortIndexes; idx++){ err = DbGetSortDefinition(myDatabase, idx, &sortIndex); if (err == errNone){ // process sort index here. The SQL is in *sortIndex } } }
See Also
DbGetSortDefinition()
, DbHasSortIndex()
DbNumTables Function
Purpose
Get the number of tables defined for a given database.
Declared In
SchemaDatabases.h
Prototype
status_t DbNumTables ( DmOpenRefdbRef
, uint32_t*tableCountP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
← tableCountP
- The number of schemas defined for the database.
Returns
Returns errNone
if no error, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
Comments
This function returns the number of tables that a specified database contains. The indices of those tables range from 0 to one less than the value that this function returns. Most functions that take a table as an argument require the table's name.
Example
Code that iterates through all of the tables in a database might look something like this:
uint32_t numTables, idx; char tblName[dbDBNameLength]; err = DbNumTables(myDatabase, &numTables); if (err == errNone){ for (idx = 0; idx < numTables; idx++){ err = DbGetTableName(myDatabase, idx, tblName); if (err == errNone){ // process table here } } }
See Also
DbOpenDatabase Function
Purpose
Open a schema database and return a reference to it.
Declared In
SchemaDatabases.h
Prototype
DmOpenRef DbOpenDatabase ( DatabaseIDdbID
, DmOpenModeTypemode
, DbShareModeTypeshare
)
Parameters
-
→ dbID
- The database ID of the schema database to be opened.
-
→ mode
- Access mode with which to open the database. See
DmOpenModeType
for the set of values that you can supply for this parameter. -
→ share
- How the database can be accessed by other applications while your application has it open. See the definition of
DbShareModeType
for the set of values that you can supply for this parameter.
Returns
A DmOpenRef
to the open database. This function may display a fatal error message if dbID
is NULL
. For all other errors, this function returns 0; call DmGetLastErr()
to obtain an error code indicating the reason for failure.
Comments
The database must exist and either the application or the user—or both—must have correct access to open the database in the specified mode.
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
DbCloseDatabase()
, DbOpenDatabaseByName()
DbOpenDatabaseByName Function
Purpose
Open the most recent revision of a schema database with the given name and creator and return a reference to it.
Declared In
SchemaDatabases.h
Prototype
DmOpenRef DbOpenDatabaseByName ( uint32_tcreator
, const char*name
, DmOpenModeTypemode
, DbShareModeTypeshare
)
Parameters
-
→ creator
- Schema database creator.
-
→ name
- Schema database type.
-
→ mode
- Access mode with which to open the database. See
DmOpenModeType
for the set of values that you can supply for this parameter. -
→ share
- How the database can be accessed by other applications while your application has it open. See the definition of
DbShareModeType
for the set of values that you can supply for this parameter.
Returns
A DmOpenRef
to the open database. This function may display a fatal error message if dbID
is NULL
. For all other errors, this function returns 0; call DmGetLastErr()
to obtain an error code indicating the reason for failure.
Comments
The database must exist and either the application or the user—or both—must have correct access to open the database in the specified mode.
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
DbCloseDatabase()
, DbOpenDatabase()
DbReleaseStorage Function
Purpose
Release memory that was allocated by the operating system and returned to your application as the result of a function call such as DbGetColumnValues()
.
Declared In
SchemaDatabases.h
Prototype
status_t DbReleaseStorage ( DmOpenRefdbRef
, void*ptr
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ ptr
- Pointer to the memory to be released. This block of memory must have been allocated by the operating system during the course of a call to one of the functions listed in the Comments section, below.
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
isNULL
orptr
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The specified database is a read-only database or is open in read-only mode.
-
dmErrCantFind
- The block wasn't allocated by calling one of the functions listed in the Comments section, below.
-
dmErrInvalidID
- A column value cannot be freed because the ID of the row containing the value is invalid.
-
dmErrUniqueIDNotFound
- A column value cannot be freed because the row containing the value cannot be located.
-
dmErrInvalidTableName
- A column property value cannot be freed because the table name is no longer valid.
-
dmErrInvalidColumnName
- A column property value cannot be freed because the name of the column is no longer valid.
-
dmErrInvalidColumnID
- A column property value cannot be freed because the column's ID is no longer valid.
Comments
Releases memory allocated by the following functions:
-
DbGetColumnValue()
-
DbGetColumnValues()
-
DbGetAllColumnValues()
-
DbGetColumnPropertyValue()
-
DbGetColumnPropertyValues()
-
DbGetAllColumnPropertyValues()
-
DbGetColumnDefinitions()
-
DbGetAllColumnDefinitions()
DbRemoveCategory Function
Purpose
Remove membership in the specified categories from a single row.
Declared In
SchemaDatabases.h
Prototype
status_t DbRemoveCategory ( DmOpenRefdbRef
, uint32_trowID
, uint32_tnumToRemove
, const CategoryIDcategoryIDs[]
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row for which category membership is to be altered.
-
→ numToRemove
- Number of categories in the
categoryIDs
array. -
→ categoryIDs
- Array of category IDs indicating those categories for which the specified row is no longer to be a member.
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,rowID
isn't a row or cursor ID, ornumToRemove
is nonzero andcategoryIDs
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The specified database is a read-only database or is open in read-only mode.
-
dmErrUniqueIDNotFound
- The specified row ID doesn't reference a row within the database.
-
dmErrMemError
- A memory error occurred.
-
dmErrInvalidCategory
- One or more of the specified categories is not a valid category.
-
dmErrRecordBusy
- The row is in use and cannot be updated.
Comments
This function removes the specified category memberships from the specified row but does not remove the actual category definitions themselves, which are defined at the database level.
The database must be opened with write access. The specified category IDs must be valid.
This function ignores category IDs for which the specified row is not a member. If the categoryIDs
array contains multiple instances of a given category ID, the category membership is removed when the first instance is encountered; the remaining instances are ignored.
See Also
DbAddCategory()
, DbMoveCategory()
, DbRemoveCategoryAllRows()
, DbSetCategory()
DbRemoveCategoryAllRows Function
Purpose
Remove category membership in the specified categories from all rows in the database, depending on the match mode criteria.
Declared In
SchemaDatabases.h
Prototype
status_t DbRemoveCategoryAllRows ( DmOpenRefdbRef
, uint32_tnumCategories
, const CategoryIDcategoryIDs[]
, DbMatchModeTypematchMode
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ numCategories
- Number of categories in the
categoryIDs
array. -
→ categoryIDs
- Array of category IDs indicating those categories for which the specified row is no longer to be a member.
-
→ matchMode
- One of the following values:
-
DbMatchAny
- (OR): Remove categories from rows matching any of the specified categories.
-
DbMatchAll
- (AND): Remove categories from rows matching all of the specified categories, including rows with additional category membership.
-
DbMatchExact
- Remove categories from rows matching exactly the specified categories.
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,numCategories
is zero andcategoryIDs
is notNULL
,numCategories
is nonzero andcategoryIDs
isNULL
, ormatchMode
isn't one of the allowable values. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The specified database is a read-only database or is open in read-only mode.
-
dmErrMemError
- A memory error occurred.
-
dmErrInvalidCategory
- One or more of the specified categories is not a valid category.
-
dmErrRecordBusy
- At least one of the database's rows is in use and cannot be updated.
Comments
This function removes the specified category memberships from the specified row but does not remove the actual category definitions themselves, which are defined at the database level.
The database must be opened with write access. The specified category IDs must be valid.
This function might perform no action if
- none of the supplied category IDs are valid and the match mode is
DbMatchAny
. - any of the category IDs are not valid and the match mode is either
DbMatchAll
orDbMatchExact
.
See Also
DbAddCategory()
, DbRemoveCategory()
, DbSetCategory()
DbRemoveColumn Function
Purpose
Remove a column definition from a specified database schema and remove that column's data for all table rows described by that schema.
Declared In
SchemaDatabases.h
Prototype
status_t DbRemoveColumn ( DmOpenRefdbRef
, const char*table
, uint32_tcolumnID
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ table
- Table name.
-
→ columnID
- ID of the column being removed.
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database, ortable
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrAccessDenied
- You do not have authorization to modify the schema.
-
dmErrInvalidTableName
- The database doesn't contain a table with the specified name.
-
dmErrColumnDefinitionsLocked
- The table's column definitions are locked.
-
dmErrInvalidColSpec
- The table has no columns defined.
-
dmErrInvalidColumnID
- The specified table doesn't have a column with the supplied column ID.
-
dmErrRecordBusy
- One or more rows are in use and cannot be modified.
-
dmErrMemError
- A memory error occurred.
See Also
DbAddColumn()
, DbRemoveColumnProperty()
DbRemoveColumnProperty Function
Purpose
Remove a single column property from a database table.
Declared In
SchemaDatabases.h
Prototype
status_t DbRemoveColumnProperty ( DmOpenRefdbRef
, const char*table
, uint32_tcolumnID
, DbSchemaColumnPropertypropID
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ table
- Table name.
-
→ columnID
- ID of the column for which the property is being removed.
-
→ propID
- ID of the column property being removed.
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database, ortable
isNULL
. -
dmErrBuiltInProperty
- The column property you are trying to remove is a built-in property; it cannot be removed.
-
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrAccessDenied
- You do not have authorization to modify the schema.
-
dmErrInvalidTableName
- The database doesn't contain a table with the specified name.
-
dmErrColumnDefinitionsLocked
- The table's column definitions are locked.
-
dmErrInvalidColSpec
- The table has no columns defined.
-
dmErrInvalidColumnID
- The specified table doesn't have a column with the supplied column ID.
-
dmErrColumnPropertiesLocked
- The specified column property is locked.
-
dmErrInvalidPropID
- The specified column property ID doesn't reference a column within the table.
Comments
This function removes the property corresponding to propID
. The memory associated with the property value is freed.
See Also
DbSetColumnPropertyValue()
, DbRemoveColumn()
DbRemoveRow Function
Purpose
Remove a row from a database and dispose of its data chunks.
Declared In
SchemaDatabases.h
Prototype
status_t DbRemoveRow ( DmOpenRefdbRef
, uint32_trowID
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row being removed.
Returns
Returns errNone
if the row was successfully removed, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,rowID
isn't a cursor or row ID, orrowID
is a cursor ID but doesn't represent a valid row within the cursor. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrRecordBusy
- The specified row is in use and cannot be removed.
-
memErrNotEnoughSpace
- A memory error occurred.
See Also
DbArchiveRow()
, DbCursorRemoveAllRows()
, DbDeleteRow()
, DbInsertRow()
, DbRemoveSecretRows()
DbRemoveSecretRows Function
Purpose
Remove all secret rows from the database.
Declared In
SchemaDatabases.h
Prototype
status_t DbRemoveSecretRows (
DmOpenRef dbRef
)
Parameters
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrRecordBusy
- At least one of the database's secret rows is in use and cannot be removed.
-
memErrNotEnoughSpace
- A memory error occurred.
See Also
DbRemoveSortIndex Function
Purpose
Remove a sort index from a database.
Declared In
SchemaDatabases.h
Prototype
status_t DbRemoveSortIndex ( DmOpenRefdbRef
, const char*orderBy
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ orderBy
- The sort index to be removed. See "The SELECT Statement" for the format of this parameter.
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrAccessDenied
- You do not have authorization to modify the database.
-
dmErrSQLParseError
- The specified table name or the sort information specified in the sort index is invalid.
-
dmErrInvalidSortDefn
- The specified sort index isn't defined for this database.
-
dmErrMemError
- A memory error occurred.
Comments
The database must exist and the application or user—or both—must have write authorization to the database. The specified sort index must also exist.
See Also
DbAddSortIndex()
, DbHasSortIndex()
DbRemoveTable Function
Purpose
Remove a table definition from a schema database.
Declared In
SchemaDatabases.h
Prototype
status_t DbRemoveTable ( DmOpenRefdbRef
, const char*table
)
Parameters
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database, ortable
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrInvalidTableName
-
table
is not the name of a table in the specified database. -
dmErrReadOnly
- You've attempted to write to or modify a database that is open in read-only mode.
-
dmErrAccessDenied
- You do not have authorization to modify the database, or one or more sort indices are defined for the table.
-
dmErrTableNotEmpty
- The table contains one or more non-deleted rows.
Comments
You cannot remove a table if it contains one or more non-deleted rows or if any sort indices are defined for the table. You must first delete or remove any such rows and sort indices before you can remove the table.
See Also
DbSetCategory Function
Purpose
Set category membership for a single database row.
Declared In
SchemaDatabases.h
Prototype
status_t DbSetCategory ( DmOpenRefdbRef
, uint32_trowID
, uint32_tnumToSet
, const CategoryIDcategoryIDs[]
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row for which category membership is being set.
-
→ numToSet
- Number of category IDs in the
categoryIDs
array. -
→ categoryIDs
- Array of category IDs identifying the categories that the row is to be a member of. Upon successful completion, the row is a member only of those categories identified in this array.
Returns
Returns errNone
if the operation completed successfully, or one of the following if an error occurred:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database, the specified row or cursor ID is not valid, ornumToASet
is nonzero andcategoryIDs
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrIndexOutOfRange
- The specified row or cursor ID doesn't reference a row within the table.
-
dmErrRecordDeleted
- The specified row is marked as deleted.
-
dmErrRecordBusy
- The specified row is in use and cannot be updated.
-
dmErrMemError
- A memory error occurred.
-
dmErrInvalidCategory
- The allowed number of categories has been exceeded, or a category ID doesn't correspond to a defined category.
Comments
Any previous category membership for the row is overwritten by the specified category membership. To remove all category membership from a row (making it "Unfiled"), set numToSet
to 0 and categoryIDs
to NULL
.
The database must be opened with write access. The supplied category IDs must be valid.
If a given category ID occurs more than once in the category ID array, the row is made a member of the category and the duplicate category IDs are ignored.
See Also
DbAddCategory()
, DbGetCategory()
, DbRemoveCategory()
DbSetColumnPropertyValue Function
Purpose
Set a single property value for a database column property.
Declared In
SchemaDatabases.h
Prototype
status_t DbSetColumnPropertyValue ( DmOpenRefdbRef
, const char*table
, uint32_tcolumnID
, DbSchemaColumnPropertypropID
, uint32_tnumBytes
, const void*propValueP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ table
- Table name.
-
→ columnID
- ID of the column for which the property value is being set.
-
→ propID
- ID of the property being set.
-
→ numBytes
- Size, in bytes, of the property value.
-
→ propValueP
- The property value.
Returns
Returns errNone
if the property value was successfully set, or one of the following otherwise:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,table
isNULL
, ornumBytes
is nonzero andpropValueP
isNULL
. -
dmErrBuiltInProperty
- The specified property is a built-in property.
-
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrAccessDenied
- You are not authorized to write to this table.
-
dmErrInvalidTableName
-
table
isn't defined within this database. -
dmErrInvalidColumnID
- The table doesn't have a column with the specified column ID.
-
dmErrColumnPropertiesLocked
- The specified column property is locked.
-
dmErrMemError
- A memory error occurred.
-
memErrNotEnoughSpace
- A memory error occurred.
Comments
This function frees the existing column property value and copies the supplied property value to the storage heap. Because it makes a copy of the property value, after calling this function your application can free any local copy of the property value.
See Also
DbGetColumnPropertyValue()
, DbSetColumnPropertyValues()
DbSetColumnPropertyValues Function
Purpose
Set one or more database column property values.
Declared In
SchemaDatabases.h
Prototype
status_t DbSetColumnPropertyValues ( DmOpenRefdbRef
, const char*table
, uint32_tnumProps
, const DbColumnPropertyValueTypepropValues[]
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ table
- Table name.
-
→ numProps
- Number of elements in the
propValues
array. -
→ propValues
- Array of structures, each of which identifies a column, a property, and a property value. See
DbColumnPropertyValueType
for a description of the structure.
Returns
Returns errNone
if the property value was successfully set, or one of the following otherwise:
-
dmErrInvalidParam
-
dbRef
doesn't reference an open database,table
isNULL
,numProps
is nonzero, orpropValues
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrAccessDenied
- You are not authorized to write to this table.
-
dmErrInvalidTableName
-
table
isn't defined within this database. -
dmErrInvalidColumnID
- One of the specified column IDs doesn't correspond to a table column.
-
dmErrColumnPropertiesLocked
- One of the column properties is locked.
-
dmErrMemError
- A memory error occurred.
-
memErrNotEnoughSpace
- A memory error occurred.
Comments
This function creates a column property if it does not exist and frees an existing column property value if the column property already exists. It copies the supplied property values to the storage heap. Because it makes a copy of each supplied property value, after calling this function your application can free any local copies of the property values.
See Also
DbGetColumnPropertyValues()
, DbSetColumnPropertyValue()
DbSetRowAttr Function
Purpose
Declared In
SchemaDatabases.h
Prototype
status_t DbSetRowAttr ( DmOpenRefdbRef
, uint32_trowID
, uint16_t*attrP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- Row ID or cursor ID identifying the row for which attributes are being set.
-
→ attrP
- Pointer to the new attributes for the row.
Returns
Returns errNone
if the attributes were set successfully, or one of the following if an error occurred:
-
dmErrNotRecordDB
- You've attempted to perform a row function on a resource database.
-
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.
Comments
Row attributes are documented under "Schema Database Row Attributes." This function can be used only to set those attributes that are not system-only attributes (system-only attributes are those that make up dbSysOnlyRecAttrs
).
See Also
DbWriteColumnValue Function
Purpose
Write a single column value for a row.
Declared In
SchemaDatabases.h
Prototype
status_t DbWriteColumnValue ( DmOpenRefdbRef
, uint32_trowID
, uint32_tcolumnID
, uint32_toffset
, int32_tbytesToReplace
, const void*srcP
, uint32_tsrcBytes
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- The row ID or cursor ID identifying the row for which the column value is being written.
-
→ columnID
- ID of the column being written.
-
→ offset
- For variable-length columns, an offset, in bytes, to the location within the column where the value is to be written.
-
→ bytesToReplace
- For variable-length columns, the number of data bytes to be replaced by the write operation, or -1 to replace all of the column's data for the row.
-
→ srcP
- Data to write into the column.
-
→ srcBytes
- Number of bytes to write.
Returns
Returns errNone
if the data was successfully written, or one of the following otherwise:
-
dmErrInvalidParam
-
dbP
doesn't reference an open database, orrowID
isn't a row or cursor ID. -
dmErrCursorBOF
- The specified cursor ID is BOF.
-
dmErrCursorEOF
- The specified cursor ID is EOF.
-
dmErrUniqueIDNotFound
- The specified row ID doesn't correspond to a valid row within the table.
-
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrRecordDeleted
- The row is marked as deleted.
-
dmErrRecordBusy
- The row is busy and cannot be written to.
-
dmErrInvalidTableName
- The database doesn't contain a table with the specified name.
-
dmErrMemError
- A memory error occurred.
-
dmErrWriteOutOfBounds
- The write exceeded the bounds of the column.
-
memErrNotEnoughSpace
- A memory error occurred.
Comments
To remove existing column data, set srcP
to NULL
. If srcP
is NULL
, srcBytes
is ignored.
Offset-based writes are not supported for fixed-length column data types; the offset
and bytesToReplace
parameters are ignored for them. The list of column data types supporting offset based writes are:
DbWriteColumnValue()
does not merely replace one set of bytes with an equal-sized set; depending on the bytesToReplace
and srcBytes
parameters, the resulting value can be shorter or longer than the original value. The following sections detail the operations you can perform with this function.
Expand
If bytesToReplace
is less than srcBytes
, the resulting column value is longer than the original value. For instance:
Updated column data: "ab12345678e"
Shrink
If bytesToReplace
is greater than srcBytes
, the resulting column value is shorter than the original value. For instance:
Truncate
Taking the "shrink" scenario to its extreme, to simply remove a portion of the original column data, set srcBytes
to 0, as shown here:
Insert
If bytesToReplace
is 0, the data is inserted into the original column data. For instance:
Updated column data: "ab12345cde"
Append
A variant on the "insert" scenario, if the offset
parameter is set to the length of the current column data and bytesToReplace
is 0, the data being written is appended to the current column data. For example:
Updated column data: "abcde12345"
Partial Replacement
To replace a portion of the original column data without changing the size of the column data, bytesToReplace
should equal srcBytes
, as shown here:
Complete Replacement
To completely replace a column's data, set offset
to 0 and bytesToReplace
to -1. For example:
See Also
DbCopyColumnValue()
, DbGetColumnValue()
, DbWriteColumnValues()
DbWriteColumnValues Function
Purpose
Write one or more column values for a row.
Declared In
SchemaDatabases.h
Prototype
status_t DbWriteColumnValues ( DmOpenRefdbRef
, uint32_trowID
, uint32_tnumColumnValues
, DbSchemaColumnValueType*columnValuesP
)
Parameters
-
→ dbRef
-
DmOpenRef
to an open database. -
→ rowID
- The row ID or cursor ID identifying the row for which the column values are being written.
-
→ numColumnValues
- Number of elements in the
columnValuesP
array. -
→ columnValuesP
- Array of structures, each containing a column ID and a value.
Returns
Returns errNone
if the data was successfully written, or one of the following otherwise:
-
dmErrInvalidParam
-
dbP
doesn't reference an open database, orrowID
isn't a row or cursor ID. -
dmErrCursorBOF
- The specified cursor ID is BOF.
-
dmErrCursorEOF
- The specified cursor ID is EOF.
-
dmErrUniqueIDNotFound
- The specified row ID doesn't correspond to a valid row within the table.
-
dmErrNotSchemaDatabase
- The specified database is not a schema database.
-
dmErrReadOnly
- The database is not open for write access.
-
dmErrRecordDeleted
- The row is marked as deleted.
-
dmErrRecordBusy
- The row is busy and cannot be written to.
-
dmErrInvalidTableName
- The database doesn't contain a table with the specified name.
-
dmErrMemError
- A memory error occurred.
-
dmErrWriteOutOfBounds
- The write exceeded the bounds of a column.
-
memErrNotEnoughSpace
- A memory error occurred.
Comments
A NULL
value for the data
field of the DbSchemaColumnValueType
structure is allowed; this removes existing column data for the specified column and row.
See Also
DbCopyColumnValues()
, DbGetColumnValues()
, DbWriteColumnValue()