Header for the RDM Database APIs. More...

#include "rdmtypes.h"
#include "rdmrowidtypes.h"
#include "rdmtfstypes.h"

Include dependency graph for rdmdbapi.h:

This graph shows which files directly or indirectly include this file:

Functions
RDM_RETCODE	rdm_dbAllocCursor (RDM_DB db, RDM_CURSOR *pCursor)
	Allocate a cursor. More...

RDM_RETCODE	rdm_dbAlterCatalog (RDM_DB db, const char *ddlStmt)
	Process a schema DDL command. More...

RDM_RETCODE	rdm_dbClearCache (RDM_DB db)

RDM_RETCODE	rdm_dbClose (RDM_DB db)
	Close the database associated with a database handle. More...

RDM_RETCODE	rdm_dbDeleteAllRowsFromDatabase (RDM_DB db)
	Remove all rows from a database. More...

RDM_RETCODE	rdm_dbDeleteAllRowsFromTable (RDM_DB db, RDM_TABLE_ID tableId)
	Remove all rows from a table. More...

RDM_RETCODE	rdm_dbGetMemoryUsage (RDM_DB db, uint64_t systemCurr, uint64_t systemMax, uint64_t userCurr, uint64_t userMax)
	Get memory usage information for a database. More...

RDM_RETCODE	rdm_dbEncrypt (RDM_DB db, RDM_ENCRYPT enc, const char *optString)
	Encrypt a database. More...

RDM_RETCODE	rdm_dbEnd (RDM_DB db)
	End a transactional operation. More...

RDM_RETCODE	rdm_dbEndRollback (RDM_DB db)
	End and rollback a transactional operation. More...

RDM_RETCODE	rdm_dbExport (RDM_DB db, const char *optString)
	Database export API. More...

RDM_RETCODE	rdm_dbVacuum (RDM_DB db, const char *optString)
	Database vacuum API. More...

RDM_RETCODE	rdm_dbCreateNewPackFile (RDM_DB db)
	Create a new pack file. More...

RDM_RETCODE	rdm_dbFree (RDM_DB db)
	Free a database handle. More...

RDM_RETCODE	rdm_dbGetEncrypt (RDM_DB db, RDM_ENCRYPT *enc)
	Get the encryption context associated with a database handle. More...

RDM_RETCODE	rdm_dbGetLockStatus (RDM_DB db, RDM_TABLE_ID tableId, RDM_LOCK_STATUS *status)
	Get the RDM_DB handle's current lock status of a table. More...

RDM_RETCODE	rdm_dbGetOption (RDM_DB db, const char keyword, char optValue, size_t bytesIn, size_t *bytesOut)
	Get a single database option into a string. More...

RDM_RETCODE	rdm_dbGetOptions (RDM_DB db, char optString, size_t bytesIn, size_t bytesOut)
	Get RDM database specific options. More...

RDM_RETCODE	rdm_dbGetInfo (RDM_DB db, const char keyword, char infoString, size_t bytesIn, size_t *bytesOut)
	Get RDM database information. More...

RDM_RETCODE	rdm_dbGetRows (RDM_DB db, RDM_TABLE_ID tableId, RDM_CURSOR *pCursor)
	Associate an RDM_CURSOR with rows based on a table id. More...

RDM_RETCODE	rdm_dbGetRowsAtRowId (RDM_DB db, RDM_TABLE_ID tableId, RDM_ROWID_T rowId, RDM_CURSOR *pCursor)
	Associate an RDM_CURSOR with rows based on a tableId and and rowId. More...

RDM_RETCODE	rdm_dbGetRowsByKey (RDM_DB db, RDM_KEY_ID keyId, RDM_CURSOR *pCursor)
	Associate an RDM_CURSOR with a row set based on a key. More...

RDM_RETCODE	rdm_dbGetRowsByKeyAtKey (RDM_DB db, RDM_KEY_ID keyId, const void keyValue, size_t len, RDM_CURSOR pCursor)
	Associate an RDM_CURSOR with a row set that is ordered by key value and is initially positioned at the specified key value. More...

