# eXtremeSQL SQL Engine Initialization in C

> Once the database is opened and connected, SQL access to the database is performed via a SQL database “engine” structure defined as type `database_t`. This structure is used, for all calls to the `mcosql_*` functions. The database engine can be created in two ways depending on how the application wants to manage dynamic memory allocations.

> The simplest method is demonstrated in the following code snippet:

> >         /* Create a SQL engine */
> >         rc = (MCO_RET)mcoapi_create_engine(db, &engine);

> >         if ( MCO_S_OK == rc )
> >         {
> >             /* Do database processing ... */
> >             /* Destroy the SQL engine */

> >             rc = (MCO_RET)mcoapi_destroy_engine( engine );

> >             /* Disconnect from and close the database, then free database memory */
> >             rc = mco_db_disconnect(db);
> >             rc = mco_db_close(db_name);
> >             free( dev.dev.conv.ptr );
> >         }

> The pair of functions `mcoapi_create_engine()` and `mcoapi_destroy_engine()` take care of all initialization and cleanup associated with the SQL database engine. However, it is still the application’s responsibility to disconnect from and close the database as well as to free the database memory. Using this method, the standard C runtime dynamic memory allocation functions `malloc()` and `free()` are called internally by the eXtremeSQL runtime for all SQL processing; i.e. parsing and compiling SQL statements, producing result sets, etc.

> Since these memory requirements can be large and unpredictable, some applications prefer to manage the dynamic memory with custom memory management functions. To allow for this, a second method is provided as demonstrated in the following snippet:

> >         #define ALLOC_QUANTUM   1024*1024
> >         #define ALLOC_RETAIN    8*1024*1024

> >         /* define custom memory management functions */
> >         void * mem_alloc( size_t n_bytes )
> >         {
> >             buffer = (void*)malloc( n_bytes );
> >             printf("\n\n\tmem_alloc(): %u bytes allocated at address 0x%" INT8_FORMAT "x\n",
> >             (unsigned int)n_bytes, (int64_t)buffer);
> >             return buffer;
> >         }

> >         void mem_free( void * buf )
> >         {
> >             printf("\n\tmem_free(): memory freed at address 0x%" INT8_FORMAT "x\n", (int64_t)buf);
> >             free(buf);
> >         }

> >         /* connect to the database by name */
> >         rc = mco_db_connect( db_name, &db );

> >         if ( MCO_S_OK == rc )
> >         {
> >             /* Set SQL memory allocator to custom malloc/free */
> >             rs = mcosql_initialize_dynamic_memory_manager(
> >     					&mem_alloc, &mem_free,

> >             ALLOC_QUANTUM, ALLOC_RETAIN);

> >             /* Initialize eXtremeDB SQL mapper */
> >             rs = mcoapi_initialize(db);

> >             /* Open SQL engine */
> >             rs = mcosql_open( &engine );

> >             /* Do normal database processing ... */
> >             /* Close SQL engine and disconnect from database */
> >             rs = mcosql_close( engine );

> >         }

> >         /* close the database, shutdown runtime and free database memory */
> >         rc = mco_db_close(db_name);
> >         mco_runtime_stop();
> >         free( dev.dev.conv.ptr );

> Note the following in this example code:

> - two custom memory management functions `mem_alloc()` and `mem_free()` are defined (these are simple examples that use standard `malloc()` and `free()` with a printf() to display the memory operation; clearly more sophisticated custom memory management is possible).
> - the function `mcosql_initialize_dynamic_memory_manager()` is called to register and initialize the custom functions with the eXtremeSQL runtime. The two pre-defined arguments `ALLOC_QUANTUM` and `ALLOC_RETAIN` provide the runtime with necessary allocation block size and total memory allocation size values.
> - the function `mcoapi_initialize(db)` is called to map runtime internals to the SQL database engine.
> - after these preparatory steps, the SQL database engine is now created using function `mcosql_open( &engine )`.
> - when the SQL database engine is initialized in this way, the function `mcosql_close()` is called to disconnect the database and “destroy” the engine (NB: It is not necessary to call `mco_db_disconnect()` as is required when using `mcoapi_create_engine()` and `mcoapi_destroy_engine()`, however it is necessary to call `mco_db_close()` to close the database).
> - The return code variable `rs` is used to distinguish SQL return codes from the eXtremeDB runtime codes in variable `rc`. SQL return codes are defined in the header file “`include/sql/sqlc.h`”, whereas eXtremeDB runtime codes are defined in “`include/mco.h`”.