RDM_CPP::Db Class Reference

The Db base class. More...

#include "cpp-db.h"

Public Member Functions

Db (void) throw ()
Db Default Constructor. More...
Db (const Db &db) throw ()
Db Copy Constructor. More...
Db & operator= (const Db &db) throw ()
Db assignment operator. More...
TFS GetTFS (void)
Get the TFS object associated with the Db. More...
void DeleteAllRows (void) const
Removes all rows from all tables. More...
void DeleteAllRows (RDM_TABLE_ID tableId) const
Removes all rows from a table. More...
void SetOptions (const char *optString) const
Set a database option. More...
void SetOptions (const std::string &optString) const
void SetOption (const char *option, const char *value) const
void SetOption (const std::string &option, const std::string &value) const
Transaction StartRead (const RDM_TABLE_ID tableIds[]=NULL, uint32_t num=0) const
Begin reading from a database. More...
Transaction StartUpdate (const RDM_TABLE_ID writeTableIds[], uint32_t numWriteTableIds, const RDM_TABLE_ID readTableIds[]=NULL, uint32_t numReadTableIds=0) const
Begin updating a database. More...
Transaction StartUpdate (const RDM_TABLE_ID writeTableIds[]=NULL, const RDM_TABLE_ID readTableIds[]=NULL, uint32_t numReadTableIds=0) const
Transaction StartSnapshot (const RDM_TABLE_ID tableIds[]=NULL, uint32_t num=0) const
Create a static snapshot of the database. More...
void Precommit (void) const
Precommit a database transaction. More...
void End (void) const
End a transaction. More...
void EndRollback (void) const
Rollback a transaction. More...
RDM_TRANS_STATUS GetTransactionStatus (void) const
Get the current database transaction status. More...
bool IsOpenedExclusive (void) const
Check to see the database is opened exclusively. More...
bool IsOpenedShared (void) const
Check to see the database is opened in shared mode. More...
bool IsOpenedReadOnly (void) const
Check to see the database is opened in read-only mode. More...
void BuildKeys (const char *optString)
Rebuild keys. More...
void Export (const char *optString) const
Export database into text files. More...
void Export (const std::string &optString) const
void Import (const char *optString) const
Import data from text files. More...
void Import (const std::string &optString) const
RDM_DB GetDb ()
Get the internal RDM_DB. More...
RDM_RETCODE GetReturnCode () const
Get current return code value. More...
Db & Release (void)
~Db ()
Db destructor. More...
Db SetCatalog (const char *const catalog=NULL) const
Associate a catalog with an allocated database. More...
Db CompileCatalog (const char *const catalog=NULL) const
Compile a catalog and associate it with an allocated database. More...
Db LoadCatalog (const char *const catalog=NULL) const
Load a catalog and associate it with an allocated database. More...
Db SetCatalogFromFile (const char *const file) const
Associate a catalog stored in a file with an allocated database. More...
Db CompileCatalogFromFile (const char *const file) const
Compile a catalog stored on file and associate it with an allocated database. More...
Db LoadCatalogFromFile (const char *const file) const
Load a catalog stored on file and associate it with an allocated database. More...
Db AlterCatalog (const char *const catalog) const
Alter a catalog with an allocated database. More...
RDM_LOCK_STATUS GetLockStatus (RDM_TABLE_ID tableId) const
Get the current lock status of a table. More...
void SetEncrypt (RDM_ENCRYPT enc) const
Add an encryption context to the Db. More...
RDM_ENCRYPT GetEncrypt (void) const
Get the encryption context associated with the Db. More...
void Encrypt (RDM_ENCRYPT enc, const char *optString) const
Encrypt a database. More...
void Vacuum (const char *optString) const
Vacuum a database. More...
void FlushIdIndex () const
Flush the id index. More...
void RebuildIdIndex () const
Rebuild the id index. More...
void ReplicationGetProgress (uint64_t *progress) const
Get The progress with respect to replication. More...
void ReplicationSetProgress (uint64_t progress) const
Set The progress with respect to replication. More...
void ReplicationGet (void *replicationBuffer, size_t bufferSize, size_t &bytesWritten) const
Generate a replication buffer. More...
void ReplicationPut (const void *replicationBuffer, size_t bufferSize) const
Process a replication buffer. More...
void CreateNewPackFile () const
Create a new pack file. More...
void Drop ()
Drop an open database. More...
Db Open (const char *name, RDM_OPEN_MODE mode, const char *const catalog) const
Open the database. More...
Db Open (const char *name, RDM_OPEN_MODE mode=RDM_OPEN_SHARED) const
Db Close () const
Close the database. More...
void ClearCache (void) const
Clear the runtime cache. More...
void TriggersOn (void) const
Turn on the processing of triggers. More...
void TriggersOff (void) const
Turn off the processing of triggers. More...
RDM_TRIGGERS_STATUS TriggersStatus (void) const
Check the triggers status. More...
void RebuildKey (RDM_KEY_ID keyId, uint32_t reportFrequency=0, RDM_REBUILD_INDEX_REPORT_FCN *fcn=NULL) const
Rebuild an index. More...
void RebuildKeys (uint32_t numKeys, const RDM_KEY_ID *keyIds, uint32_t reportFrequency=0, RDM_REBUILD_INDEX_REPORT_FCN *fcn=NULL) const
Rebuild multiples indexes. More...
void Persist (void) const
Persist an in-memory database. More...
std::string GetOption (std::string option) const
Get a single database option into a string. More...
void GetOption (const char *option, char *value, size_t bytesIn, size_t *bytesOut=NULL) const
std::string GetInfo (std::string key) const
Get database information into a string. More...
void GetInfo (const char *key, char *value, size_t bytesIn, size_t *bytesOut=NULL) const
void GetMemoryUsage (uint64_t &systemCurr, uint64_t &systemMax, uint64_t &userCurr, uint64_t &userMax) const
Get database memory usage information. More...
void TableSetMaxRows (RDM_TABLE_ID tableId, uint32_t maxRows) const
Set the maximum number of rows for a table. More...