RDM_RETCODE	rdm_dbGetRowsByKeyAtSearchKey (RDM_DB db, RDM_KEY_ID keyId, const RDM_SEARCH_KEY keyValue, RDM_CURSOR pCursor)
	Associate an RDM_CURSOR with a row set that is ordered by key value and is initially positioned at the specified key value. More...

RDM_RETCODE	rdm_dbGetRowsByKeyInKeyRange (RDM_DB db, RDM_KEY_ID keyId, const void startValue, size_t bytesInStartValue, const void endValue, size_t bytesInEndValue, RDM_CURSOR *pCursor)
	Associate an RDM_CURSOR with rows in a specified key range. More...

RDM_RETCODE	rdm_dbGetRowsByKeyInRangeKeyRange (RDM_DB db, RDM_KEY_ID keyId, const RDM_RANGE_KEY startValue, const RDM_RANGE_KEY endValue, RDM_CURSOR *pCursor)
	Associate an RDM_CURSOR with rows in a specified key range. More...

RDM_RETCODE	rdm_dbGetRowsByKeyInRtreeKeyRange (RDM_DB db, RDM_KEY_ID keyId, const RDM_RTREE_KEY keyValue, RDM_CURSOR pCursor)
	Associate an RDM_CURSOR with a row set based on a R-tree. More...

RDM_RETCODE	rdm_dbGetRowsByKeyInSearchKeyRange (RDM_DB db, RDM_KEY_ID keyId, const RDM_SEARCH_KEY startValue, const RDM_SEARCH_KEY endValue, RDM_CURSOR *pCursor)
	Associate an RDM_CURSOR with rows in a specified key range. More...

RDM_RETCODE	rdm_dbGetTFS (RDM_DB db, RDM_TFS *pTFS)
	Get the RDM_TFS handle associated with a db. More...

RDM_RETCODE	rdm_dbGetTFSType (RDM_DB db, TFS_TYPE *pTfsType)
	Get the type of the RDM_TFS handle associated with a database. More...

RDM_RETCODE	rdm_dbGetTransactionStatus (RDM_DB db, RDM_TRANS_STATUS *status)
	Get the transaction status for a database handle. More...

RDM_RETCODE	rdm_dbImport (RDM_DB db, const char *optString)
	Database import API. More...

RDM_RETCODE	rdm_dbInsertRow (RDM_DB db, RDM_TABLE_ID tableId, const void colValues, size_t bytesIn, RDM_CURSOR pCursor)
	Insert a new row into a table at the specified rowId. More...

RDM_RETCODE	rdm_dbOpen (RDM_DB db, const char *dbNameSpec, RDM_OPEN_MODE mode)
	Open an existing RDM database using the specified database handle. More...

RDM_RETCODE	rdm_dbPersistInMemory (RDM_DB db)
	Persist in-memory tables to disk. More...

RDM_RETCODE	rdm_dbPrecommit (RDM_DB db)

RDM_RETCODE	rdm_dbRebuildKey (RDM_DB db, RDM_KEY_ID keyId, uint32_t reportFrequency, RDM_REBUILD_INDEX_REPORT_FCN *fcn)
	Rebuild keys for an index. More...

RDM_RETCODE	rdm_dbRebuildKeys (RDM_DB db, uint32_t numKeys, const RDM_KEY_ID keyId, uint32_t reportFrequency, RDM_REBUILD_INDEX_REPORT_FCN fcn)
	Rebuild keys for one or more indexes. More...

RDM_RETCODE	rdm_dbReinsertRow (RDM_DB db, RDM_TABLE_ID tableId, RDM_ROWID_T rowId, const void colValues, size_t bytesIn, RDM_CURSOR pCursor)
	Insert a new row into a table. More...

RDM_RETCODE	rdm_dbSetCatalog (RDM_DB db, const char *catalog)
	Associate a catalog with an allocated database. More...

RDM_RETCODE	rdm_dbSetCatalogFromFile (RDM_DB db, const char *catfile)
	Associate a catalog with an allocated database. More...

