# Native C/C++ API

MamBase C/C++ API follows the common practices for database drivers.

A typical database interaction is as follows:

Connect to a server
Query a server
Receive response
Disconnect

After successfully connecting, a connection descriptor is returned that uniquely identifies the current session. This descriptor will be used in all later API calls.

When API is used, raw types and numeric values not wrapped into constants and typedefs should be avoided. Constant values and underlying types may be different on different platforms and in different API versions.

# mb_connect

MB_HANDLE mb_connect (
    const char * host,
    int sockport,
    const char * user,
    const char * password
);

Attempts to connect to MamBase server.

Parameters:

host — MamBase server hostname
sockport — MamBase server TCP port
user — MamBase server user
password — MamBase server user password

Returned value:

If successful, connection descriptor is returned
In case of failure — MB_INVALID_HANDLE is returned

Currently, MamBase doesn't support authentication. Any values, including NULL, can be passed as user and password.

# mb_disconnect

MB_ERROR_T mb_disconnect (
    MB_HANDLE connection
);

Terminates the connection immediately.

Parameters:

connection — server connection descriptor

Returned value:

MB_SUCCESS (if successful)
error code (in case of failure)

# mb_setoption

void mb_setoption (
    MB_HANDLE connection,
    MB_CONN_OPTIONS option,
    int value
);

Allows specification of connection parameters.

Function parameters:

connection — connection descriptor
option — connection parameter to configure
value — the new value for the parameter: 0 or 1 (currently, connection to MamBase has boolean settings only).

MB_CONN_OPTIONS — enumeration with the following members:

MB_OPT_STREAMED_RESULT — if 1, the server starts to send a response before full query results are obtained.
In this mode, MBAffectedRows() is not available and always returns 0.
MB_OPT_DATETIME_MICROSECONDS — whether datetime values' precision is microseconds (1) or milliseconds (0);
MB_OPT_AVGINTASDOUBLE — if 1 then avg(intfield) function returns double value, if 0 then avg(intfield) function returns int value (like MSSQL).

# mb_errno

MB_ERROR_T mb_errno (
    MB_HANDLE connection
);

Returns code for the latest error associated with the connection.

Parameters:

connection — connection descriptor

Returned value:

MB_SUCCESS — success
MB_ERROR_UNKNOWN = (MB_ERROR | 0) — general error
MB_ERROR_NOT_IMPLEMENTED = (MB_ERROR | 1) — not implemented
MB_ERROR_UNEXPECTED = (MB_ERROR | 2) — unexpected result or state when executing function
MB_ERROR_ARGUMENTS = (MB_ERROR | 3) — incorrect arguments
MB_ERROR_TIMEOUT = (MB_ERROR | 4) — function execution timeout
MB_ERROR_NO\_DATA = (MB_ERROR | 5) — no data; result set is empty

# mb_err_text

const char * mb_err_text (
    MB_HANDLE connection
);

Returns text of the latest error associated with the connection.

Parameters:

connection — connection descriptor

Returned value: error text.

# mb_execute_sql

MB_ERROR_T mb_execute_sql (
    MB_HANDLE connection,
    const char * query,
    size_t length
);

Performs SQL query on the server.

Parameters:

connection — connection descriptor
query — query text
length — query text length

Returned value:

MB_SUCCESS (if successful)
Error code (in case of failure)

Despite its name, the function can perform not only SQL queries, but also SPARQL queries or other queries in supported languages.

The length parameter is used when the query text contains binary data (e.g., the \0 symbol).

# mb_fetch_row

MB_ERROR_T mb_fetch_row (
    MB_HANDLE connection
);

Returns the next result from query result set.

Parameters:

connection — connection descriptor

Returned value:

MB_SUCCESS (if successful)
Error code (in case of failure)

# mb_field_count

int mb_field_count (
    MB_HANDLE connection
);

Returns number of fields of the latest record received using mb_fetch_row.

Parameters:

connection — connection descriptor

Returned value:

The number of fields (if successful)
-1 (in case of failure)

The number of fields in the result set is not a constant value. In a graph model, it may vary from one record to another.

# mb_field_name

MB_ERROR_T mb_field_name (
    MB_HANDLE connection,
    int fieldnum, MBValue * name
);

Returns field name from the latest element of the result set obtained using mb_fetch_row.

Parameters:

