11.5 mysql_stmt_bind_result()

bool
mysql_stmt_bind_result(MYSQL_STMT *stmt,
                       MYSQL_BIND *bind)

Description

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

All columns must be bound to buffers prior to calling mysql_stmt_fetch(). bind is the address of an array of MYSQL_BIND structures. The client library expects the array to contain one element for each column of the result set. If you do not bind columns to MYSQL_BIND structures, mysql_stmt_fetch() simply ignores the data fetch. The buffers should be large enough to hold the data values, because the protocol does not 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_stmt_fetch() is called. Suppose that an application binds the columns in a result set and calls mysql_stmt_fetch(). The client/server protocol returns data in the bound buffers. Then suppose that the application binds the columns to a different set of buffers. The protocol places data into the newly bound buffers when the next call to mysql_stmt_fetch() occurs.

To bind a column, an application calls mysql_stmt_bind_result() and passes the type, address, and length of the output buffer into which the value should be stored. Chapter 9, C API Prepared Statement Data Structures, describes the members of each MYSQL_BIND element and how they should be set to receive output values.

Return Values

Zero for success. Nonzero if an error occurred.

Errors

• CR_UNSUPPORTED_PARAM_TYPE

  The conversion is not supported. Possibly the buffer_type value is invalid or is not one of the supported types.

• CR_OUT_OF_MEMORY

  Out of memory.

• CR_UNKNOWN_ERROR

  An unknown error occurred.

Example

See the Example in Section 11.11, “mysql_stmt_fetch()”.