Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

7    Schema Databases

Memory, Databases, and Files

Exploring Palm OS®

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 ^TOP^

DbColumnPropertySpecType Struct ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

Purpose

Generic type for any kind of column data.

Declared In

SchemaDatabases.h

Prototype

typedef void DbSchemaColumnData;

Fields

None.

Comments

The DbSchemaColumnValueType structure uses this data type for the column's data.

DbSchemaColumnDefnType Struct ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 to dataSize.
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 ^TOP^

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 ^TOP^

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 ^TOP^

Schema Database Row Attributes ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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() or DbCursorOpenWithCategory() if the open failed.
#define dbInvalidRowID dbInvalidCursorID
Row ID returned from DbCursorGetCurrentRowID(), DbCursorGetPositionForRowID(), or DbInsertRow() 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 ^TOP^

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() calls DbCursorMove() with a fetch type of dbFetchAbsolute.
dbFetchNext
Moves the cursor forward one row. The macro DbCursorMoveNext() calls DbCursorMove() with a fetch type of dbFetchNext. Note that the offset parameter to DbCursorMove() is ignored when the fetch type is dbFetchNext.
dbFetchPrior
Moves the cursor backward one row. The macro DbCursorMovePrev() calls DbCursorMove() with a fetch type of dbFetchPrior. Note that the offset parameter to DbCursorMove() is ignored when the fetch type is dbFetchPrior.
dbFetchFirst
Moves the cursor onto the first row. The macro DbCursorMoveFirst() calls DbCursorMove() with a fetch type of dbFetchFirst.
dbFetchLast
Moves the cursor onto the last row. The macro DbCursorMoveLast() calls DbCursorMove() with a fetch type of dbFetchLast.
dbFetchRowID
Moves the cursor onto the row with the specified row ID. The macro DbCursorMoveToRowID() calls DbCursorMove() with a fetch type of dbFetchRowID.

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 ^TOP^

DbAddCategory Function ^TOP^

Purpose

Make the specified row a member of one or more additional categories.

Declared In

DataMgr.h

Prototype

status_t DbAddCategory (
   DmOpenRef dbRef,
   uint32_t rowID,
   uint32_t numToAdd,
   const CategoryID categoryIDs[]
)

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, or numToAdd is nonzero and categoryIDs is NULL.
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 ^TOP^

Purpose

Adds a column to a database table.

Declared In

SchemaDatabases.h

Prototype