RDM_RETCODE	rdm_dbCompileCatalog (RDM_DB db, const char *schema)
	Associate a schema with an allocated database. More...

RDM_RETCODE	rdm_dbCompileCatalogFromFile (RDM_DB db, const char *schemafile)
	Associate a catalog with an allocated database. More...

RDM_RETCODE	rdm_dbLoadCatalog (RDM_DB db, const char *catalog)
	Associate a catalog with an allocated database. More...

RDM_RETCODE	rdm_dbLoadCatalogFromFile (RDM_DB db, const char *catfile)
	Associate a catalog with an allocated database. More...

RDM_RETCODE	rdm_dbSetEncrypt (RDM_DB db, RDM_ENCRYPT enc)
	Associate an encryption context with a database handle. More...

RDM_RETCODE	rdm_dbSetErrorHandler (RDM_DB db, RDM_ERROR_FCN errorFunction, void *userData)
	Replace default error reporting with a custom function. More...

RDM_RETCODE	rdm_dbSetOption (RDM_DB db, const char keyword, const char strValue)
	Set a single RDM option from a string. More...

RDM_RETCODE	rdm_dbSetOptions (RDM_DB db, const char *optString)
	Set RDM options. More...

RDM_RETCODE	rdm_dbStartRead (RDM_DB db, const RDM_TABLE_ID tableIds, uint32_t numTableIds, RDM_TRANS pTrans)
	Get read locks. More...

RDM_RETCODE	rdm_dbStartSnapshot (RDM_DB db, const RDM_TABLE_ID tableIds, uint32_t numTableIds, RDM_TRANS pTrans)
	Start a snapshot. More...

RDM_RETCODE	rdm_dbStartUpdate (RDM_DB db, const RDM_TABLE_ID writeTableIds, uint32_t numWriteTableIds, const RDM_TABLE_ID readTableIds, uint32_t numReadTableIds, RDM_TRANS *pTrans)
	Get write locks. More...

RDM_RETCODE	rdm_dbEvictRowData (RDM_DB db, RDM_TABLE_ID evictTableId)
	Evict rows from the runtime cache. More...

RDM_RETCODE	rdm_dbEvictKeyData (RDM_DB db, RDM_KEY_ID evictKeyId)
	Evict key from the runtime cache. More...

RDM_RETCODE	rdm_dbTableSetMaxRows (RDM_DB db, RDM_TABLE_ID table, uint32_t maxrows)
	Set the max number of rows in a table. More...

RDM_RETCODE	rdm_dbTriggersOff (RDM_DB db)
	Disable use of triggers for an open database. More...

RDM_RETCODE	rdm_dbTriggersOn (RDM_DB db)
	Enable use of triggers for an open database. More...

RDM_RETCODE	rdm_dbTriggersStatus (RDM_DB db, RDM_TRIGGERS_STATUS *pStat)
	Check the triggers use status for a database. More...

RDM_RETCODE	rdm_dbRepair (RDM_DB db, const char *optString)

RDM_RETCODE	rdm_dbFindTableIdByName (RDM_DB db, const char tableName, RDM_TABLE_ID pTableId)
	Find the ID of the table specified by the name. More...

RDM_RETCODE	rdm_dbFindColumnIdByName (RDM_DB db, RDM_TABLE_ID tableId, const char columnName, RDM_COLUMN_ID pColumnId)
	Find the ID of the column specified by the name. More...

RDM_RETCODE	rdm_dbFindColumnIdsForTable (RDM_DB db, RDM_TABLE_ID tableId, RDM_COLUMN_INFO pColumns, uint16_t numColumnsIn, uint16_t pNumColumnsOut)
	Retrieve the list of column IDs for the specified table. More...

RDM_RETCODE	rdm_dbFindPrimaryKeyIdByTableId (RDM_DB db, RDM_TABLE_ID tableId, RDM_KEY_ID *pKeyId)
	Find the ID of the primary key of the table specified by the table ID. More...

