mysql_stmt_fetch()

You can call the mysql_stmt_fetch() function to fetch the next row in a result set and return data of all bound columns.

Syntax

int
mysql_stmt_fetch(MYSQL_STMT *stmt)

Return values

MYSQL_DATA_TRUNCATED is returned when truncation reporting is enabled. To determine which column values were truncated when this value is returned, check whether the MYSQL_BIND structures used for fetching values contain error members. Truncation reporting is enabled by default, but can be controlled by calling mysql_options() with the MYSQL_REPORT_DATA_TRUNCATION option.

Errors

• CR_COMMANDS_OUT_OF_SYNC: Commands were executed in an improper order.

  Although mysql_stmt_fetch() can produce this error, it is more likely to occur in the following C API call if mysql_stmt_fetch() is not called enough times to read the entire result set (that is, enough times to return MYSQL_NO_DATA).

• CR_OUT_OF_MEMORY: The memory is insufficient.

• CR_SERVER_GONE_ERROR: The connection to the OBServer was disconnected.

• 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 data type is not DATE, TIME, DATETIME, or TIMESTAMP.

All other unsupported conversion errors are returned by mysql_stmt_bind_result().

Notes

mysql_stmt_fetch() can be called only when the result set exists, that is, after a call to mysql_stmt_execute() for a statement such as SELECT that produces a result set.

mysql_stmt_fetch() returns row data by using the buffers bound by mysql_stmt_bind_result(). It returns the data in the buffers for all the columns in the current row set and returns the lengths to the length pointer. All columns must be bound by the application before it calls mysql_stmt_fetch().

mysql_stmt_fetch() typically occurs within a loop, to ensure that all result set rows are fetched. Sample statement:

int status;

while (1)
{
  status = mysql_stmt_fetch(stmt);

  if (status == 1  status == MYSQL_NO_DATA)
    break;

  /* Handle the current row. */
}

/* If required, display the error here when handler status == 1. */

By default, result sets are fetched row by row in an unbuffered manner from the server. To buffer the entire result set on the client, call mysql_stmt_store_result() after binding the data buffers and before calling mysql_stmt_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. The length of the string types depends on the length of the actual data value, as indicated by data_length.

In some cases, you might want to determine the length of a column value before fetching it by using mysql_stmt_fetch(). Use one of the following strategies:

• Before you call mysql_stmt_fetch() to retrieve individual rows, pass STMT_ATTR_UPDATE_MAX_LENGTH to mysql_stmt_attr_set(), and then call mysql_stmt_store_result() to buffer the entire result on the client. Setting the STMT_ATTR_UPDATE_MAX_LENGTH attribute causes the maximal length of column values to be indicated by the max_length member of the result set metadata returned by mysql_stmt_result_metadata().

• Call mysql_stmt_fetch() by using a zero-length buffer for the column and a pointer in which the real length can be stored. Then use the real length with mysql_stmt_fetch_column().