Step 1: Database Definition

Before you begin using eXtremeDB, it is important to understand some basic concepts. For database applications using the C++ API, as with the C API, development consists of three stages on the host environment:

• Data layout definition (creating what is referred to as a database schema) and compilation (which produces database interface files, including the database dictionary; the database dictionary is a binary representation of the database schema that the eXtremeDB runtime uses to understand the data layout, which fields participate in which indexes, etc.).
• Using the eXtremeDB static and schema-specific generated APIs in the application.
• Compiling the database interface files with the application source code and linking with the appropriate eXtremeDB runtime libraries.

Schema definition

The database schema is defined in a high-level C-like Data Definition Language (DDL). The essential DDL statements are a declare database <db_name> to assign the database name, and a class <class_name> to define a database class (corresponds to a table in SQL jargon). For example, the following defines a simple database with name mydb and a single class (table) MyClass with two fields id (an unsigned 4-byte integer) and name (a variable length character string):

 
    declare database mydb;
     
    class MyClass {
        unsigned<4> id;
        string name;
    };
     

Compiling the schema

Typically the schema file will be named with extension .mco; like schema.mco or mydb.mco. Then this file is compiled by the DDL compiler mcocomp to produce the schema-specific database dictionary and data access APIs in the form of a C++ implementation file <db_name>.hpp, a C <db_name>.h header file and a C <db_name>.c implementation file.

For example the following command will produce files mydb.hpp, mydb.h and mydb.c in the current working directory:

 
    ../../host/bin/mcocomp -hpp mydb.mco
     

A more interesting example of DDL usage can be seen in the SDK sample samples/native/core/20_languages/cpp/cppdemo.mco.

Implementing eXtremeDB C++ APIs in the application source code

The C++ API is a "thin" wrapper around the C API. In fact, the generated C++ implementation file (<db_name>.hpp) defines a namespace <db_name> and a C++ class for each database class defined in the schema file. The C++ classes implement class level methods like create(), remove(), and checkpoint() as well as field access methods like id_get(), id_put(), name_get(), name_size() and name_put(). These methods simply implement the corresponding generated C API functions MyClass_new(), MyClass_delete(), MyClass_checkpoint(), MyClass_id_get(), MyClass_id_put(), MyClass_name_get(), MyClass_name_put(), etc.

To use the generated C++ class implementation the application must first include <db_name>.hpp and declare using namespace <db_name>. It is often convenient to subclass the generated classes by creating an application level class that inherits the generated class and extends its functionality with methods like print() or ToString(). For example the following code snippet defines an application level class AppClass that extends the generated MyClass:

 
    #include "mydb.hpp"
    using namespace mydb;
     
    class AppClass: public MyClass
    {
    public:
        void ToString()
        {
            uint4 id;
            uint2 len;
            char name[20];
             
            id_get(id);
            name_get(name, sizeof(name), len);
            name[len] = 0;
            printf("\n[%d]: %s\n", id, name);
        }
    }
     

Compiling and linking the application

As for C applications, at a minimum, a simple C++ application that creates an eXtremeDB database in conventional memory will require the following libraries (by convention we use abbreviated naming, for example, mcolib which will exist as mcolib.lib on Windows platforms and libmcolib.a on Unix-Linux platforms):

mcolib	The “core” runtime library
mcovtmem	The “virtual tables” library for all-in-memory databases
mcomconv	The “memory devices” library for conventional memory
mcosw32, mcosw32n, or mcoslnx	The “synchronization” library
mcouwrt	The “utilities” library

Please refer to the SDK sample samples/native/core/20_languages/cpp/cppdemo for a practical C++ example.

In the next steps we will add some database functionality to applications. The best way to learn these details is to build and run the sample applications and examine the source code described in these steps.