5.4.84 mysql_store_result()

MYSQL_RES *
mysql_store_result(MYSQL *mysql)

Description

Note

mysql_store_result() is a synchronous function. Its asynchronous counterpart is mysql_store_result_nonblocking(), for use by applications that require asynchronous communication with the server. See Chapter 7, C API Asynchronous Interface.

After invoking mysql_real_query() or mysql_query(), you must call mysql_store_result() or mysql_use_result() for every statement that successfully produces a result set (SELECT, SHOW, DESCRIBE, EXPLAIN, CHECK TABLE, and so forth). You must also call mysql_free_result() after you are done with the result set.

You need not call mysql_store_result() or mysql_use_result() for other statements, but it does not do any harm or cause any notable performance degradation if you call mysql_store_result() in all cases. You can detect whether the statement has a result set by checking whether mysql_store_result() returns a nonzero value (more about this later).

If you enable multiple-statement support, you should retrieve results from calls to mysql_real_query() or mysql_query() by using a loop that calls mysql_next_result() to determine whether there are more results. For an example, see Section 3.6.3, “Multiple Statement Execution Support”.

To determine whether a statement returns a result set, call mysql_field_count(). See Section 5.4.23, “mysql_field_count()”.

mysql_store_result() reads the entire result of a query to the client, allocates a MYSQL_RES structure, and places the result into this structure.

mysql_store_result() returns NULL if the statement did not return a result set (for example, if it was an INSERT statement), or an error occurred and reading of the result set failed.

An empty result set is returned if there are no rows returned. (An empty result set differs from a null pointer as a return value.)

After you have called mysql_store_result() and gotten back a result that is not a null pointer, you can call mysql_num_rows() to find out how many rows are in the result set.

You can call mysql_fetch_row() to fetch rows from the result set, or mysql_row_seek() and mysql_row_tell() to obtain or set the current row position within the result set.

See Section 3.6.9, “NULL mysql_store_result() Return After mysql_query() Success”.

Return Values

A pointer to a MYSQL_RES result structure with the results. NULL if the statement did not return a result set or an error occurred. To determine whether an error occurred, check whether mysql_error() returns a nonempty string, mysql_errno() returns nonzero, or mysql_field_count() returns zero.

Errors

mysql_store_result() resets mysql_error() and mysql_errno() if it succeeds.

• 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.