mSQL C API (MySQL & mSQL)

19.2.1. Datatypes

The mSQL C API uses a few defined datatypes beyond the standard C types. These types are defined in the `msql.h' header file that must be included when compiling any program that uses the MySQL library.

m_result

A structure containing the results of a SELECT (or SHOW) statement. The actual output of the query must be accessed through m_row elements of this structure.

m_row

A single row of data returned from a SELECT query. Output of all mSQL datatypes are stored in this type (as an array of character strings).

m_field

A structure containing all of the information concerning a specific field in the table. The elements of the m_field structure can be directly examined and are as follows:

char *name

The name of the field.

char *table

The name of the table containing the field. This is a null value if the result set does not correspond to a real table.

int type

The type of the field. This is an integer corresponding to the mSQL SQL datatypes defined in the msql.h header file.

int length

The byte length of the field.

int flags

Zero or more option flags. The flags are accessed through the following macros:

IS_PRI_KEY(flags): Returns true if the field is a primary key.
IS_NOT_NULL(flags): Returns true if the field is defined as NOT NULL.

msqlConnect

int msqlConnect ( char *host )

Creates a connection to the mSQL server whose hostname or IP address is given. If a null value is passed as the argument, the connection is made to the mSQL server on the local host using Unix sockets. The return value is a database handle used to communicate with the database server. In the case of an error, -1 is returned.

Example

/* Create a connection to the database server on the local host */
dbh = msqlConnect( (char *)NULL );
if (dbh == -1) { 
   print "Error connecting!\n"; 
   exit(1); 
}

msqlSelectDB

int msqlSelectDB ( int sock , char *dbName )

Chooses a database for the specified connection. A database must be chosen before any queries are sent to the database server. In the case of an error, -1 is returned.

Example

/* Select the "mydatabase" database */
result = msqlSelectDB( dbh, "mydatabase" );
if (result == -1) { 
   print "Error selecting database!\n"; 
   exit(1); 
}

msqlQuery

int msqlQuery( int sock , char *query )

Executes the given SQL query. In mSQL 2, the return value is the number of rows affected by the query (or selected by a SELECT query). In mSQL 1, zero is returned upon success. In both versions, in the case of an error, -1 is returned.

Example

rows_returned = msqlQuery( dbh, "SELECT * FROM people" );

msqlStoreResult

m_result *msqlStoreResult()

Stores the result of a SELECT query. This function is called immediately after calling msqlQuery with an SQL SELECT query. The results of the query are then stored in the m_result structure. Only after this function has been called, can other queries be sent to the database server. Every m_result structure must be freed using msqlFreeResult when you are finished with it.

Example

m_result *results;

rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
results = msqlStoreResult();
/* Other queries may now be submitted and the data from this query can be
   accessed through 'results' */

msqlFreeResult

void msqlFreeResult ( m_result *result )

Frees the memory associated with an m_result structure.

Example

m_result *results;

rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
results = msqlStoreResult();

/* Do work */

msqlFreeResult(results);

msqlFetchRow

m_row msqlFetchRow ( m_result *result )

Retrieves a single row of data from a result set. This data is placed in an m_row structure, which is an array of character strings. With each successive call to msqlFetchRow, another row is returned until there are no more rows left, then a null value is returned.

Example

m_result *results;
m_row *row;

rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
results = msqlStoreResult();
row = msqlFetchRow(results);
printf("The third field of the first row of the table is: %s\n", row[2]);

msqlDataSeek

void msqlDataSeek ( m_result *result, int pos )

Sets the cursor that tells msqlFetchRow which row to fetch next. Setting a position of will move the cursor to the beginning of the data. Setting the cursor to a position past the last row of data will place the cursor at the end of the data.

Example

m_result *results;
m_row *row;

rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
results = msqlStoreResult();
row = msqlFetchRow(results);
/* Now go back to the beginning */
msqlDataSeek(results, 0);

msqlNumRows

int msqlNumRows ( m_result *result )

Returns the number of rows in the result set.

Example

rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
results = msqlStoreResult();
rows = msqlNumRows(results);

msqlFetchField

m_field *msqlFetchField ( m_result *result )

Returns the information about the fields in the result set. Each successive call to msqlFetchField will return a m_field structure for the next field until there are no more fields left, then a null value will be returned.

Example

m_field *field;

rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
results = msqlStoreResult();
field = msqlFetchField(results);
/* 'field' now contains information about the first field in the result set */
field = msqlFetchField(results);
/* 'field' now contains information about the second field in the result set */

msqlFieldSeek

void msqlFieldSeek ( m_result *result , int pos )

Sets the cursor that tells msqlFetchField which field to fetch next. Setting a position of will move the cursor to the beginning of the fields. Setting the cursor to a position past the last field places the cursor just past the last field.

Example

m_result *results;
m_field *field;

rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
results = msqlStoreResult();
field = msqlFetchField(results);
/* Now go back to the beginning */
msqlFieldSeek(results, 0);

msqlNumFields

int msqlNumFields ( m_result *result )

Returns the number of fields in the result set.

Example

rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
results = msqlStoreResult();
fields = msqlNumFields(results);

msqlClose

int msqlClose ( int sock )

Closes the connection to the mSQL database server.

Example

dbh = msqlConnect( (char *)NULL );
/* Do work */
msqlClose(dbh);

msqlListDBs

m_result *msqlListDBs ( int sock )

Returns an m_result structure containing the names of all of the databases available in the database server. Like all m_result structures, the return value of this function must be freed with msqlFreeResult when you are done with it.

Example

databases = msqlListDBs(dbh);
/* 'databases' now contains the names of all of the databases on the server */

msqlListTables

m_result *msqlListTables ( int sock )

Returns an m_result structure containing the names of all of the tables in the current database. Like all m_result structures, the return value of this function must be freed with msqlFreeResult when you are done with it.

Example

tables = msqlListTables(dbh);
/* 'tables' now contains the names of all of the tables in the 
    current database */

msqlListFields

m_result *msqlListFields ( int sock , char *tableName )

Returns an m_result structure containing the names of all of the fields in the given table. Like all m_result structures, the return value of this function must be freed with msqlFreeResult when you are done with it.

Example

fields = msqlListFields(dbh, "people");
/* 'fields' now contains the names of all of the fields in the 
    'people' table */

msqlListIndex

m_result *msqlListIndex ( int sock , char *tableName , char *index )

Returns an m_result structure containing information about the given index. The returned result set will contain the type of index (currently, `avl' is the only supported type), and the names of the fields contained in the index. Like all m_result structures, the return value of this function must be freed with msqlFreeResult when you are done with it.

Example

index = msqlListIndex(dbh, "people", "idx1");
/* 'index' now contains the information about the 'idx1' index in the 'people'
   table */

19.2. mSQL C API

19.2.1. Datatypes

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example