connection — connection descriptor
fieldnum — field number (numbering starts from 0)
name — pointer to the MBValue structure that contains result set element

The MBValue structure is defined as follows:

struct MBValue {
 MB_DATA_TYPE type;
 union {
     int intv;
     long long int64v;
     double dbl;
     struct {
         char * str;
         int len;
     };
 };
 bool null;
};

Returned value:

If successful, the function returns MB_SUCCESS and fills the MBValue structure referenced by the name pointer.
In case of failure, the function returns error code.

# mb_field_type

MB_DATA_TYPE mb_field_type ( MB_HANDLE connection, int fieldnum );

Returns the scalar value type of field in the latest record obtained using mb_fetch_row.

Parameters:

connection — connection descriptor
fieldnum — field number (numbering starts from 0)

Returned value is one of the following:

enum MB_DATA_TYPE {
 MB_DATA_NONE,
 MB_DATA_STRING,
 MB_DATA_INT,
 MB_DATA_INT64,
 MB_DATA_DOUBLE,
 MB_DATA_DATETIME,
 MB_DATA_BOOL,
};

In case of error, the MB_DATA_NONE value is returned.

# mb_field_value

MB_ERROR_T mb_field_value (
    MB_HANDLE connection,
    int fieldnum,
    MBValue * v );

Returns value of field in the latest record obtained using mb_fetch_row.

Parameters:

connection — connection descriptor
fieldnum — field number (starting from 0)
v — pointer to the MBValue structure that contains result set element (see the mb_field_name function description)

Returned value:

If successful, returns MB_SUCCESS and fills the MBValue structure referenced by the v pointer.
In case of failure, returns the error code.

# mb_get_tableslist

MB_ERROR_T mb_get_tableslist (
    MB_HANDLE connection,
);

Returns the table list (see also INFORMATION_SCHEMA.TABLES pseudo table description)

Parameters:

connection — connection descriptor.

Returned value:

MB_SUCCESS (if successful)
Error code (in case of failure)

After calling this function, one has to call mb_fetch_row, etc., as if a regular query was executed via mb_execute_sql. A result contains two fields:

name — table name;
type — table type (2 — regular table; 3 — link table, see CREATE TABLE AS EDGE).

# mb_get_tablesсhema

MB_ERROR_T mb_get_tableschema (
    MB_HANDLE connection,
    const char * table,
    size_t length
);

Returns the table column list (see also INFORMATION_SCHEMA.COLUMNS pseudo table description)

Parameters:

connection — connection descriptor
table — table name
length — table name length

Returned value:

MB_SUCCESS (if successful)
Error code (in case of failure)

After calling this function, one has to call mb_fetch_row, etc., as if a regular query was executed via mb_execute_sql. A result contains five fields:

name — field name;
type — field type:
1 — string,
2 — int,
3 — bigint,
4 — double,
5 — datetime,
6 — bool,
7 — date,
8 — if field is a primary key or a foreign key (and is a string thereafter);
subtype — specifies the previous field:
0 — regular field,
1 — primary key,
2 — foreign key;
linktable — referenced table name for foreign key;
nullable — always TRUE in the current version.

# mb_get_indexsсhema

MB_ERROR_T mb_get_indexschema( MB_HANDLE connection );

Returns JSON, containing information about all the indexes in the database

Parameters:

connection — server connection descriptor;

After calling this function, you should call mb_fetch_row, etc. as if a regular query were executed using mb_execute_sql.

The result contains one record with one field containing JSON.

JSON example

[
  {

    "name" : "p_age",
    "table" : "person",
    "fields" : [ "age" ]
  },
  {

    "name" : "p_city",
    "table" : "person",
    "fields" : [ "city" ]
  },
  {

    "name" : "c_model",
    "table" : "car",
    "fields" : [ "model" ]
  }
]

# Creating client application

In Microsoft Visual Studio, included directories and library directories have to be configured:

the mambase/include directory has to be added to the included directories list (Project Properties / VC++ Directories > Include Directories)
the mambase/lib and mambase/bin directories have to be added to the library directories list (Project Properties > VC++ Directories > Library Directories)

There are two options to link the client library:

use preprocessor: #pragma comment(lib, "mbclient.lib")
add mbclient.lib to the list of additional libraries (in Visual Studio: Project properties > Linker > Input Additional Dependencies)

← Graph-SQL ODBC →