C/C++ Guides

Home

The Database C API

The MoSync Database API provides a set of syscall functions that enable you to create and access databases from your C/C++ code using the SQL query language. The Database API makes use of the SQLite database manager.

Supported platforms: Android, iOS, MoSync MoRE emulator.

Database API functions

The MoSync Database API consists of a set of low-level syscall functions:

  • maDBOpen — Opens a database file. The database is created if it does not exist.
  • maDBClose — Closes a database. 
  • maDBExecSQL — Executes an SQL statement. If the statement returns a query result, a cursor handle is returned.
  • maDBExecSQLParams — Executes a parameterized SQL statement.
  • maDBCursorDestroy — Deallocates a cursor returned by maDBExecSQL or maDBExecSQLParams.
  • maDBCursorNext Move the cursor to the next row in the result set. You must call this function before retrieving column data (the initial position of the cursor is before the first row).
  • maDBCursorGetColumnData — Get a field value in the current row as a data handle. 
  • maDBCursorGetColumnText — Get a field value in the current row as a text buffer (note that the string is NOT zero terminated). 
  • maDBCursorGetColumnInt — Get a field value in the current row as an integer. 
  • maDBCursorGetColumnDouble — Get a field value in the current row as a double.

General usage

These are the main steps you need to follow when you use the Database API:

  1. Open the database with maDBOpen. The database is in a file and you need to specify the full path to the file. The database is created if it does not exist.

  2. If this is the first time the application is launched, create the tables needed and populate them with initial data using maDBExecSQL. You can use a store (a file in the local file system) to save a value that indicates if the application has been initialized.

  3. Use maDBExecSQL to insert, update and query data. The SQL dialect used by the Database API is SQLite. Explore the SQLite documentation to learn mroe about this SQL dialect.

  4. For queries, use the cursor returned by maDBExecSQL to iterate over the query result with maDBCursorNext (see the code example below).

  5. Deallocate the cursor with maDBCursorDestroy when finished using it.

  6. Close the database with maDBClose.

If you want to delete the database, delete the database file using the MoSync File API.

Iterating over a query result

// Compute average age of persons in the database.

// Variable to hold the age of a person. 
int age; 

// Variable to hold the age sum. 
int ageSum = 0; 

// Number of persons. 
int numberOfPersons = 0; 

// Query all rows from the table named "person". 
MAHandle cursor = maDBExecSQL(db, "SELECT age FROM person"); 

// Iterate of the result set. 
while (cursor > 0 && MA_DB_OK == maDBCursorNext(cursor))
{
    // Get the age of the current row (first field has index zero) 
    // and update variables. 
    maDBCursorGetColumnInt(cursor, 0, &age); 
    ageSum += age; ++ numberOfPersons; 
}

// Compute average age. 
if (numberOfPersons > 0)
{
    float ageAverage = (float) ageSum / (float) numberOfPersons; 
    printf("Average age is: %.1f\n", ageAverage); 
}

Example application

Have a look at the Database API in action by running the example application DatabaseTest. This example is included in the MoSync SDK and demonstrates the features of the Database API.

MoSync SDK 3.3
Copyright © 2013 MoSync AB
www.mosync.com