The functions available in the C API are listed below and are described in
greater detail in the next section.
20.4 Descriptions des fonctions C API.
Returns the number of rows affected by the last |
Closes a server connection.
Connects to a MySQL server. This function is deprecated; use
Change user and database on an open connection.
Creates a database. This function is deprecated; use the SQL command
CREATE DATABASE instead.
Seeks to an arbitrary row in a query result set.
Does a |
DBUG_PUSH with the given string.
Drops a database. This function is deprecated; use the SQL command
DROP DATABASE instead.
Makes the server write debug information to the log.
Determines whether or not the last row of a result set has been read.
This function is deprecated; |
may be used instead.
Returns the error number for the most recently invoked MySQL function.
Returns the error message for the most recently invoked MySQL function.
Escapes special characters in a string for use in a SQL statement.
Returns the type of the next table field.
Returns the type of a table field, given a field number.
Returns an array of all field structures.
Returns the lengths of all columns in the current row.
Fetches the next row from the result set.
Puts the column cursor on a specified column.
Returns the number of result columns for the most recent query.
Returns the position of the field cursor used for the last
Frees memory used by a result set.
Returns client version information.
Returns a string describing the connection.
Returns the protocol version used by the connection.
Returns the server version number.
Returns information about the most recently executed query.
Gets or initializes a |
Returns the ID generated for an |
AUTO_INCREMENT column by the previous
Kill a given thread.
Returns database names matching a simple regular expression.
Returns field names matching a simple regular expression.
Returns a list of the current server threads.
Returns table names matching a simple regular expression.
Returns the number of columns in a result set.
Returns the number of rows in a result set.
Set connect options for |
Checks whether or not the connection to the server is working, reconnecting
Executes a SQL query specified as a null-terminated string.
Connects to a MySQL server.
Executes a SQL query specified as a counted string.
Tells the server to reload the grant tables.
Seeks to a row in a result set, using value returned from
Returns the row cursor position.
Connects to a database.
Shuts down the database server.
Returns the server status as a string.
Retrieves a complete result set to the client.
Returns the current thread ID.
Initiates a row-by-row result set retrieval.
To connect to the server, call
mysql_init() to initialize a connection
handler, then call
mysql_real_connect() with that handler (along with
other information such as the hostname, user name and password). When you
are done with the connection, call
mysql_close() to terminate it.
While a connection is active, the client may send SQL requêtesto the server
mysql_real_query(). The difference
between the two is that
mysql_query() expects the query to be
specified as a null-terminated string whereas
expects a counted string. If the string contains binary data (which may
include null bytes), you must use
For each non-
SELECT query (e.g.,
DELETE), you can found out how many rows were affected (changed)
SELECT queries, you retrieve the selected rows as a result set.
(Note that some statements are
SELECT-like in that they return rows.
EXPLAIN. They should
be treated the same way as
There are two ways for a client to process result sets. One way is to
retrieve the entire result set all at once by calling
mysql_store_result(). This function acquires from the server all the
rows returned by the query and stores them in the client. The second way is
for the client to initiate a row-by-row result set retrieval by calling
mysql_use_result(). This function initializes the retrieval, but does
not actually get any rows from the server.
In both cases, you access rows by calling
mysql_fetch_row() accesses rows that have
already been fetched from the server. With
mysql_fetch_row() actually retrieves the row from the server.
Information about as the size of the data values in each row is available by
After you are done with a result set, call
to free the memory used for it.
The two retrieval mechanisms are complementary. Client programs should
choose the approach that is most appropriate for their requirements.
In practice, clients tend to use
An advantage of
mysql_store_result() is that since the rows have all
been fetched to the client, you not only can access rows sequentially, you
can move back and forth in the result set using
mysql_row_seek() to change the current row position within the result
set. You can also find out how many rows there are by calling
mysql_num_rows(). On the other hand, the memory requirements for
mysql_store_result() may be very high for large result sets and you
are more likely to encounter out-of-memory conditions.
An advantage of
mysql_use_result() is that the client requires less
memory for the result set since it maintains only one row at a time (and
since there is less allocation overhead,
mysql_use_result() can be
faster). Disadvantages are that you must process each row quickly to avoid
tying up the server, you don't have random access to rows within the result
set (you can only access rows sequentially), and you don't know how many rows
are in the result set until you have retrieved them all. Furthermore, you
must retrieve all the rows even if you determine in mid-retrieval that
you've found the information you were looking for.
The API makes it possible for clients to respond appropriately to
requêtes(retrieving rows only as necessary) without knowing whether or
not the query is a
SELECT. You can do this by calling
mysql_store_result() after each
mysql_real_query()). If the result set call succeeds, the query
SELECT and you can read the rows. If the result set call
mysql_field_count() to determine whether or not a
result was actually to be expected. If
returns zero, the query returned no data (indicating that it was an
DELETE, etc.), and thus not
expected to return rows. If
mysql_field_count() is non-zero, the
query should have returned rows, but didn't. This indicates that the
query was a
SELECT that failed. See the description for
mysql_field_count() for an example of how this can be done.
mysql_use_result() allow you to
obtain information about the fields that make up the result set (the number
of fields, their names and types, etc.). You can access field information
sequentially within the row by calling
or by field number within the row by calling
mysql_fetch_field_direct(). The current field cursor position may be
changed by calling
mysql_field_seek(). Setting the field cursor
affects subsequent calls to
mysql_fetch_field(). You can also get
information for fields all at once by calling
For detecting and reporting errors, MySQL provides access to error
information by means of the
functions. These return the error code or error message for the most
recently invoked function that can succeed or fail, allowing you to determine
when an error occurred and what it was.