Create/Open Databases in C

To create a database, the application first specifies memory device(s), and database parameters that are then passed to the mco_db_open_dev() API. For an in-memory database the relevant parameters are described below. For persistent databases there are additional considerations. Please use the following link to view detailed instructions for creating or opening persistent databases.

Database Parameters

The database parameters are specified in a mco_db_params_t structure that consists of many elements to determine runtime behavior. The mco_db_params_init() API is called to initialize the database parameters with default values. For In-Memory databases, apart from the default values, typically the only parameters to specify are mem_page_size and max_connections. For example:

     
    int main(int argc, char* argv[])
    {
        ...
        mco_db_params_t       db_params;
        ...
        mco_db_params_init( &db_params );               /* Initialize the params with default values */
        db_params.mem_page_size      = 128; /* Set page size for memory access */
        db_params.db_max_connections = 1;                /* Set total number of connections to the database */
        ...
    }
         

The key elements of the mco_db_params_t structure for in-memory databases are:

mem_page_size	The size in bytes of the database object and index pages
disk_page_size	Set to zero to indicate an in-memory database (and disable disk operations)
db_max_connections	The total number of connections allowed to the database
mode_mask	The database open mode flags.
license_key	Normally this is not specified. But, if required, a license key is provided by McObject Support

Memory page size

The mem_page_size element of mco_db_params_t defines the size of memory pages for conventional memory. The mem_page_size can be calculated to optimize performance and will vary depending on the application dynamics, but as a rule of thumb, page size should be between 80 and 512 bytes; a 128 byte page size is good in most situations.

(Note that for all-in-memory databases disk_page_size will be set to zero by the call to mco_db_params_init().)

(Also note that rtree indexes require larger page sizes. If error codes MCO_ERR_RTREE or MCO_E_DISK_PAGE_POOL_EXHAUSTED are encountered during database transactions, increase the page size in increments until these error codes are remedied.)

Max database connections

The db_max_connections element of mco_db_params_t specifies the maximum number of connections that will be managed for this database. A C application connects to the database (creates a database handle) by passing a database name to the mco_db_connect() function. The database must have been previously created with mco_db_open_dev(), possibly in a different process if the database is in shared memory. If successful, this function returns a handle to a database connection or session. This handle is used in subsequent calls to database runtime functions, particularly the transaction control functions.

Note that all applications must create a separate connection for each thread (task) that accesses the database; database connection handles cannot be shared between different threads or tasks.

Mode mask

The mode_mask element is a bitmask used to specify a combination of runtime options that can be used to optimize performance and or memory consumption. Most In-Memory database applications will not need to modify the default values. (Please see Database Open Modes for a detailed description of the possible options).

Example

Typical application code to create an in-memory database could look like the following:

     
    #define  DATABASE_SEGMENT_SIZE 300 * 1024
    #define  MEMORY_PAGE_SIZE 128
     
    int main(int argc, char* argv[])
    {
        MCO_RET            rc;
        mco_device_t       dev;
        mco_db_params_t    db_params;
        ...
        mco_runtime_start();
        ...
        dev.type       = MCO_MEMORY_CONV;                /* Set the device as a conventional memory device */
        dev.assignment = MCO_MEMORY_ASSIGN_DATABASE;     /* Assign the device as main database memory */
        dev.size       = DATABASE_SEGMENT_SIZE;          /* Set the device size */
        dev.dev.conv.ptr = (void*)malloc( DATABASE_SEGMENT_SIZE ); /* Allocate memory and set device pointer */
        ...
        mco_db_params_init ( &db_params );
        db_params.mem_page_size      = MEMORY_PAGE_SIZE; /* Set page size for the in-memory part */
        db_params.disk_page_size     = 0;                /* Set page size to zero to disable disk operations */
        db_params.db_max_connections = 1;                /* Set total number of connections to the database */
        ...
        rc = mco_db_open_dev(db_name, convdb_get_dictionary(), &dev, 1, &db_params );
            
        if ( MCO_S_OK == rc ) 
        {
            ...
            mco_db_close(db_name);
        }
        ...
        mco_runtime_stop();
    }
     

 

Persistent Databases

Please use the following link to view detailed instructions for creating or opening persistent databases.