Detailed Description

Header for the RDM Database APIs.

Function Documentation

rdm_dbClearCache()

RDM_RETCODE rdm_dbClearCache ( RDM_DB db )

Parameters

[in] db A valid RDM database handle

rdm_dbEvictKeyData()

RDM_RETCODE rdm_dbEvictKeyData	(	RDM_DB	db,
		RDM_KEY_ID	evictKeyId
	)

Evict key from the runtime cache.

Call this function to evict key data from the runtime cache without committing the content. Calling this function may reduce the memory footprint of RDM at the cost of I/O.

Use caution in calling this function as it may worsen performance. Using this function may make rdm_dbEnd() and rdm_transEnd() execute faster. Avoid using this function for small transactions or transactions that are likely to be aborted.

If insert, updates and deletes are done in key order, there is very little extra total overhead using this function. On the other hand, operations done in random order may incur a lot of extra total overhead.

How much content is evicted from the runtime cache is an implementation detail.

This function currently returns successfully without doing anything. The behaviour will change in future releases.

See also: rdm_dbStartUpdate

Return values

sOKAY	Normal, successful return.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.

Parameters

[in]	db	A valid RDM database handle
[in]	evictKeyId	The key id of key entries to evict

rdm_dbEvictRowData()

RDM_RETCODE rdm_dbEvictRowData	(	RDM_DB	db,
		RDM_TABLE_ID	evictTableId
	)

Evict rows from the runtime cache.

Call this function to evict inserted or updated rows from the runtime cache without committing the rows. Calling this function may reduce the memory footprint of RDM at the cost of I/O.

Use caution in calling this function as it may worsen performance. Using this function may make rdm_dbEnd() and rdm_transEnd() execute faster. Avoid using this function for small transactions or transactions that are likely to be aborted.

How many rows or which rows are evicted from the runtime cache is an implementation detail.

This function currently returns successfully without doing anything. The behaviour will change in future releases.

See also: rdm_dbStartUpdate

Return values

sOKAY	Normal, successful return.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.

Parameters

[in]	db	A valid RDM database handle
[in]	evictTableId	The table identifier for rows to evict

rdm_dbFindColumnIdByName()

RDM_RETCODE rdm_dbFindColumnIdByName	(	RDM_DB	db,
		RDM_TABLE_ID	tableId,
		const char *	columnName,
		RDM_COLUMN_ID *	pColumnId
	)

Find the ID of the column specified by the name.

This function accepts a database handle, a table ID and a column name, and returns the corresponding ID for the column. The value of the returned column ID is identical to the enumerated value of the column assigned in the structure header file generated by rdm-compile.

Locking Requirements: None.

Return values

sOKAY	Normal, successful return.
sNOTFOUND	Requested item not found.
eDBNOTOPEN	Database not open.
eINVNULLARG	Function argument cannot be NULL.
eINVTABID	Invalid table id.

Parameters

[in]	db	A valid RDM database handle
[in]	tableId	ID of the table for which to retrieve the column ID
[in]	columnName	Name of a valid column that belongs to the table
[out]	pColumnId	ID of the specified column

rdm_dbFindColumnIdsForTable()

RDM_RETCODE rdm_dbFindColumnIdsForTable	(	RDM_DB	db,
		RDM_TABLE_ID	tableId,
		RDM_COLUMN_INFO *	pColumns,
		uint16_t	numColumnsIn,
		uint16_t *	pNumColumnsOut
	)

Retrieve the list of column IDs for the specified table.

This function accepts a database handle and a table ID, and returns a list of column names and corresonding IDs available to the specified table. An RDM_COLUMN_INFO structure consists of name and ID fields. The values of the returned column IDs are identical to the enumerated values of the columns assigned in the structure header file generated by rdm-compile.

If pColumns is NULL, the function returns the number of available columns to the specified table in pNumColumnsOut. If both a\ pColumns and pNumColumnsOut are NULL, the function returns eINVNULLARG.

