# 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`, ``updat`e` or ``delete``statement with a variable list of parameters
> vexecuteStatement(...) | Execute an SQL `insert`, ``updat`e` or ``delete``statement 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`, ``updat`e` 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
> exportXML(char const *xmlFile) | Export database to the specified XML file
> importXML(char const *xmlFile, mco_uint4 transactionSize = 0) | Import database from the specified XML file.
> 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.