status_t DbAddColumn (
   DmOpenRef dbRef,
   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 is NULL, or addColumnP is NULL.
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 ^TOP^

Purpose

Adds a new sort index to a database.

Declared In

SchemaDatabases.h

Prototype

status_t DbAddSortIndex (
   DmOpenRef dbRef,
   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:

  • dbDateTimeSecs
  • dbBoolean
  • dbVarChar

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 ^TOP^

Purpose

Adds a table to an existing database.

Declared In

SchemaDatabases.h

Prototype

status_t DbAddTable (
   DmOpenRef dbRef,
   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, or schemaP is NULL.
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

DbHasTable(), DbRemoveTable()

DbArchiveRow Function ^TOP^

Purpose

Mark a row as archived. This function leaves the row's data intact.

Declared In

SchemaDatabases.h

Prototype

status_t DbArchiveRow (
   DmOpenRef dbRef,
   uint32_t rowID
)

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 ^TOP^

Purpose

Close a schema database.

Declared In

SchemaDatabases.h

Prototype

status_t DbCloseDatabase (
   DmOpenRef dbRef
)

Parameters

dbRef
DmOpenRef to an open database.

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 ^TOP^

Purpose

Obtains the value of a single schema database column for a specified row.

Declared In

SchemaDatabases.h

Prototype

status_t DbCopyColumnValue (
   DmOpenRef dbRef,
   uint32_t rowID,
   uint32_t columnID,
   uint32_t offset,
   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, or valueSizeP is NULL.
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:

  • VarChar
  • Blob
  • Vector

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 ^TOP^

Purpose

Obtains the value of one or more schema database columns for a specified row.

Declared In

SchemaDatabases.h

Prototype

status_t DbCopyColumnValues (
   DmOpenRef dbRef,
   uint32_t rowID,
   uint32_t numColumns,
   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 to NULL, which results in the actual size of the column data being returned in the actualDataSize 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, or columnValuesP is NULL.
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 ^TOP^

Purpose

Creates a new schema database.

Declared In

SchemaDatabases.h

Prototype

status_t DbCreateDatabase (
   const char *name,
   uint32_t creator,
   uint32_t type,
   uint32_t numTables,
   const DbTableDefinitionType schemaListP[],
   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 by dmDBNameLength. The name should be constructed only of 7-bit ASCII characters (0x20 through 0x7E).
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 is NULL, 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 ^TOP^

Purpose

Create a new secure schema database.

Declared In

SchemaDatabases.h

Prototype

status_t DbCreateSecureDatabase (
   const char *name,
   uint32_t creator,
   uint32_t type,
   uint32_t numSchemas,
   const DbTableDefinitionType schemaList[],
   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 by dmDBNameLength. The name should be constructed only of 7-bit ASCII characters (0x20 through 0x7E).
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 is NULL, 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 ^TOP^

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 is NULL or pRuleSet is NULL.
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 ^TOP^

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() or DbCursorOpenWithCategory().

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 ^TOP^

Purpose

Bind a variable to a cursor column.

Declared In

SchemaDatabases.h

Prototype

status_t DbCursorBindData (
   uint32_t cursorID,
   uint32_t columnID,
   void *dataBufferP,
   uint32_t dataBufferLength,
   uint32_t *dataSizeP,
   status_t *errCodeP
)

Parameters

cursorID
ID of a valid cursor, as returned from DbCursorOpen() or DbCursorOpenWithCategory().
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 ^TOP^

Purpose

Bind a variable to a cursor column, offset by a specified amount.

Declared In

SchemaDatabases.h

Prototype

status_t DbCursorBindDataWithOffset (
   uint32_t cursorID,
   uint32_t columnID,
   void *dataBufferP,
   uint32_t dataBufferLength,
   uint32_t *dataSizeP,
   uint32_t fieldDataOffset,
   status_t *errCodeP
)

Parameters

cursorID
ID of a valid cursor, as returned from DbCursorOpen() or DbCursorOpenWithCategory().
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 ^TOP^

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() or DbCursorOpenWithCategory().

Returns

Returns errNone if the resources were successfully freed, or one of the following otherwise:

dmErrInvalidParam
The supplied cursor ID is invalid.
dmErrMemError
A memory error occurred.

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 ^TOP^

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() or DbCursorOpenWithCategory().

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 ^TOP^

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() or DbCursorOpenWithCategory().

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 ^TOP^

Purpose

Get the index of the cursor's current row.

Declared In

SchemaDatabases.h

Prototype

status_t DbCursorGetCurrentPosition (
   uint32_t cursorID,
   uint32_t *position
)

Parameters

cursorID
ID of a valid cursor, as returned from DbCursorOpen() or DbCursorOpenWithCategory().
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 ^TOP^

Purpose

Get the row ID of the cursor's current row.

Declared In

SchemaDatabases.h

Prototype

status_t DbCursorGetCurrentRowID (
   uint32_t cursorID,
   uint32_t *rowIDP
)

Parameters

cursorID
ID of a valid cursor, as returned from DbCursorOpen() or DbCursorOpenWithCategory().
rowIDP
Pointer to a variable that receives the row ID. If the cursor isn't currently positioned at a valid row, *rowIDP is set to dbInvalidRowID.

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 ^TOP^

Purpose

Get the index of a specified row within the cursor.

Declared In

SchemaDatabases.h

Prototype

status_t DbCursorGetPositionForRowID (
   uint32_t cursorID,
   uint32_t rowID,
   uint32_t *positionP
)

Parameters

cursorID
ID of a valid cursor, as returned from DbCursorOpen() or DbCursorOpenWithCategory().
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 is NULL.
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 ^TOP^

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() or DbCursorOpenWithCategory().

Returns

Returns the number of rows in the cursor.

DbCursorGetRowIDForPosition Function ^TOP^

Purpose

Get a row's ID given its index.

Declared In

SchemaDatabases.h

Prototype

status_t DbCursorGetRowIDForPosition (
   uint32_t cursorID,
   uint32_t position,
   uint32_t *rowIDP
)

Parameters

cursorID
ID of a valid cursor, as returned from DbCursorOpen() or DbCursorOpenWithCategory().
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 to dbInvalidRowID.

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 is NULL.
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 ^TOP^

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() or DbCursorOpenWithCategory().

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 ^TOP^

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() or DbCursorOpenWithCategory().

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

DbArchiveRow(), DbDeleteRow()

DbCursorIsEOF Function ^TOP^

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() or DbCursorOpenWithCategory().

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 ^TOP^

Purpose

Move a cursor's current row position.

Declared In

SchemaDatabases.h

Prototype

status_t DbCursorMove (
   uint32_t cursorID,
   int32_t offset,
   DbFetchType fetchType
)

Parameters

cursorID
ID of a valid cursor, as returned from DbCursorOpen() or DbCursorOpenWithCategory().
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 ^TOP^

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() or DbCursorOpenWithCategory().

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
The cursor contains no rows.

Comments

Upon successful completion of the move, any bound variables are updated with corresponding field values for the new current row.

See Also

DbCursorMove()

DbCursorMoveLast Macro ^TOP^

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() or DbCursorOpenWithCategory().

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
The cursor contains no rows.

Comments

Upon successful completion of the move, any bound variables are updated with corresponding field values for the new current row.

See Also

DbCursorMove()

DbCursorMoveNext Macro ^TOP^

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() or DbCursorOpenWithCategory().

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

DbCursorMove()

DbCursorMovePrev Macro ^TOP^

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() or DbCursorOpenWithCategory().

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

DbCursorMove()

DbCursorRelocateRow Function ^TOP^

Purpose

Relocate a row within a cursor that was opened using the default sort index.

Declared In

SchemaDatabases.h

Prototype

status_t DbCursorRelocateRow (
   uint32_t cursorID,
   uint32_t from,
   uint32_t to
)

Parameters

cursorID
ID of a valid cursor, as returned from DbCursorOpen() or DbCursorOpenWithCategory().
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 or to 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

DbCursorMove()

DbCursorMoveToRowID Macro ^TOP^

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() or DbCursorOpenWithCategory().
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:

dmErrInvalidParam
The specified cursor ID is invalid.

Comments

Upon successful completion, any bound variables are updated with corresponding field values for the new current row.

See Also

DbCursorMove(), DbCursorSetAbsolutePosition()

DbCursorOpen Function ^TOP^

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 (
   DmOpenRef dbRef,
   const char *sql,
   uint32_t flags,
   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 to dbInvalidCursorID.

Returns

Returns errNone if the cursor was successfully opened, or one of the following otherwise:

dmErrInvalidParam
dbRef doesn't reference an open database, sql is NULL, or cursorID is NULL.
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 ^TOP^

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 (
   DmOpenRef dbRef,
   const char *sql,
   uint32_t flags,
   uint32_t numCategories,
   const CategoryID categoryIDs[],
   DbMatchModeType matchMode,
   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 to dbInvalidCursorID.

Returns

Returns errNone if the cursor was successfully opened, or one of the following otherwise:

dmErrInvalidParam
dbRef doesn't reference an open database, sql is NULL, or cursorID is NULL.
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 ^TOP^

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() or DbCursorOpenWithCategory().

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 ^TOP^

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() or DbCursorOpenWithCategory().

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 ^TOP^

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() or DbCursorOpenWithCategory().
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 ^TOP^

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() or DbCursorOpenWithCategory().

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 ^TOP^

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 (
   DmOpenRef dbRef,
   uint32_t rowID
)

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, or rowID 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 ^TOP^

Purpose

Turn automatic sorting on or off for a given database.

Declared In

SchemaDatabases.h

Prototype

status_t DbEnableSorting (
   DmOpenRef dbRef,
   Boolean enable
)

Parameters

dbRef
DmOpenRef to an open database.
enable
If true, sorting is enabled. If false, 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 ^TOP^

Purpose

Retrieve all of a table's column definitions.

Declared In

SchemaDatabases.h

Prototype

status_t DbGetAllColumnDefinitions (
   DmOpenRef dbRef,
   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 is NULL, columnDefnsPP is NULL, or table is NULL.
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 ^TOP^

Purpose

Retrieve all of a table's column property values.

Declared In

SchemaDatabases.h

Prototype

status_t DbGetAllColumnPropertyValues (
   DmOpenRef dbRef,
   const char *table,
   Boolean customPropsOnly,
   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 is NULL, propValuesPP is NULL, or table is NULL.
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 ^TOP^

Purpose

Retrieve all column values for a specified row.

Declared In

SchemaDatabases.h

Prototype

status_t DbGetAllColumnValues (
   DmOpenRef dbRef,
   uint32_t rowID,
   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, or columnValuesPP is NULL.
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 ^TOP^

Purpose

Retrieve the category membership for the specified row.

Declared In

SchemaDatabases.h

Prototype

status_t DbGetCategory (
   DmOpenRef dbRef,
   uint32_t rowID,
   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 ^TOP^

Purpose

Retrieve one or more table column definitions.

Declared In

SchemaDatabases.h

Prototype

status_t DbGetColumnDefinitions (
   DmOpenRef dbRef,
   const char *table,
   uint32_t numColumns,
   const uint32_t columnIDs[],
   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 is NULL, columnDefnsPP is NULL, or table is NULL.
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 ^TOP^

Purpose

Retrieve the column ID for a column index.

Declared In

SchemaDatabases.h

Prototype

status_t DbGetColumnID (
   DmOpenRef dbRef,
   const char *table,
   uint32_t columnIndex,
   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, or table is NULL.
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

DbNumColumns()

DbGetColumnPropertyValue Function ^TOP^

Purpose

Retrieve the value of a specified table column property.

Declared In

SchemaDatabases.h

Prototype

status_t DbGetColumnPropertyValue (
   DmOpenRef dbRef,
   const char *table,
   uint32_t columnID,
   DbSchemaColumnProperty propID,
   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 is NULL, propValuePP is NULL, or table is NULL.
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 ^TOP^

Purpose

Retrieve the value of one or more table column properties.

Declared In

SchemaDatabases.h

Prototype

status_t DbGetColumnPropertyValues (
   DmOpenRef dbRef,
   const char *table,
   uint32_t numProps,
   const DbColumnPropertySpecType propSpecs[],
   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 is NULL, propValuePP is NULL, or table is NULL.
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 ^TOP^

Purpose

Retrieve a single column value for a row.

Declared In

SchemaDatabases.h

Prototype

status_t DbGetColumnValue (
   DmOpenRef dbRef,
   uint32_t rowID,
   uint32_t columnID,
   uint32_t offset,
   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, or valuePP is NULL.
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:

  • VarChar
  • Blob
  • Vector

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 ^TOP^

Purpose

Retrieve one or more column values for a row.

Declared In

SchemaDatabases.h

Prototype

status_t DbGetColumnValues (
   DmOpenRef dbRef,
   uint32_t rowID,
   uint32_t numColumns,
   const uint32_t columnIDs,
   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, or columnValuesPP is NULL.
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 ^TOP^

Purpose

Retrieve a row's attributes.

Declared In

SchemaDatabases.h

Prototype

status_t DbGetRowAttr (
   DmOpenRef dbRef,
   uint32_t rowID,
   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 ^TOP^

Purpose

Get the current access rules for a secure database.

Declared In

SchemaDatabases.h

Prototype

status_t DbGetRuleSet (
   DatabaseID dbID,
   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 or ruleset is NULL.
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 ^TOP^

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 (
   DmOpenRef dbRef,
   uint32_t sortIndex,
   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 ^TOP^

Purpose

Obtain the name of the table that contains a specified row.

Declared In

SchemaDatabases.h

Prototype

status_t DbGetTableForRow (
   DmOpenRef dbRef,
   uint32_t rowID,
   char *buf,
   size_t bufSize
)

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 is NULL, or bufSize 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

DbCursorGetCurrentRowID()

DbGetTableName Function ^TOP^

Purpose

Obtain a table's name, given the index of the table within a database.

Declared In

SchemaDatabases.h

Prototype

status_t DbGetTableName (
   DmOpenRef dbRef,
   uint32_t index,
   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, or table is NULL.
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

DbNumTables()

DbGetTableSchema Function ^TOP^

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 (
   DmOpenRef dbRef,
   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 calling DbGetTableSchema(). Upon return, your pointer variable contains the address of a DbTableDefinitionType 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, or schemaPP is NULL.
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 ^TOP^

Purpose

Determine whether a particular sort index has been defined for a database.

Declared In

SchemaDatabases.h

Prototype

Boolean DbHasSortIndex (
   DmOpenRef dbRef,
   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 ^TOP^

Purpose

Determine whether a specific table exists in a particular database.

Declared In

SchemaDatabases.h

Prototype

Boolean DbHasTable (
   DmOpenRef dbRef,
   const char *table
)

Parameters

dbRef
DmOpenRef to an open database.
table
Table name.

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 ^TOP^

Purpose

Add a row to a specified database table.

Declared In

SchemaDatabases.h

Prototype

status_t DbInsertRow (
   DmOpenRef dbRef,
   const char *table,
   uint32_t numColumnValues,
   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 ^TOP^

Purpose

Determine whether a specified ID is a cursor ID.

Declared In

SchemaDatabases.h

Prototype

Boolean DbIsCursorID (
   uint32_t uniqueID
)

Parameters

uniqueID
The ID to be checked.

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

DbIsRowID Function ^TOP^

Purpose

Determine whether a specified ID is a row ID.

Declared In

SchemaDatabases.h

Prototype

Boolean DbIsRowID (
   uint32_t uniqueID
)

Parameters

uniqueID
The ID to be checked.

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

DbIsCursorID()

DbIsRowInCategory Function ^TOP^

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 (
   DmOpenRef dbRef,
   uint32_t rowID,
   uint32_t numCategories,
   const CategoryID categoryIDs[],
   DbMatchModeType matchMode,
   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 to true if the row membership includes any of the categories specified in the categoryIDs array.
DbMatchAll
(AND) Set pIsInCategory to true if the row membership includes all of the categories specified in the categoryIDs array, including rows with additional category membership.
DbMatchExact
Set pIsInCategory to true if the row membership exactly matches the categories specified in the categoryIDs 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 and categoryIDs is not NULL, numCategories is nonzero and categoryIDs is NULL, or matchMode 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 or DbMatchExact.

See Also

DbGetCategory()

DbIsSortingEnabled Function ^TOP^

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

DbEnableSorting()

DbMoveCategory Function ^TOP^

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 (
   DmOpenRef dbRef,
   CategoryID toCategory,
   uint32_t numFromCategories,
   const CategoryID fromCategoryIDs[],
   DbMatchModeType matchMode
)

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 and fromCategoryIDs is not NULL, numCategories is nonzero and fromCategoryIDs is NULL, or matchMode 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 the fromCategoryIDs parameter and 0 for numFromCategories. In this case, the matchMode 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 is DbMatchAny.
  • any of the category IDs in fromCategoryIDs are not valid and the match mode criteria value is either DbMatchAll or DbMatchExact.

See Also

DbRemoveCategoryAllRows()

DbNumCategory Function ^TOP^

Purpose

Determine how many categories a specified row is a member of.

Declared In

SchemaDatabases.h

Prototype

status_t DbNumCategory (
   DmOpenRef dbRef,
   uint32_t rowID,
   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, or pNumCategories is NULL.
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

DbGetCategory()

DbNumColumns Function ^TOP^

Purpose

Get the number of columns in a specified table.

Declared In

SchemaDatabases.h

Prototype

status_t DbNumColumns (
   DmOpenRef dbRef,
   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 or table is NULL.
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 ^TOP^

Purpose

Get the number of sort indices defined for a given database.

Declared In

SchemaDatabases.h

Prototype

status_t DbNumSortIndexes (
   DmOpenRef dbRef,
   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 ^TOP^

Purpose

Get the number of tables defined for a given database.

Declared In

SchemaDatabases.h

Prototype

status_t DbNumTables (
   DmOpenRef dbRef,
   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

DbGetTableName()

DbOpenDatabase Function ^TOP^

Purpose

Open a schema database and return a reference to it.

Declared In

SchemaDatabases.h

Prototype

DmOpenRef DbOpenDatabase (
   DatabaseID dbID,
   DmOpenModeType mode,
   DbShareModeType share
)

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 ^TOP^

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_t creator,
   const char *name,
   DmOpenModeType mode,
   DbShareModeType share
)

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 ^TOP^

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 (
   DmOpenRef dbRef,
   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 is NULL or ptr is NULL.
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:

DbRemoveCategory Function ^TOP^

Purpose

Remove membership in the specified categories from a single row.

Declared In

SchemaDatabases.h

Prototype

status_t DbRemoveCategory (
   DmOpenRef dbRef,
   uint32_t rowID,
   uint32_t numToRemove,
   const CategoryID categoryIDs[]
)

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, or numToRemove is nonzero and categoryIDs is NULL.
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 ^TOP^

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 (
   DmOpenRef dbRef,
   uint32_t numCategories,
   const CategoryID categoryIDs[],
   DbMatchModeType matchMode
)

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 and categoryIDs is not NULL, numCategories is nonzero and categoryIDs is NULL, or matchMode 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 or DbMatchExact.

See Also

DbAddCategory(), DbRemoveCategory(), DbSetCategory()

DbRemoveColumn Function ^TOP^

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 (
   DmOpenRef dbRef,
   const char *table,
   uint32_t columnID
)

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, or table is NULL.
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 ^TOP^

Purpose

Remove a single column property from a database table.

Declared In

SchemaDatabases.h

Prototype

status_t DbRemoveColumnProperty (
   DmOpenRef dbRef,
   const char *table,
   uint32_t columnID,
   DbSchemaColumnProperty propID
)

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, or table is NULL.
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 ^TOP^

Purpose

Remove a row from a database and dispose of its data chunks.

Declared In

SchemaDatabases.h

Prototype

status_t DbRemoveRow (
   DmOpenRef dbRef,
   uint32_t rowID
)

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, or rowID 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 ^TOP^

Purpose

Remove all secret rows from the database.

Declared In

SchemaDatabases.h

Prototype

status_t DbRemoveSecretRows (
   DmOpenRef dbRef
)

Parameters

dbRef
DmOpenRef to an open database.

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

DbRemoveRow()

DbRemoveSortIndex Function ^TOP^

Purpose

Remove a sort index from a database.

Declared In

SchemaDatabases.h

Prototype

status_t DbRemoveSortIndex (
   DmOpenRef dbRef,
   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 ^TOP^

Purpose

Remove a table definition from a schema database.

Declared In

SchemaDatabases.h

Prototype

status_t DbRemoveTable (
   DmOpenRef dbRef,
   const char *table
)

Parameters

dbRef
DmOpenRef to an open database.
table
Table name.

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, or table is NULL.
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

DbAddTable()

DbSetCategory Function ^TOP^

Purpose

Set category membership for a single database row.

Declared In

SchemaDatabases.h

Prototype

status_t DbSetCategory (
   DmOpenRef dbRef,
   uint32_t rowID,
   uint32_t numToSet,
   const CategoryID categoryIDs[]
)

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, or numToASet is nonzero and categoryIDs is NULL.
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 ^TOP^

Purpose

Set a single property value for a database column property.

Declared In

SchemaDatabases.h

Prototype

status_t DbSetColumnPropertyValue (
   DmOpenRef dbRef,
   const char *table,
   uint32_t columnID,
   DbSchemaColumnProperty propID,
   uint32_t numBytes,
   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 is NULL, or numBytes is nonzero and propValueP is NULL.
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 ^TOP^

Purpose

Set one or more database column property values.

Declared In

SchemaDatabases.h

Prototype

status_t DbSetColumnPropertyValues (
   DmOpenRef dbRef,
   const char *table,
   uint32_t numProps,
   const DbColumnPropertyValueType propValues[]
)

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 is NULL, numProps is nonzero, or propValues is NULL.
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 ^TOP^

Purpose

Set the attributes of a row.

Declared In

SchemaDatabases.h

Prototype

status_t DbSetRowAttr (
   DmOpenRef dbRef,
   uint32_t rowID,
   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

DbGetRowAttr()

DbWriteColumnValue Function ^TOP^

Purpose

Write a single column value for a row.

Declared In

SchemaDatabases.h

Prototype

status_t DbWriteColumnValue (
   DmOpenRef dbRef,
   uint32_t rowID,
   uint32_t columnID,
   uint32_t offset,
   int32_t bytesToReplace,
   const void *srcP,
   uint32_t srcBytes
)

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, or rowID 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:

  • VarChar
  • Blob
  • Vector

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:

Original column data: "abcde"

offset: 2

bytesToReplace: 2

srcBytes: 8

*srcP: "12345678"

Updated column data: "ab12345678e"

Shrink

If bytesToReplace is greater than srcBytes, the resulting column value is shorter than the original value. For instance:

Original column data: "abcde"

offset: 2

bytesToReplace: 3

srcBytes: 1

*srcP: "1"

Updated column data: "ab1"

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:

Original column data: "abcde"

offset: 2

bytesToReplace: 3

srcBytes: 0

*srcP: NULL

Updated column data: "ab"

Insert

If bytesToReplace is 0, the data is inserted into the original column data. For instance:

Original column data: "abcde"

offset: 2

bytesToReplace: 0

srcBytes: 5

*srcP: "12345"

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:

Original column data: "abcde"

offset: 5

bytesToReplace: 0

srcBytes: 5

*srcP: "12345"

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:

Original column data: "abcde"

offset: 2

bytesToReplace: 2

srcBytes: 2

*srcP: "12"

Updated column data: "ab12e"

Complete Replacement

To completely replace a column's data, set offset to 0 and bytesToReplace to -1. For example:

Original column data: "abcde"

offset: 0

bytesToReplace: -1

srcBytes: 5

*srcP: "12345"

Updated column data: "12345"

See Also

DbCopyColumnValue(), DbGetColumnValue(), DbWriteColumnValues()

DbWriteColumnValues Function ^TOP^

Purpose

Write one or more column values for a row.

Declared In

SchemaDatabases.h

Prototype

status_t DbWriteColumnValues (
   DmOpenRef dbRef,
   uint32_t rowID,
   uint32_t numColumnValues,
   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, or rowID 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()