Friends

class Cursor
class TFS

Detailed Description

The Db base class.

This /ref Db class provides the base database implementation.

This is a class with very little overhead - a single pointer - that is a 'smart pointer' (i.e. will automatically get destroyed when the last reference is removed).

To keep the overhead down this class should have no virtual functions.

Constructor & Destructor Documentation

Db() [1/2]

RDM_CPP::Db::Db ( void )
throw (
)

Db Default Constructor.

The default constructor, copy constructor, assignment operator, and destructor implement a smart pointer for the /ref Db interface and it's generated subclasses. The number of references to the underlying implementation object will be maintained. When the number of references to an implementation object is down to zero the object will be released.

The default constructor will initialize the number of references to the underlying implementation object to one.

Db() [2/2]

RDM_CPP::Db::Db ( const Db & db )
throw (
)

Db Copy Constructor.

The default constructor, copy constructor, assignment operator, and destructor implement a smart pointer for the /ref Db interface and it's generated subclasses. The number of references to the underlying implementation object will be maintained. When the number of references to an implementation object is down to zero the object will be released.

The copy constructor will increment the number of references to the underlying implementation object by one.

~Db()

RDM_CPP::Db::~Db ( )

Db destructor.

The default constructor, copy constructor, assignment operator, and destructor implement a smart pointer for the /ref Db interface and it's generated subclasses. The number of references to the underlying implementation object will be maintained. When the number of references to an implementation object is down to zero the object will be released.

The destructor will decrement the number of references to the underlying implementation object by one.

Member Function Documentation

AlterCatalog()

Db RDM_CPP::Db::AlterCatalog ( const char *const catalog ) const

Alter a catalog with an allocated database.

This method alters a catalog with a /ref Db.

BuildKeys()

void RDM_CPP::Db::BuildKeys ( const char * optString )

Rebuild keys.

This method rebuilds a keys for the database. Rebuilding keys is a two-step process. First, the index is reinitialized. Then, each row that has a key stored in the key file is sequentially read from the database and the key inserted into the index.

