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	ReplicationSend (void *replicationBuffer, size_t bufferSize, size_t &bytesWritten) const
	Generate a replication buffer. More...

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

◆ DeleteAllRows() [2/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)

◆ 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]

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.

◆ GetInfo() [2/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.

◆ 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]

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.

◆ GetOption() [2/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.

◆ 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 the database.

Examples: cpp/01_helloworld_cpp/cpp01Example_main.cpp, tfscpp/tfsAlloc.cpp, and tfscpp/tfsAllocDefault.cpp.

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

◆ ReplicationReceive()

void RDM_CPP::Db::ReplicationReceive	(	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.

Locking Requirements: Database must be opened in read-only mode

Exceptions

rdm_exception

◆ ReplicationSend()

void RDM_CPP::Db::ReplicationSend	(	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 ReplicationReceive method

Locking Requirements: Read lock on all tables

Exceptions

rdm_exception

◆ 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 types parameter is NULL terminated there is no need to specify the number of items in the array in the num parameter. However if the types 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 types parameter is NULL terminated there is no need to specify the number of items in the array in the num parameter. However if the types 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: cpp/01_helloworld_cpp/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:

cpp-db.h

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.

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Db() [1/2]

◆ Db() [2/2]

◆ ~Db()

Member Function Documentation

◆ AlterCatalog()

◆ BuildKeys()

◆ ClearCache()

◆ Close()

◆ CompileCatalog()

◆ CompileCatalogFromFile()

◆ CreateNewPackFile()

◆ DeleteAllRows() [1/2]

◆ DeleteAllRows() [2/2]

◆ Drop()

◆ Encrypt()

◆ End()

◆ EndRollback()

◆ Export() [1/2]

◆ Export() [2/2]

◆ FlushIdIndex()

◆ GetDb()

◆ GetEncrypt()

◆ GetInfo() [1/2]

◆ GetInfo() [2/2]

◆ GetLockStatus()

◆ GetMemoryUsage()

◆ GetOption() [1/2]

◆ GetOption() [2/2]

◆ GetReturnCode()

◆ GetTFS()

◆ GetTransactionStatus()

◆ Import() [1/2]

◆ Import() [2/2]

◆ IsOpenedExclusive()

◆ IsOpenedReadOnly()

◆ IsOpenedShared()

◆ LoadCatalog()

◆ LoadCatalogFromFile()

◆ Open() [1/2]

◆ Open() [2/2]

◆ operator=()

◆ Persist()

◆ Precommit()

◆ RebuildIdIndex()

◆ RebuildKey()

◆ RebuildKeys()

◆ Release()

◆ ReplicationReceive()

◆ ReplicationSend()

◆ SetCatalog()

◆ SetCatalogFromFile()

◆ SetEncrypt()

◆ SetOption() [1/2]

◆ SetOption() [2/2]

◆ SetOptions() [1/2]

◆ SetOptions() [2/2]

◆ StartRead()

◆ StartSnapshot()

◆ StartUpdate() [1/2]

◆ StartUpdate() [2/2]

◆ TableSetMaxRows()

◆ TriggersOff()

◆ TriggersOn()

◆ TriggersStatus()

◆ Vacuum()

Friends And Related Function Documentation

◆ Cursor

◆ TFS