The mSQL C API has remained relatively stable between mSQL Versions 1
and 2. However, several new functions have been added, and there have
been a few changes in the existing function. Wherever a function or
feature can only be used with mSQL 2, it is noted.
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.
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);
}
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);
}
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" );
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' */
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);
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]);
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);
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);
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 */
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);
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);
int msqlClose ( int sock ) | |
Closes the connection to the mSQL database server.
Example
dbh = msqlConnect( (char *)NULL );
/* Do work */
msqlClose(dbh);
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 */
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 */
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 */
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. C Reference |  | 20. Python Reference |
Copyright © 2001 O'Reilly & Associates. All rights reserved.