This utility can be used to regenerate an index when dbcheck reports an inconsistency.

Locking Requirements
This method requires exclusive access to the database (opened in exclusive mode)
Exceptions
rdm_exception (eINVDBID, eEXCLUSIVE, eNOMEMORY, eREADONLY)
Parameters
[in] optString The BuildKeys option string

ClearCache()

void RDM_CPP::Db::ClearCache ( void ) const

Clear the runtime cache.

Close()

Db RDM_CPP::Db::Close ( ) const

Close the database.

CompileCatalog()

Db RDM_CPP::Db::CompileCatalog ( const char *const catalog = NULL ) const

Compile a catalog and associate it with an allocated database.

This method compiles a catalog and associates it with a /ref Db. The /ref Db must not have a database open. When the database is opened with Open() method the associated catalog will be used. If a catalog is found on the TFS then the specified catalog and the stored catalog will be compared to ensure that they are identical.

CompileCatalogFromFile()

Db RDM_CPP::Db::CompileCatalogFromFile ( const char *const file ) const

Compile a catalog stored on file and associate it with an allocated database.

This method compiles a catalog stored on file and associates it with a /ref Db. The /ref Db must not have a database open. When the database is opened with Open() method the associated catalog will be used. If a catalog is found on the TFS then the specified catalog and the stored catalog will be compared to ensure that they are identical.

CreateNewPackFile()

void RDM_CPP::Db::CreateNewPackFile ( ) const

Create a new pack file.

This method will create a new pack file.

Locking Requirements
None
Exceptions
rdm_exception

DeleteAllRows() [1/2]

void RDM_CPP::Db::DeleteAllRows ( RDM_TABLE_ID tableId ) const

Removes all rows from a table.

This method removes all rows from the specified table

This method must be the only change operations in an update transaction. An exception will be thrown if an update transaction is not active or if any other change operations have occurred in the update transaction prior to calling the DeleteAllRows() method.

Locking Requirements
An Update transaction with locks on the table (and all related tables)
Exceptions
rdm_exception (eINVDBID, eNOSTARTUPDATE)

DeleteAllRows() [2/2]

void RDM_CPP::Db::DeleteAllRows ( void ) const

Removes all rows from all tables.

This method removes all rows from all database tables.

This method must be the only change operations in an update transaction. An exception will be thrown if an update transaction is not active or if any other change operations have occurred in the update transaction prior to calling the DeleteAllRows() method.

Locking Requirements
An Update transaction with locks on all tables in the database
Exceptions
rdm_exception (eINVDBID, eNOSTARTUPDATE)

Drop()

void RDM_CPP::Db::Drop ( )

Drop an open database.

Encrypt()

void RDM_CPP::Db::Encrypt ( RDM_ENCRYPT enc,
const char * optString
) const

Encrypt a database.

This method can encrypt, decrypt, and re-encrypt a Db

When re-encrypting a database you can choose whether to do a full or quick re-encryption. A quick re-encryption will just change the passcode used for encrypting the randomly generated key used to encrypt the actual database contents. In this case the database contents do not need to be read and rewritten so the operation can be performed very quickly.

A full re-encryption will generate a new internal encryption key and will require each database page to be read, decrypted, re-encrypted, and rewritten to the file. This can be a lengthy operation for very large database images.

To decrypt an encrypted database pass in a NULL encryption context (enc).

Locking Requirements
This function requires that the database be opened in exclusive mode
Exceptions
rdm_exception

End()

void RDM_CPP::Db::End ( void ) const

End a transaction.

This method ends an update, read or snapshot transaction.

If the current transaction is an update all changes since the StartUpdate() will be written to the database. The changes are first written to the log file to support recovery and are then written to the database by the TFS.

End() frees all locked files for the database.

Locking Requirements
None
Exceptions
rdm_exception (eINVDBID)

EndRollback()

void RDM_CPP::Db::EndRollback ( void ) const

Rollback a transaction.

The method discards all database changes made between the call to StartUpdate() and the call to EndRollback().

