The C++ McoSqlEngine Class

This is the principle class for most eXtremeSQL C++ applications. An instance of McoSqlEngine is used to open and connect to an eXtremeDB database, execute SQL statements and process query result sets, and perform other database operations. (Please view the Embedded SQL Quick Start page for an example.)

For an overview see page C++ Classes

The McoSqlEngine class is not thread safe and can only be accessed from a single thread. To guard against improper usage, the McoSqlEngine instance is associated with the thread that this instance was created from. If the engine is used from a different thread, by default the SQL runtime raises an exception.

Sometimes an application might choose to share the engine between multiple threads. It must be understood that proper application-level synchronization is necessary to avoid trouble (including possibly corrupting the database runtime and data). In this case, in order to avoid raising the exception, the application makes use of the grab() method, which associates the engine with the current thread. Alternatively the McoMultithreadedSqlEngine class can be used.

 

The McoSqlEngine methods are listed below. Though it inherits many of its methods from base class SqlEngine, the inheritance lineage is not shown here; the principle methods of SqlEngine are included in the list below. Note that some methods have links to pages with more detailed descriptions.

McoSqlEngine()	Default constructor
McoSqlEngine(McoSqlEngine* engine)	Copy constructor
open( params )	Open the SQL engine with an McoSqlOpenParameters argument
open( database handle )	Open the SQL engine with an eXtremeDB database handle for SQL access
open( parameter list )	Open the SQL engine with a list of parameters
executeQuery(...)	Execute an SQL select statement with a variable list of parameters
vexecuteQuery(...)	Execute an SQL select statement with a va_list argument containing a list of parameters or an array of Value parameters
executeStatement(...)	Execute an SQL insert, update or deletestatement with a variable list of parameters
vexecuteStatement(...)	Execute an SQL insert, update or deletestatement with a va_list argument containing a list of parameters or an array of Value parameters
prepare()	Prepare an SQL prepared statement for later execution; see also page Parameter Substitution Format Specifiers
executePreparedQuery(...)	Execute a prepared select statement
executePreparedStatement(...)	Execute a prepared insert, update or delete statement
beginTransaction(...)	Begin a database transaction
disconnect()	Disconnect the database
close()	Close the database
grab()	Associate this engine instance with the current thread
createConnectionPool()	Create a connection pool needed for parallel query execution
destroyConnectionPool()	Destroy the connection pool created by createConnectionPool()
connectionPoolSize()	Return the connection pool size
registerExternalTables(McoSql::Table** tables, size_t n_tables)	Register external tables, i.e. tables located in other DBMS or files. xSQL provides an open implementation of McoSql::Table and other classes (functionality similar to "foreign data wrappers" for Postgres or "federated tables" for mySQL).
save(char const *databaseFile)	Save a database image to the specified file
save(void *stream, mco_stream_write streamWriter)	Save a database image using a stream writer
saveClass(char const *filePath, char const *className)	Save the table contents to the specified file
loadClass()	Load the table contents from the specified file
saveMetadata(char const *metadataFile)	Save the database metadata (compatible with xSQL) to the specified file
saveMetadata(void *stream, mco_stream_write streamWriter);	Save the database metadata (compatible with xSQL) using a stream writer
saveDictionary(char const *dictionaryFile)	Save the database dictionary to the specified file
saveDictionary(void *stream, mco_stream_write streamWriter)	Save the database dictionary using a stream writer
backupCreate(...)	Perform an incremental backup
backupInfo(...)	List the contents of a backup file
backupRestore(...)	Restore a database from an incremental backup
fileBackup(...)	Create a file backup of a disk database - for persistent databases only
checkInterrupted()	Check the interrupted flag which is cleared before execution of each SQL query. (When calling fileBackup() it may be necessary to set this flag with setInterrupted() to manage long running backups)
setInterrupted( bool trueOrFalse )	Set the interrupted flag which is cleared before execution of each SQL query. (When calling fileBackup() it may be necessary to set this flag to manage long running backups)
setFreeMemoryThreshold(size_t threshold)	Setting this threshold causes the memory allocator to set error status in the current transaction state when the amount of free memory is below the specified threshold. This threshold allows the eXtremeDB runtime to gracefully perform unwind or recovery if there is no free memory at all.
getFreeMemoryThreshold()	Return the current size of the free memory threshold
getHandle()	Get the database handle which can be used by eXtremeDB C API functions
getLastAutoid()	Return the autoid (64 bit integer value) of the last object allocated
setTransactionPolicy(MCO_COMMIT_POLICY policy)	Change the transaction commit policy for the current connection
flush()	Flush all changes done by committed transactions to the disk. (Note that this method can be used to save database changes to disk when the MCO_COMMIT_NO_FLUSH transaction policy is used.)
getName()	Return the database name
detach()	Detach from buy do not close the database keeping it in shared memory
isDetached()	Returns true if detach() was called
getPageSize()	Returns the database page size
getFreePages()	Returns the number of free in-memory pages
getTotalPages()	Returns the total number of in-memory pages
getDiskInfo()	Get information about disk usage
license( char * key )	Set license key (for license-protected packages only). (The license key must be set before calling any of the open() methods
setInterrupted(bool enable)	Mark the current query as interrupted. This is used to implement interruption of long running queries.
DESTROY(McoSqlEngine)	This macro generates the default destructor for eXtremeSQL C++ classes.