Step 3: Opening Databases

Before performing data storage and retrieval operations, we must open the database, as demonstrated in SDK sample samples/native/core/02_open_conv. eXtremeDB uses the notion of logical devices to describe storage locations. For an all-in-memory database, there can be a single device to describe the conventional (aka local or in-process) or shared memory for the database. The 02_open_conv sample demonstrates how to open an all-in-memory database in “conventional” memory, while sample 02_open_dbextend demonstrates the use of an array of devices to allow the application to extend the in-memory database.

The database dictionary is the compiled form of the schema which is accessed via the generated function <dbname>_get_dictionary(). This function is typically called as the second parameter in the call to mco_db_open_dev() (see example below).

The following code snippet demonstrates the process of initializing the memory devices and database parameters, then opening an in-memory database:

 
    /* 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_SEGMENT_SIZE;          /* Set the device size */
    dev.dev.conv.ptr = (void*)malloc( DATABASE_SEGMENT_SIZE ); /* Allocate memory and set device pointer */
 
    /* 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 operations */
    db_params.db_max_connections = 1;                /* Set total number of connections to the database */
 
    /* Open a database on the device with given params */
    rc = mco_db_open_dev(db_name, convdb_get_dictionary(), &dev, 1, &db_params );
    if ( MCO_S_OK == rc ) 
    {
        ...
    }
     

For persistent databases, a minimum of four storage devices must be defined. Please see the Opening Persistent Databases page for further details.

Sample 02_open_shared illustrates how to open a shared memory database. The platform-dependent shared memory library mcomipc or mcomw32 is linked into 02_open_shared rather than the conventional memory library mcomconv. Note that if you change the linker directive by substituting mcomconv the database open function mco_db_open_dev() fails with an invalid parameter. This is because the shared memory device dev.type = MCO_MEMORY_NAMED and parameter and dev.named.name are valid only for shared memory, which is implemented in the mcomipc (Unix-Linux), mcompsx (for OSes with the POSIX API such as QNX or VxWorks) or mcomw32 (Win32) library – not with mcomconv. (See package contents for a more detailed explanation of the eXtremeDB runtime libraries.)

Remember that once a database has been opened, the application should close it by calling mco_db_close() before terminating.