EndRollback() frees all locked tables for the database.

Locking Requirements
None
Exceptions
rdm_exception (eINVDBID)

Export() [1/2]

void RDM_CPP::Db::Export ( const char * optString ) const

Export database into text files.

This method exports data from the database to ASCII text files. The method writes all data from each table to a separate file; it is the table name with file extension ".txt". If a table name is specified in the parameter structure then only that table's rows are exported. The created files will consist of one text line per row with sep_char (default ',') characters separating the columns.

The Export method has two ways of printing extended ASCII characters to the output files. The default is to write out the octal value. Since the Import method cannot handle this, the extended option can be used to print the extended ASCII character as the character. For example, ASCII 2 would be printed as "\002" without the extended and as a smiley face with the extended option.

See dbexp for full details

Locking Requirements
A Snapshot transaction or a Read transaction with locks on all the database tables that will be exported
Exceptions
rdm_exception (eINVDBID, eNOTLOCKED, eNOMEMORY)

RDM Export Library for C++. Linker option:

    -lrdmcppexport
Parameters
[in] optString Export options string

Export() [2/2]

void RDM_CPP::Db::Export ( const std::string & optString ) const
Parameters
[in] optString Export options string

FlushIdIndex()

void RDM_CPP::Db::FlushIdIndex ( ) const

Flush the id index.

This method will flush the database's id index

Locking Requirements
None
Exceptions
rdm_exception

GetDb()

RDM_DB RDM_CPP::Db::GetDb ( )

Get the internal RDM_DB.

Returns
The internal RDM_DB

GetEncrypt()

RDM_ENCRYPT RDM_CPP::Db::GetEncrypt ( void ) const

Get the encryption context associated with the Db.

This method allows the application to retrive the encryption context associated with a /ref Db object. It is possible that multiple encryption contexts are associated with a /ref Db object. If that is the case this function will return the most recently associated encryption context.

GetInfo() [1/2]

