rdmdbapi.h File Reference

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_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_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 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.
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