Remarks: If the table has fewer columns than specified in numColumns, the function returns the name and IDs of all columns in the table, leaving the remaining elements of pColumns untouched. If the table has more columns than specified, the function returns sTRUNCATE and fills the pColumns array up to numColumnsIn elements.

Return values

sOKAY	Normal, successful return.
sTRUNCATE	Result is truncated.
eDBNOTOPEN	Database not open.
eINVNULLARG	Function argument cannot be NULL.
eINVTABID	Invalid table id.

Parameters

[in]	db	A valid RDM database handle
[in]	tableId	ID of the table for which to retrieve the column ID
[in]	pColumns	Array of the column information structure
[in]	numColumnsIn	Number of columns
	pNumColumnsOut	K [out] Actual number of columns returned

rdm_dbFindPrimaryKeyIdByTableId()

RDM_RETCODE rdm_dbFindPrimaryKeyIdByTableId	(	RDM_DB	db,
		RDM_TABLE_ID	tableId,
		RDM_KEY_ID *	pKeyId
	)

Find the ID of the primary key of the table specified by the table ID.

This function accepts a database handle and a table ID, and returns the ID of the primary key of that table. The value of the returned primary key ID is identical to the enumerated value of the primary key specified in the structure header file generated by rdm-compile.

Locking Requirements: None.

Return values

sOKAY	Normal, successful return.
sNOTFOUND	Requested item not found.
eDBNOTOPEN	Database not open.
eINVNULLARG	Function argument cannot be NULL.
eINVTABID	Invalid table id.

Parameters

[in]	db	A valid RDM database handle
[in]	tableId	RDM table ID of the targettable
[out]	pKeyId	the primary key ID of the targettable

rdm_dbFindTableIdByName()

RDM_RETCODE rdm_dbFindTableIdByName	(	RDM_DB	db,
		const char *	tableName,
		RDM_TABLE_ID *	pTableId
	)

Find the ID of the table specified by the name.

This function accepts a database handle and a table name, and returns the corresponding ID for the table. The value of the returned table ID is identical to the enumerated value of the table assigned in the structure header file generated by rdm-compile.

Locking Requirements: None.

Return values

sOKAY	Normal, successful return.
sNOTFOUND	Requested item not found.
eDBNOTOPEN	Database not open.
eINVNULLARG	Function argument cannot be NULL.

Parameters

[in]	db	A valid RDM database handle
[in]	tableName	Name of a valid table that belongs to the database
[out]	pTableId	ID of the specified table

rdm_dbPrecommit()

RDM_RETCODE rdm_dbPrecommit ( RDM_DB db )

Parameters

[in] db A valid RDM database handle

rdm_dbRepair()

RDM_RETCODE rdm_dbRepair	(	RDM_DB	db,
		const char *	optString
	)

Parameters

[in]	db	A valid RDM database handle
[in]	optString	A semicolon delimited string that contains the utility options

rdm_dbTableSetMaxRows()

RDM_RETCODE rdm_dbTableSetMaxRows	(	RDM_DB	db,
		RDM_TABLE_ID	table,
		uint32_t	maxrows
	)

Set the max number of rows in a table.

This function will set the maximum number of rows in a table.

Locking Requirements: None.

Return values

sOKAY	Normal, successful return.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eSNAPSHOTACTIVE	Snapshot is active.
eREADONLY	Database is read-only and cannot be updated.
eUNAVAIL	Requested resource not available.
sSCHEMACHANGE	A schema change was detected but the current operation succeeded.

Parameters

[in]	db	A valid RDM database handle
[in]	table	array of table identifiers
[in]	maxrows	The maximum number of rows in the table

Functions

Detailed Description

Function Documentation

rdm_dbClearCache()

rdm_dbEvictKeyData()

rdm_dbEvictRowData()

rdm_dbFindColumnIdByName()

rdm_dbFindColumnIdsForTable()

rdm_dbFindPrimaryKeyIdByTableId()

rdm_dbFindTableIdByName()

rdm_dbPrecommit()

rdm_dbRepair()

rdm_dbTableSetMaxRows()