void RDM_CPP::Db::GetInfo ( const char * key,
char * value,
size_t bytesIn,
size_t * bytesOut = NULL
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

GetInfo() [2/2]

std::string RDM_CPP::Db::GetInfo ( std::string key ) const

Get database information into a string.

This function retrieves database information into a string value. The key parameter accepts the key for the information to get.

GetLockStatus()

RDM_LOCK_STATUS RDM_CPP::Db::GetLockStatus ( RDM_TABLE_ID tableId ) const

Get the current lock status of a table.

This method returns the current lock status of the specified table. If the /ref Db does not have a lock on the table then the status will be RDM_LOCK_FREE regardless of whether any other sessions have the table locked. This function allows the user to know if the /ref Db currently has access to the table.

GetMemoryUsage()

void RDM_CPP::Db::GetMemoryUsage ( uint64_t & systemCurr,
uint64_t & systemMax,
uint64_t & userCurr,
uint64_t & userMax
) const

Get database memory usage information.

This method retrieves database memory usage information

The memory usage is split between system memory which is memory that is used by the engine and user data which is memory used for storing the user data (rows, keys, blobs, schema, etc.).

For a disk based database the user memory usage will always be 0 as the data is stored on disk and not in-memory.

Both disk and in-memory databases require system memory.

Parameters
[out] systemCurr The current amount of system memory in use for the database (does not include user data - rows, keys, etc.)
[out] systemMax The maximum total amount of system memory in use for the database (does not include user data - rows, keys, etc.)
[out] userCurr The current amount of memory for user data in the database
[out] userMax The maximum amount of memory for user data in the database

GetOption() [1/2]

void RDM_CPP::Db::GetOption ( const char * option,
char * value,
size_t bytesIn,
size_t * bytesOut = NULL
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

GetOption() [2/2]

std::string RDM_CPP::Db::GetOption ( std::string option ) const

Get a single database option into a string.

This function retrieves a single database option into a string value. The key parameter accepts the key for the option to get.

Options are defined using keys or properties. Every key has a name and a value, delimited by an equals sign (=). The key name appears to the left of the equals sign. Key names are not case-sensitive. Unless otherwise noted, values are not case-sensitive.

Key Value Description
api_encoding Specify string encoding for data retrieval.
timeout Specify default lock timeout in seconds.
time_zone Specify current time zone.
storage Specify database storage mode.
cache_size Specify cache size.
collate Specify database UTF8 collation.
error_format Specify error message format.
durability Specify database transaction safety level.
pack_file_size Specify pack file maximum size.
db_size Specify the maximum database size allocation.
vacuum_percentage Specify the vacuum trigger level for pack files.
vacuum_chunk_size Specify the vacuum write size for pack files.

GetReturnCode()

RDM_RETCODE RDM_CPP::Db::GetReturnCode ( ) const

Get current return code value.

The /ref Db object does not throw exceptions for status codes. This function allows you to get the return code from the last method call. If the previous method call did not throw and exception this will either be sOKAY or a status code value. If the previous method call did throw an exception this will be the error code related to that exception.

Returns
The current RDM_RETCODE value

GetTFS()

TFS RDM_CPP::Db::GetTFS ( void )

Get the TFS object associated with the Db.

Each active /ref Db is associated with a TFS object. This method allows a user to get a reference to the TFS object associated with the source /ref Db.

Returns
The TFS object associated with this /ref Db
Locking Requirements
None
Exceptions
rdm_exception

GetTransactionStatus()

RDM_TRANS_STATUS RDM_CPP::Db::GetTransactionStatus ( void ) const

Get the current database transaction status.

Returns
A RDM_TRANS_STATUS value
Locking Requirements
None
Exceptions
rdm_exception (eINVDBID)

Import() [1/2]

void RDM_CPP::Db::Import ( const char * optString ) const

Import data from text files.

This method imports data into the database from ASCII text files. The import functionality is simple enough to allow great quantities of raw ASCII data to be entered into an RDM database with very little specification. With more complex requirements, ImportXML can be instructed to perform mappings between the input data and RDM tables and to make set connections based upon matching column values.

All instructions to Import are placed into a text file in the form of an import specification language (ISL). An ISL specification identifies the database and the files containing ASCII data to be imported. It also contains mappings between the ASCII data fields and the columns.

Locking Requirements
An Update transaction with locks on all tables that will be imported
Exceptions
rdm_exception (eINVDBID, eNOSTARTUPDATE, eNOTLOCKED, sDUPLICATE)

RDM Export Library for C++. Linker option:

    -lrdmcppexport
Parameters
[in] optString import options string

Import() [2/2]

void RDM_CPP::Db::Import ( const std::string & optString ) const
Parameters
[in] optString import options string

IsOpenedExclusive()

bool RDM_CPP::Db::IsOpenedExclusive ( void ) const

Check to see the database is opened exclusively.

Returns
A boolean value
Return values
true the database is opened in exclusive mode
false the database is not opened in exclusive mode
Locking Requirements
None
Exceptions
rdm_exception (eINVDBID)

IsOpenedReadOnly()

bool RDM_CPP::Db::IsOpenedReadOnly ( void ) const

Check to see the database is opened in read-only mode.

Returns
A boolean value
Return values
true the database is opened in read-only mode
false the database is not opened in read-only mode
Locking Requirements
None
Exceptions
rdm_exception (eINVDBID)

IsOpenedShared()

bool RDM_CPP::Db::IsOpenedShared ( void ) const

Check to see the database is opened in shared mode.

Returns
A boolean value
Return values
true the database is opened in shared mode
false the database is not opened in shared mode
Locking Requirements
None
Exceptions
rdm_exception (eINVDBID)

LoadCatalog()

Db RDM_CPP::Db::LoadCatalog ( const char *const catalog = NULL ) const

Load a catalog and associate it with an allocated database.

This method loads a catalog and associates it with a /ref Db. The /ref Db must not have a database open. When the database is opened with Open() method the associated catalog will be used. If a catalog is found on the TFS then the specified catalog and the stored catalog will be compared to ensure that they are identical.

LoadCatalogFromFile()

Db RDM_CPP::Db::LoadCatalogFromFile ( const char *const file ) const

Load a catalog stored on file and associate it with an allocated database.

This method loads a catalog stored on file and associates it with a /ref Db. The /ref Db must not have a database open. When the database is opened with Open() method the associated catalog will be used. If a catalog is found on the TFS then the specified catalog and the stored catalog will be compared to ensure that they are identical.

Open() [1/2]

Db RDM_CPP::Db::Open ( const char * name,
RDM_OPEN_MODE mode,
const char *const catalog
) const

Open() [2/2]

Db RDM_CPP::Db::Open ( const char * name,
RDM_OPEN_MODE mode = RDM_OPEN_SHARED
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator=()

Db& RDM_CPP::Db::operator= ( const Db & db )
throw (
)

Db assignment operator.

The default constructor, copy constructor, assignment operator, and destructor implement a smart pointer for the /ref Db interface and it's generated subclasses. The number of references to the underlying implementation object will be maintained. When the number of references to an implementation object is down to zero the object will be released.

The assignment operator will increment the number of references to the underlying implementation object by one.

Persist()

void RDM_CPP::Db::Persist ( void ) const

Persist an in-memory database.

Precommit()

void RDM_CPP::Db::Precommit ( void ) const

Precommit a database transaction.

This methods prepares to commit a transaction by writing to the database log file all changes made since the most recent call to StartUpdate(). Following soon after this call, a End() should be called to finally commit the transaction, or EndRollback() to throw it away. The difference between calling Precommit prior to End() is that all file I/O necessary to prepare the transaction will be done during the Precommit, and the End() has a minimal task, essentially flipping a switch to commit the prepared transaction.

This call does not change the status of locks, so it shouldn't be held in this state indefinitely.

No updates or reads should be performed on the database after the Precommit until the end of the transaction.

Locking Requirements
None
Exceptions
rdm_exception (eINVDBID)

RebuildIdIndex()

void RDM_CPP::Db::RebuildIdIndex ( ) const

Rebuild the id index.

This method will rebuild the database's id index

Locking Requirements
None
Exceptions
rdm_exception

RebuildKey()

void RDM_CPP::Db::RebuildKey ( RDM_KEY_ID keyId,
uint32_t reportFrequency = 0,
RDM_REBUILD_INDEX_REPORT_FCN * fcn = NULL
) const

Rebuild an index.

RebuildKeys()

void RDM_CPP::Db::RebuildKeys ( uint32_t numKeys,
const RDM_KEY_ID * keyIds,
uint32_t reportFrequency = 0,
RDM_REBUILD_INDEX_REPORT_FCN * fcn = NULL
) const

Rebuild multiples indexes.

Release()

Db& RDM_CPP::Db::Release ( void )

ReplicationGet()

void RDM_CPP::Db::ReplicationGet ( void * replicationBuffer,
size_t bufferSize,
size_t & bytesWritten
) const

Generate a replication buffer.

This method generates a replication buffer of recent changes that can be applied to another database via a call to the ReplicationPut method. This methode may not be implemented.

Locking Requirements
Database must be opened in RDM_OPEN_REPLICATE_SOURCE mode. Otherwise no locks required.
Exceptions
rdm_exception

ReplicationGetProgress()

void RDM_CPP::Db::ReplicationGetProgress ( uint64_t * progress ) const

Get The progress with respect to replication.

Get The progress with respect to replication. The progress is simply a number. A higher number means more data have been applied.

Use this function prior to starting replication to take progress that have already been made into account. First call this function on the target database DB handle to get its progress and then pass that number to the source database DB handle by calling ReplicationSetProgress(). This methode may not be implemented.

Locking Requirements
Database must be opened in RDM_OPEN_REPLICATE_TARGET mode. Other users that have this database open must have it open in RDM_OPEN_READONLY mode and are only allowed to retrieve data by calling StartSnapshot(). Otherwise no locks required.
Parameters
[out] progress The progress we have made

ReplicationPut()

void RDM_CPP::Db::ReplicationPut ( const void * replicationBuffer,
size_t bufferSize
) const

Process a replication buffer.

This method processes a replication buffer of recent changes and applies them to the database. This methode may not be implemented.

Locking Requirements
Database must be opened in RDM_OPEN_REPLICATE_TARGET mode. Other users that have this database open must have it open in RDM_OPEN_READONLY mode and are only allowed to retrieve data by calling StartSnapshot(). Otherwise no locks required.
Exceptions
rdm_exception

ReplicationSetProgress()

void RDM_CPP::Db::ReplicationSetProgress ( uint64_t progress ) const

Set The progress with respect to replication.

Set The progress with respect to replication. The progress is simply a number. A higher number means more data have been applied.

Use this function prior to starting replication to take progress that have already been made into account. First call rdm_dbReplicationGetProgress() on the target database DB handle to get its progress and then pass that number to the source database DB handle by calling this function. This methode may not be implemented.

Locking Requirements
Database must be opened in RDM_OPEN_REPLICATE_SOURCE mode. Otherwise no locks required.
Parameters
[out] progress The progress we have made

SetCatalog()

Db RDM_CPP::Db::SetCatalog ( const char *const catalog = NULL ) const

Associate a catalog with an allocated database.

This method associates a catalog with a /ref Db. The /ref Db must not have a database open. When the database is opened with Open() method the associated catalog will be used. If a catalog is found on the TFS then the specified catalog and the stored catalog will be compared to ensure that they are identical.

SetCatalogFromFile()

Db RDM_CPP::Db::SetCatalogFromFile ( const char *const file ) const

Associate a catalog stored in a file with an allocated database.

This method associates a catalog with a /ref Db. The /ref Db must not have a database open. When the database is opened with Open() method the associated catalog will be used. If a catalog is found on the TFS then the specified catalog and the stored catalog will be compared to ensure that they are identical.

SetEncrypt()

void RDM_CPP::Db::SetEncrypt ( RDM_ENCRYPT enc ) const

Add an encryption context to the Db.

This method will associate an encryption context to a /ref Db. When a database is opened the system will use the encryption contexts associated with the /ref Db to attempt to open the database.

Typically you would associate the encryption context to a handle prior to opening a database.

You can remove all encryption contexts associated with the /ref Db by passing in a NULL encryption context to this method.

SetOption() [1/2]

void RDM_CPP::Db::SetOption ( const char * option,
const char * value
) const

SetOption() [2/2]

void RDM_CPP::Db::SetOption ( const std::string & option,
const std::string & value
) const

SetOptions() [1/2]

void RDM_CPP::Db::SetOptions ( const char * optString ) const

Set a database option.

This function is used to set any Tfs option. The optString is a key value pair in the form of "key=value".

Options are defined using keys or properties. Every key has a name and a value, delimited by an equals sign (=). The key name appears to the left of the equals sign. Key names are not case-sensitive. Unless otherwise noted, values are not case-sensitive.

Key Value Description
api_encoding Specify string encoding for data retrieval.
timeout Specify default lock timeout in seconds.
time_zone Specify current time zone.
storage Specify database storage mode.
cache_size Specify cache size.
collate Specify database UTF8 collation.
error_format Specify error message format.
durability Specify database transaction safety level.
pack_file_size Specify pack file maximum size.
db_size Specify the maximum database size allocation.
vacuum_percentage Specify the vacuum trigger level for pack files.
vacuum_chunk_size Specify the vacuum write size for pack files.
Locking Requirements
None
Exceptions
rdm_exception (eDBOPEN, eNOMEMORY)

SetOptions() [2/2]

void RDM_CPP::Db::SetOptions ( const std::string & optString ) const

StartRead()

Transaction RDM_CPP::Db::StartRead ( const RDM_TABLE_ID tableIds[] = NULL,
uint32_t num = 0
) const

Begin reading from a database.

Use this method before reading data from the database. Specify the tables you want access to or RDM_LOCK_ALL for every table. You are not allowed to combine this method with StartSnapshot(). Call End() when you are done reading.

If the tableIds parameter is NULL terminated there is no need to specify the number of items in the array in the num parameter. However if the tableIds parameter is not NULL terminated an exception can occur if the correct value for num is not provided.

See also
Transactions and Locking
Locking Requirements
None.
Exceptions
rdm_exception (eINVDBID, eUNAVAIL, eINVIDENTIFIER)
Parameters
[in] tableIds An array of table ids to be read locked
[in] num The number of tables to be locked

StartSnapshot()

Transaction RDM_CPP::Db::StartSnapshot ( const RDM_TABLE_ID tableIds[] = NULL,
uint32_t num = 0
) const

Create a static snapshot of the database.

Take a snapshot of the databases for reading data from the database. You are not allowed to combine this method with StartRead() or StartSnapshot(). Call End() when you are done reading.

See also
Transactions and Locking
Locking Requirements
None.
Exceptions
rdm_exception (eINVDBID)
Parameters
[in] tableIds An array of table identifiers to be included in the snapshot
[in] num The number of tables in the snapshot

StartUpdate() [1/2]

Transaction RDM_CPP::Db::StartUpdate ( const RDM_TABLE_ID writeTableIds[],
uint32_t numWriteTableIds,
const RDM_TABLE_ID readTableIds[] = NULL,
uint32_t numReadTableIds = 0
) const

Begin updating a database.

Parameters
writeTableIds An array of table ids to be write locked
numWriteTableIds The number of tables to be locked
readTableIds An array of table ids to be read locked
numReadTableIds The number of tables to be locked

Use this method before making any updates to the database. Specify the tables you want access to or RDM_LOCK_ALL for every table. You are not allowed to combine this method with StartRead(). Call End() when you are finished with the update

If the TableIds parameter is NULL terminated there is no need to specify the number of items in the array in the num parameter. However if the TableIds parameter is not NULL terminated an exception can occur if the correct value for num is not provided.

See also
Transactions and Locking
Locking Requirements
None.
Exceptions
rdm_exception (eINVDBID, eUNAVAIL, eINVIDENTIFIER, eREADONLY)
Parameters
[in] writeTableIds An array of table identifiers to be read locked
[in] numWriteTableIds The number of tables to be write-locked
[in] readTableIds An array of table identifiers to be read locked
[in] numReadTableIds The number of tables to be read-locked
Examples
cpp01Example_main.cpp.

StartUpdate() [2/2]

Transaction RDM_CPP::Db::StartUpdate ( const RDM_TABLE_ID writeTableIds[] = NULL,
const RDM_TABLE_ID readTableIds[] = NULL,
uint32_t numReadTableIds = 0
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
[in] writeTableIds An array of table identifiers to be read locked
[in] readTableIds An array of table identifiers to be read locked
[in] numReadTableIds The number of tables to be read-locked

TableSetMaxRows()

void RDM_CPP::Db::TableSetMaxRows ( RDM_TABLE_ID tableId,
uint32_t maxRows
) const

Set the maximum number of rows for a table.

This method set the maximum number of rows for a table

Locking Requirements
None
Exceptions
rdm_exception
Parameters
[in] tableId The table id
[in] maxRows The new maximum number of rows for the table

TriggersOff()

void RDM_CPP::Db::TriggersOff ( void ) const

Turn off the processing of triggers.

TriggersOn()

void RDM_CPP::Db::TriggersOn ( void ) const

Turn on the processing of triggers.

TriggersStatus()

RDM_TRIGGERS_STATUS RDM_CPP::Db::TriggersStatus ( void ) const

Check the triggers status.

Vacuum()

void RDM_CPP::Db::Vacuum ( const char * optString ) const

Vacuum a database.

This method can vacuum a database.

When vacuuming a database you move database objects into the current pack file. When earlier pack files no longer contain any database objects they can be deleted. This is the only method available to reclaim disk space.

Locking Requirements
None
Exceptions
rdm_exception

Friends And Related Function Documentation

Cursor

friend class Cursor
friend

TFS

friend class TFS
friend

The documentation for this class was generated from the following file: