C API Prepared Statement Function Descriptions

To prepare and execute queries, use the following functions.

Description

mysql_bind_param() is used to bind data for the parameter markers in the SQL statement that was passed to mysql_prepare(). It uses MYSQL_BIND structures to supply the data. bind is the address of an array of MYSQL_BIND structures. The client library expects the array to contain an element for each ? parameter marker that is present in the query.

Suppose you prepare the following statment:

INSERT INTO mytbl VALUES(?,?,?)

When you bind the parameters, the array of MYSQL_BIND structures must contain three elements, and can be declared like this:

MYSQL_BIND bind[3];

The members of each MYSQL_BIND element that should be set are described in C API Prepared statement datatypes.

Return Values

Zero if the bind was successful. Non-zero if an error occurred.

Errors

CR_NO_PREPARE_STMT No prepared statement exists.
CR_NO_PARAMETERS_EXISTS No parameters exist to bind.
CR_INVALID_BUFFER_USE Indicates if the bind is to supply the long data in chunks and if the buffer type is non string or binary.
CR_UNSUPPORTED_PARAM_TYPE The conversion is not supported. Possibly the buffer_type value is illegal or is not one of the supported types.
CR_OUT_OF_MEMORY Out of memory.
CR_UNKNOWN_ERROR An unknown error occurred.

Example

For the usage of mysql_bind_param(), refer to the Example from mysql_execute().

Description

mysql_bind_result() is used to associate (bind) columns in the result set to data buffers and length buffers. When mysql_fetch() is called to fetch data, the MySQL client/server protocol places the data for the bound columns into the specified buffers.

Note that all columns must be bound to buffers prior to calling mysql_fetch(). bind is the address of an array of MYSQL_BIND structures. The client library expects the array to contain an element for each column of the result set. Otherwise, mysql_fetch() simply ignores the data fetch. Also, the buffers should be large enough to hold the data values, because the protocol doesn't return data values in chunks.

A column can be bound or rebound at any time, even after a result set has been partially retrieved. The new binding takes effect the next time mysql_fetch() is called. Suppose an application binds the columns in a result set and calls mysql_fetch(). The client/server protocol returns data in the bound buffers. Then suppose the application binds the columns to a different set of buffers. The protocol does not place data into the newly bound buffers until the next call to mysql_fetch() occurs.

To bind a column, an application calls mysql_bind_result() and passes the type, address, and the address of the length buffer. The members of each MYSQL_BIND element that should be set are described in C API Prepared statement datatypes.

Return Values

Zero if the bind was successful. Non-zero if an error occurred.

Errors

CR_NO_PREPARE_STMT No prepared statement exists.
CR_UNSUPPORTED_PARAM_TYPE The conversion is not supported. Possibly the buffer_type value is illegal or is not one of the supported types.
CR_OUT_OF_MEMORY Out of memory.
CR_UNKNOWN_ERROR An unknown error occurred.

Example

For the usage of mysql_bind_result(), refer to the Example from mysql_fetch().

Description

mysql_execute() executes the prepared query associated with the statement handle. The currently bound parameter marker values are sent to server during this call, and the server replaces the markers with this newly supplied data.

If the statement is an UPDATE, DELETE, or INSERT, the total number of changed, deleted, or inserted rows can be found by calling mysql_stmt_affected_rows(). If this is a result set query such as SELECT, you must call mysql_fetch() to fetch the data prior to calling any other functions that result in query processing. For more information on how to fetch the results, refer to mysql_fetch().

Return Values

Zero if execution was successful. Non-zero if an error occurred. The error code and message can be obtained by calling mysql_stmt_errno() and mysql_stmt_error().

Errors

CR_NO_PREPARE_QUERY No query prepared prior to execution.
CR_ALL_PARAMS_NOT_BOUND Not all parameter data is supplied.
CR_COMMANDS_OUT_OF_SYNC Commands were executed in an improper order.
CR_OUT_OF_MEMORY Out of memory.
CR_SERVER_GONE_ERROR The MySQL server has gone away.
CR_SERVER_LOST The connection to the server was lost during the query.
CR_UNKNOWN_ERROR An unknown error occurred.

Example

The following example demonstrates how to create and populate a table using mysql_prepare(), mysql_param_count(), mysql_bind_param(), mysql_execute(), and mysql_stmt_affected_rows(). The mysql variable is assumed to be a valid connection handle.

#define STRING_SIZE 50
#define DROP_SAMPLE_TABLE "DROP TABLE IF EXISTS test_table"
#define CREATE_SAMPLE_TABLE "CREATE TABLE test_table(col1 INT,\
                                                 col2 VARCHAR(40),\
                                                 col3 SMALLINT,\
                                                 col4 TIMESTAMP)"
#define INSERT_SAMPLE "INSERT INTO test_table(col1,col2,col3) VALUES(?,?,?)"
MYSQL_STMT    *stmt;
MYSQL_BIND    bind[3];
my_ulonglong  affected_rows;
int           param_count;
short         small_data;
int           int_data;
char          str_data[STRING_SIZE];
unsigned long str_length;
my_bool       is_null;
if (mysql_query(mysql, DROP_SAMPLE_TABLE))
{
  fprintf(stderr, " DROP TABLE failed\n");
  fprintf(stderr, " %s\n", mysql_error(mysql));
  exit(0);
}
if (mysql_query(mysql, CREATE_SAMPLE_TABLE))
{
  fprintf(stderr, " CREATE TABLE failed\n");
  fprintf(stderr, " %s\n", mysql_error(mysql));
  exit(0);
}
/* Prepare an INSERT query with 3 parameters */
/* (the TIMESTAMP column is not named; it will */
/* be set to the current date and time) */
stmt = mysql_prepare(mysql, INSERT_SAMPLE, strlen(INSERT_SAMPLE));
if (!stmt)
{
  fprintf(stderr, " mysql_prepare(), INSERT failed\n");
  fprintf(stderr, " %s\n", mysql_error(mysql));
  exit(0);
}
fprintf(stdout, " prepare, INSERT successful\n");
/* Get the parameter count from the statement */
param_count= mysql_param_count(stmt);
fprintf(stdout, " total parameters in INSERT: %d\n", param_count);
if (param_count != 3) /* validate parameter count */
{
  fprintf(stderr, " invalid parameter count returned by MySQL\n");
  exit(0);
}
/* Bind the data for all 3 parameters */
/* INTEGER PARAM */
/* This is a number type, so there is no need to specify buffer_length */
bind[0].buffer_type= MYSQL_TYPE_LONG;
bind[0].buffer= (char *)&int_data;
bind[0].is_null= 0;
bind[0].length= 0;
/* STRING PARAM */
bind[1].buffer_type= MYSQL_TYPE_VAR_STRING;
bind[1].buffer= (char *)str_data;
bind[1].buffer_length= STRING_SIZE;
bind[1].is_null= 0;
bind[1].length= &str_length;
/* SMALLINT PARAM */
bind[2].buffer_type= MYSQL_TYPE_SHORT;
bind[2].buffer= (char *)&small_data;       
bind[2].is_null= &is_null;
bind[2].length= 0;
/* Bind the buffers */
if (mysql_bind_param(stmt, bind))
{
  fprintf(stderr, " mysql_bind_param() failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}
/* Specify the data values for the first row */
int_data= 10;             /* integer */
strncpy(str_data, "MySQL", STRING_SIZE); /* string  */
str_length= strlen(str_data);
/* INSERT SMALLINT data as NULL */
is_null= 1;
/* Execute the INSERT statement - 1*/
if (mysql_execute(stmt))
{
  fprintf(stderr, " mysql_execute(), 1 failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}
/* Get the total number of affected rows */   
affected_rows= mysql_stmt_affected_rows(stmt);
fprintf(stdout, " total affected rows(insert 1): %ld\n", affected_rows);
if (affected_rows != 1) /* validate affected rows */
{
  fprintf(stderr, " invalid affected rows by MySQL\n");
  exit(0);
}
/* Specify data values for second row, then re-execute the statement */
int_data= 1000;             
strncpy(str_data, "The most popular open source database", STRING_SIZE); 
str_length= strlen(str_data);
small_data= 1000;         /* smallint */
is_null= 0;               /* reset */
/* Execute the INSERT statement - 2*/
if (mysql_execute(stmt))
{
  fprintf(stderr, " mysql_execute, 2 failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}
/* Get the total rows affected */   
affected_rows= mysql_stmt_affected_rows(stmt);
fprintf(stdout, " total affected rows(insert 2): %ld\n", affected_rows);
if (affected_rows != 1) /* validate affected rows */
{
  fprintf(stderr, " invalid affected rows by MySQL\n");
  exit(0);
}
/* Close the statement */
if (mysql_stmt_close(stmt))
{
  fprintf(stderr, " failed while closing the statement\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

Note: For complete examples on the use of prepared statement functions, refer to the file tests/client_test.c. This file can be obtained from a MySQL source distribution or from the BitKeeper source repository.

Description

mysql_fetch() returns the next row in the result set. It can be called only while the result set exists, that is, after a call to mysql_execute() that creates a result set or after mysql_stmt_store_result(), which is called after mysql_execute() to buffer the entire result set.

mysql_fetch() returns row data using the buffers bound by mysql_bind_result(). It returns the data in those buffers for all the columns in the current row set and the lengths are returned to the length pointer.

Note that all columns must be bound by the application before calling mysql_fetch().

If a fetched data value is a NULL value, the *is_null value of the corresponding MYSQL_BIND structure contains TRUE (1). Otherwise, the data and its length are returned in the *buffer and *length elements based on the buffer type specified by the application. Each numeric and temporal type has a fixed length, as listed in the following table. The length of the string types depends on the length of the actual data value, as indicated by data_length.

TypeLength
MYSQL_TYPE_TINY1
MYSQL_TYPE_SHORT2
MYSQL_TYPE_LONG4
MYSQL_TYPE_LONGLONG8
MYSQL_TYPE_FLOAT4
MYSQL_TYPE_DOUBLE8
MYSQL_TYPE_TIMEsizeof(MYSQL_TIME)
MYSQL_TYPE_DATEsizeof(MYSQL_TIME)
MYSQL_TYPE_DATETIMEsizeof(MYSQL_TIME)
MYSQL_TYPE_TIMESTAMPsizeof(MYSQL_TIME)
MYSQL_TYPE_STRINGdata length
MYSQL_TYPE_VAR_STRINGdata_length
MYSQL_TYPE_TINY_BLOBdata_length
MYSQL_TYPE_BLOBdata_length
MYSQL_TYPE_MEDIUM_BLOBdata_length
MYSQL_TYPE_LONG_BLOBdata_length

Return Values

Return ValueDescription
0 Successful, the data has been fetched to application data buffers.
1 Error occurred. Error code and message can be obtained by calling mysql_stmt_errno() and mysql_stmt_error().
MYSQL_NO_DATANo more rows/data exists

Errors

CR_COMMANDS_OUT_OF_SYNC Commands were executed in an improper order.
CR_OUT_OF_MEMORY Out of memory.
CR_SERVER_GONE_ERROR The MySQL server has gone away.
CR_SERVER_LOST The connection to the server was lost during the query.
CR_UNKNOWN_ERROR An unknown error occurred.
CR_UNSUPPORTED_PARAM_TYPE The buffer type is MYSQL_TYPE_DATE, MYSQL_TYPE_TIME, MYSQL_TYPE_DATETIME, or MYSQL_TYPE_TIMESTAMP, but the datatype is not DATE, TIME, DATETIME, or TIMESTAMP.
All other unsupported conversion errors are returned from mysql_bind_result().

Example

The following example demonstrates how to fetch data from a table using mysql_get_metadata(), mysql_bind_result(), and mysql_fetch(). (This example expects to retrieve the two rows inserted by the example shown in mysql_execute().) The mysql variable is assumed to be a valid connection handle.

#define STRING_SIZE 50
#define SELECT_SAMPLE "SELECT col1, col2, col3, col4 FROM test_table"
MYSQL_STMT    *stmt;
MYSQL_BIND    bind[4];
MYSQL_RES     *prepare_meta_result;
MYSQL_TIME    ts;
unsigned long length[4];
int           param_count, column_count, row_count;
short         small_data;
int           int_data;
char          str_data[STRING_SIZE];
my_bool       is_null[4];
/* Prepare a SELECT query to fetch data from test_table */
stmt = mysql_prepare(mysql, SELECT_SAMPLE, strlen(SELECT_SAMPLE));
if (!stmt)
{
  fprintf(stderr, " mysql_prepare(), SELECT failed\n");
  fprintf(stderr, " %s\n", mysql_error(mysql));
  exit(0);
}
fprintf(stdout, " prepare, SELECT successful\n");
/* Get the parameter count from the statement */
param_count= mysql_param_count(stmt);
fprintf(stdout, " total parameters in SELECT: %d\n", param_count);
if (param_count != 0) /* validate parameter count */
{
  fprintf(stderr, " invalid parameter count returned by MySQL\n");
  exit(0);
}
/* Fetch result set meta information */
prepare_meta_result = mysql_get_metadata(stmt);
if (!prepare_meta_result)
{
  fprintf(stderr, " mysql_get_metadata(), returned no meta information\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}
/* Get total columns in the query */
column_count= mysql_num_fields(prepare_meta_result);
fprintf(stdout, " total columns in SELECT statement: %d\n", column_count);
if (column_count != 4) /* validate column count */
{
  fprintf(stderr, " invalid column count returned by MySQL\n");
  exit(0);
}
/* Execute the SELECT query */
if (mysql_execute(stmt))
{
  fprintf(stderr, " mysql_execute(), failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}
/* Bind the result buffers for all 4 columns before fetching them */
/* INTEGER COLUMN */
bind[0].buffer_type= MYSQL_TYPE_LONG;
bind[0].buffer= (char *)&int_data;
bind[0].is_null= &is_null[0];
bind[0].length= &length[0];
/* STRING COLUMN */
bind[1].buffer_type= MYSQL_TYPE_VAR_STRING;
bind[1].buffer= (char *)str_data;
bind[1].buffer_length= STRING_SIZE;
bind[1].is_null= &is_null[1];
bind[1].length= &length[1];
/* SMALLINT COLUMN */
bind[2].buffer_type= MYSQL_TYPE_SHORT;
bind[2].buffer= (char *)&small_data;       
bind[2].is_null= &is_null[2];
bind[2].length= &length[2];
/* TIMESTAMP COLUMN */
bind[3].buffer_type= MYSQL_TYPE_TIMESTAMP;
bind[3].buffer= (char *)&ts;       
bind[3].is_null= &is_null[3];
bind[3].length= &length[3];
/* Bind the result buffers */
if (mysql_bind_result(stmt, bind))
{
  fprintf(stderr, " mysql_bind_result() failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}
/* Now buffer all results to client */
if (mysql_stmt_store_result(stmt))
{
  fprintf(stderr, " mysql_stmt_store_result() failed\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}
/* Fetch all rows */
row_count= 0;
fprintf(stdout, "Fetching results ...\n");
while (!mysql_fetch(stmt))
{
  row_count++;
  fprintf(stdout, "  row %d\n", row_count);
  /* column 1 */
  fprintf(stdout, "   column1 (integer)  : ");
  if (is_null[0])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %d(%ld)\n", int_data, length[0]);
  /* column 2 */
  fprintf(stdout, "   column2 (string)   : ");
  if (is_null[1])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %s(%ld)\n", str_data, length[1]);
  /* column 3 */
  fprintf(stdout, "   column3 (smallint) : ");
  if (is_null[2])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %d(%ld)\n", small_data, length[2]);
  /* column 4 */
  fprintf(stdout, "   column4 (timestamp): ");
  if (is_null[3])
    fprintf(stdout, " NULL\n");
  else
    fprintf(stdout, " %04d-%02d-%02d %02d:%02d:%02d (%ld)\n",
                                               ts.year, ts.month, ts.day,
                                               ts.hour, ts.minute, ts.second,
                                               length[3]);
  fprintf(stdout, "\n");
}
/* Validate rows fetched */
fprintf(stdout, " total rows fetched: %d\n", row_count);
if (row_count != 2)
{
  fprintf(stderr, " MySQL failed to return all rows\n");
  exit(0);
} 
/* Free the prepared result metadata */
mysql_free_result(prepare_meta_result);
/* Close the statement */
if (mysql_stmt_close(stmt))
{
  fprintf(stderr, " failed while closing the statement\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}

Description

Return Values

Errors

Description

If a statement passed to mysql_prepare() is one that produces a result set, mysql_get_metadata() returns the result set metadata in the form of a pointer to a MYSQL_RES structure that can be used to process the meta information such as total number of fields and individual field information. This result set pointer can be passed as an argument to any of the field-based API functions that process result set metadata, such as:

  • mysql_num_fields()

  • mysql_fetch_field()

  • mysql_fetch_field_direct()

  • mysql_fetch_fields()

  • mysql_field_count()

  • mysql_field_seek()

  • mysql_field_tell()

  • mysql_free_result()

The result set structure should be freed when you are done with it, which you can do by passing it to mysql_free_result(). This is similar to the way you free a result set obtained from a call to mysql_store_result().

The result set returned by mysql_get_metadata() contains only metadata. It does not contain any row results. The rows are obtained by using the statement handle with mysql_fetch().

Return Values

A MYSQL_RES result structure. NULL if no meta information exists for the prepared query.

Errors

CR_OUT_OF_MEMORY Out of memory.
CR_UNKNOWN_ERROR An unknown error occurred.

Example

For the usage of mysql_get_metadata(), refer to the Example from mysql_fetch().

Description

Returns the number of parameter markers present in the prepared statement.

Return Values

An unsigned long integer representing the number of parameters in a statement.

Errors

None.

Example

For the usage of mysql_param_count(), refer to the Example from mysql_execute().

Description

Return Values

Errors

Description

Prepares the SQL query pointed to by the null-terminated string query, and returns a statement handle to be used for further operations on the statement. The query must consist of a single SQL statement. You should not add a terminating semicolon (;) or \g to the statement.

The application can include one or more parameter markers in the SQL statement by embedding question mark (?) characters into the SQL string at the appropriate positions.

The markers are legal only in certain places in SQL statements. For example, they are allowed in the VALUES() list of an INSERT statement (to specify column values for a row), or in a comparison with a column in a WHERE clause to specify a comparison value. However, they are not allowed for identifiers (such as table or column names), in the select list that names the columns to be returned by a SELECT statement), or to specify both operands of a binary operator such as the = equal sign. The latter restriction is necessary because it would be impossible to determine the parameter type. In general, parameters are legal only in Data Manipulation Languange (DML) statements, and not in Data Defination Language (DDL) statements.

The parameter markers must be bound to application variables using mysql_bind_param() before executing the statement.

Return Values

A pointer to a MYSQL_STMT structure if the prepare was successful. NULL if an error occurred.

Errors

CR_COMMANDS_OUT_OF_SYNC Commands were executed in an improper order.
CR_OUT_OF_MEMORY Out of memory.
CR_SERVER_GONE_ERROR The MySQL server has gone away.
CR_SERVER_LOST The connection to the server was lost during the query
CR_UNKNOWN_ERROR An unknown error occurred.

If the prepare is not successful (that is, mysql_prepare() returns NULL), the error message can be obtained by calling mysql_error().

Example

For the usage of mysql_prepare(), refer to the Example from mysql_execute().

Description

Allows an application to send parameter data to the server in pieces (or ``chunks''). This function can be called multiple times to send the parts of a character or binary data value for a column, which must be one of the TEXT or BLOB datatypes.

parameter_number indicates which parameter to associate the data with. Parameters are numbered beginning with 0. data is a pointer to a buffer containing data to be sent, and length indicates the number of bytes in the buffer.

Return Values

Zero if the data is sent successfully to server. Non-zero if an error occurred.

Errors

CR_INVALID_PARAMETER_NO Invalid parameter number.
CR_COMMANDS_OUT_OF_SYNC Commands were executed in an improper order.
CR_SERVER_GONE_ERROR The MySQL server has gone away.
CR_OUT_OF_MEMORY Out of memory.
CR_UNKNOWN_ERROR An unknown error occurred.

Example

The following example demonstrates how to send the data for a TEXT column in chunks. It inserts the data value 'MySQL - The most popular open source database' into the text_column column. The mysql variable is assumed to be a valid connection handle.

#define INSERT_QUERY "INSERT INTO test_long_data(text_column) VALUES(?)"
MYSQL_BIND bind[1];
long       length;
if (!mysql_prepare(mysql, INSERT_QUERY, strlen(INSERT_QUERY))
{
  fprintf(stderr, "\n prepare failed");
  fprintf(stderr, "\n %s", mysql_error(mysql));
  exit(0);
}
 memset(bind, 0, sizeof(bind));
 bind[0].buffer_type= MYSQL_TYPE_STRING;
 bind[0].length= &length;
 bind[0].is_null= 0;
/* Bind the buffers */
if (mysql_bind_param(stmt, bind))
{
  fprintf(stderr, "\n param bind failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}
 /* Supply data in chunks to server */
 if (!mysql_send_long_data(stmt,0,"MySQL",5))
{
  fprintf(stderr, "\n send_long_data failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}
 /* Supply the next piece of data */
 if (mysql_send_long_data(stmt,0," - The most popular open source database",40))
{
  fprintf(stderr, "\n send_long_data failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}
 /* Now, execute the query */
 if (mysql_execute(stmt))
{
  fprintf(stderr, "\n mysql_execute failed");
  fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
  exit(0);
}

Description

Returns the total number of rows changed, deleted, or inserted by the last executed statement. May be called immediatlely after mysql_execute() for UPDATE, DELETE, or INSERT statements. For SELECT statements, mysql_stmt_affected_rows() works like mysql_num_rows().

Return Values

An integer greater than zero indicates the number of rows affected or retrieved. Zero indicates that no records were updated for an UPDATE statement, no rows matched the WHERE clause in the query, or that no query has yet been executed. -1 indicates that the query returned an error or that, for a SELECT query, mysql_stmt_affected_rows() was called prior to calling mysql_stmt_store_result(). Because mysql_stmt_affected_rows() returns an unsigned value, you can check for -1 by comparing the return value to (my_ulonglong)-1 (or to (my_ulonglong)~0, which is equivalent).

Errors

None.

Example

For the usage of mysql_stmt_affected_rows(), refer to the Example from mysql_execute().

Description

Closes the prepared statement. mysql_stmt_close() also deallocates the statement handle pointed to by stmt.

If the current statement has pending or unread results, this function cancels them so that the next query can be executed.

Return Values

Zero if the statement was freed successfully. Non-zero if an error occurred.

Errors

CR_SERVER_GONE_ERROR The MySQL server has gone away.
CR_UNKNOWN_ERROR An unknown error occurred.

Example

For the usage of mysql_stmt_close(), refer to the Example from mysql_execute().

Description

Seeks to an arbitrary row in a statement result set. The offset value is a row number and should be in the range from 0 to mysql_stmt_num_rows(stmt)-1.

This function requires that the statement result set structure contains the entire result of the last executed query, so mysql_stmt_data_seek() may be used only in conjunction with mysql_stmt_store_result().

Return Values

None.

Errors

None.

Description

For the statement specified by stmt, mysql_stmt_errno() returns the error code for the most recently invoked statement API function that can succeed or fail. A return value of zero means that no error occurred. Client error message numbers are listed in the MySQL errmsg.h header file. Server error message numbers are listed in mysqld_error.h. In the MySQL source distribution you can find a complete list of error messages and error numbers in the file Docs/mysqld_error.txt. The server error codes also are listed at Error-returns.

Return Values

An error code value. Zero if no error occurred.

Errors

None.

Description

For the statement specified by stmt, mysql_stmt_error() returns a null-terminated string containing the error message for the most recently invoked statement API function that can succeed or fail. An empty string ("") is returned if no error occurred. This means the following two tests are equivalent:

if (mysql_stmt_errno(stmt))
{
  // an error occurred
}
if (mysql_stmt_error(stmt)[0])
{
  // an error occurred
}

The language of the client error messages may be changed by recompiling the MySQL client library. Currently you can choose error messages in several different languages.

Return Values

A character string that describes the error. An empty string if no error occurred.

Errors

None.

Description

Return Values

Errors

Description

Returns the number of rows in the result set.

The use of mysql_stmt_num_rows() depends on whether or not you used mysql_stmt_store_result() to buffer the entire result set in the statement handle.

If you use mysql_stmt_store_result(), mysql_stmt_num_rows() may be called immediately.

Return Values

The number of rows in the result set.

Errors

None.

Description

Return Values

Errors

Description

Sets the row cursor to an arbitrary row in a statement result set. The offset value is a row offset that should be a value returned from mysql_stmt_row_tell() or from mysql_stmt_row_seek(). This value is not a row number; if you want to seek to a row within a result set by number, use mysql_stmt_data_seek() instead.

This function requires that the result set structure contains the entire result of the query, so mysql_stmt_row_seek() may be used only in conjunction with mysql_stmt_store_result().

Return Values

The previous value of the row cursor. This value may be passed to a subsequent call to mysql_stmt_row_seek().

Errors

None.

Description

Returns the current position of the row cursor for the last mysql_fetch(). This value can be used as an argument to mysql_stmt_row_seek().

You should use mysql_stmt_row_tell() only after mysql_stmt_store_result().

Return Values

The current offset of the row cursor.

Errors

None.

Description

For the statement specified by stmt, mysql_stmt_sqlstate() returns a null-terminated string containing the SQLSTATE error code for the most recently invoked prepared statement API function that can succeed or fail. The error code consists of five characters. "00000" means ``no error''. The values are specified by ANSI SQL and ODBC. For a list of possible values, see Error-returns.

Note that not all MySQL errors are yet mapped to SQLSTATE's. The value "HY000" (general error) is used for unmapped errors.

This function was added to MySQL 4.1.1.

Return Values

A null-terminated character string containing the SQLSTATE error code.

Description

You must call mysql_stmt_store_result() for every query that successfully produces a result set (SELECT, SHOW, DESCRIBE, EXPLAIN), and only if you want to buffer the complete result set by the client, so that the subsequent mysql_fetch() call returns buffered data.

It is unnecessary to call mysql_stmt_store_result() for other queries, but if you do, it will not harm or cause any notable performance in all cases. You can detect whether the query produced a result set by checking if mysql_get_metadata() returns NULL. For more information, refer to mysql_get_metadata().

Return Values

Zero if the results are buffered successfully. Non-zero if an error occurred.

Errors

CR_COMMANDS_OUT_OF_SYNC Commands were executed in an improper order.
CR_OUT_OF_MEMORY Out of memory.
CR_SERVER_GONE_ERROR The MySQL server has gone away.
CR_SERVER_LOST The connection to the server was lost during the query.
CR_UNKNOWN_ERROR An unknown error occurred.

mysql_bind_param()

my_bool mysql_bind_param(MYSQL_STMT *stmt, MYSQL_BIND *bind)

mysql_bind_result()

my_bool mysql_bind_result(MYSQL_STMT *stmt, MYSQL_BIND *bind)

mysql_execute()

int mysql_execute(MYSQL_STMT *stmt)

mysql_fetch()

int mysql_fetch(MYSQL_STMT *stmt)

mysql_fetch_column()

int mysql_fetch_column(MYSQL_STMT *stmt, MYSQL_BIND *bind, unsigned int column, unsigned long offset)

To be added.

mysql_get_metadata()

MYSQL_RES *mysql_get_metadata(MYSQL_STMT *stmt)

mysql_param_count()

unsigned long mysql_param_count(MYSQL_STMT *stmt)

mysql_param_result()

MYSQL_RES *mysql_param_result(MYSQL_STMT *stmt)

To be added.

mysql_prepare()

MYSQL_STMT * mysql_prepare(MYSQL *mysql, const char *query, unsigned long length)

mysql_send_long_data()

my_bool mysql_send_long_data(MYSQL_STMT *stmt, unsigned int parameter_number, const char *data, unsigned long length)

mysql_stmt_affected_rows()

my_ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)

mysql_stmt_close()

my_bool mysql_stmt_close(MYSQL_STMT *)

mysql_stmt_data_seek()

void mysql_stmt_data_seek(MYSQL_STMT *stmt, my_ulonglong offset)

mysql_stmt_errno()

unsigned int mysql_stmt_errno(MYSQL_STMT *stmt)

mysql_stmt_error()

const char *mysql_stmt_error(MYSQL_STMT *stmt)

mysql_stmt_free_result()

my_bool mysql_stmt_free_result(MYSQL_STMT *stmt)

To be added.

mysql_stmt_num_rows()

my_ulonglong mysql_stmt_num_rows(MYSQL_STMT *stmt)

mysql_stmt_reset()

my_bool mysql_stmt_reset(MYSQL_STMT *stmt)

To be added.

mysql_stmt_row_seek()

MYSQL_ROW_OFFSET mysql_stmt_row_seek(MYSQL_STMT *stmt, MYSQL_ROW_OFFSET offset)

mysql_stmt_row_tell()

MYSQL_ROW_OFFSET mysql_stmt_row_tell(MYSQL_STMT *stmt)

mysql_stmt_sqlstate()

const char *mysql_stmt_sqlstate(MYSQL_STMT *stmt)

mysql_stmt_store_result()

int mysql_stmt_store_result(MYSQL_STMT *stmt)