eXtremeSQL Runtime Initialization in C

The SQL interface to an eXtremeDB database in eXtremeSQL embedded C applications, typically called the SQL engine, is of type database_t and is created by calling mcoapi_create_engine(). But first, as with all eXtremeDB applications using the C API, the runtime is initialized and error handler registered (optional but recommended), then the memory device(s) and database parameters are specified before opening and connecting to the database. Please refer to the Memory Devices and Open Parameters page for a more detailed explanation of how to define memory devices and the database parameters. The following code snippet demonstrates these steps for a single-user application using a memory-only database:

     
    int main(int argc, char** argv)
    {
        MCO_RET           rc;
        mco_db_h          db;
        mco_device_t      dev;
        mco_db_params_t   db_params;
        database_t        engine;
         
        /* set fatal error handler */
        mco_error_set_handler(extremedb_error_handler);
         
        /* start eXtremeDB runtime */
        mco_runtime_start();
     
        /* setup memory device as a plain conventional memory region */
        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_SIZE;                  /* set the device size */
        dev.dev.conv.ptr = (void*)malloc( DATABASE_SIZE );  /* allocate database memory */
         
        if ( !dev.dev.conv.ptr ) 
        {
            extremedb_error_handler(MCO_E_NOMEM);
        }
     
        /* initialize and customize the database parameters */
        mco_db_params_init ( &db_params );               /* initialize the params with default values */
        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 use */
        db_params.db_max_connections = 1;                /* set total number of database connections */
        db_params.db_log_type        = REDO_LOG;         /* set transaction log type */
     
        /* open a database on the device with given params */
        rc = mco_db_open_dev(db_name, c_apidb_get_dictionary(), &dev, 1, &db_params );
        if ( MCO_S_OK == rc ) 
        {
            /* connect to the database by name */
            rc = mco_db_connect( db_name, &db );
            if ( MCO_S_OK == rc ) 
            {
                ...
            }
        }
        /* Close the database, stop the eXtremeDB runtime and free the database memory */
        rc = mco_db_close(db_name);
        mco_runtime_stop();
        free( dev.dev.conv.ptr );
    }
     

Once the eXtremeDB runtime is initialized and a database connection is established, a SQL interface to the database (of type database_t) is created by calling mcoapi_create_engine():

 
        rc = mco_db_connect( db_name, &db );
        if ( MCO_S_OK == rc ) 
        {
            database_t        engine;
            rc = (MCO_RET)mcoapi_create_engine(db, &engine);
            if ( MCO_S_OK == rc ) {
                add_person( engine, "John Smith", "unknown", "Team leader", 75000, 80.3f, "Steve Smith");
                show_persons( engine, "John Smith");
            }
        }
         

Then SQL statements can be executed by calling mcosql_execute_query() and mcosql_execute_statement() as demonstrated in the following code snippet from functions add_person() and show_persons():

                 
    MCO_RET add_person(database_t engine, char const* name, char const* address, char const* position,
                uint4 salary, float rating, char const* manager)
    {
        MCO_RET rc = MCO_S_OK;
        ...
        rc = (MCO_RET)mcosql_execute_statement(engine, NULL, NULL,
            "insert into Person (name,address,position,salary,rating,manager) values (%s,%s,%s,%u,%f,%p)",
            name, address, position, salary, rating, manager );
        ...
    }
     
    MCO_RET show_persons( database_t engine, char* name_pattern )
    {
        MCO_RET rc = MCO_S_OK;
        data_source_t data_source = NULL;
        ...
        rc = (MCO_RET)mcosql_execute_query(engine, NULL, &data_source, 
            "select name,position,salary,rating,manager,address from Person where name like %s",
            name_pattern );
        ...
    }
             

For further information about initializing and destroying the SQL engine see the C API SQL Engine Initialization page.