25.2.3.66. mysql_store_result()
MYSQL_RES *mysql_store_result(MYSQL *mysql)
Description
You must call mysql_store_result() or
mysql_use_result() for every query that
successfully retrieves data (SELECT,
SHOW, DESCRIBE,
EXPLAIN, CHECK TABLE,
and so forth).
You don't have to call mysql_store_result()
or mysql_use_result() for other queries,
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 if the query didn't have a result set by checking if
mysql_store_result() returns 0 (more about
this later on).
If you want to know whether the query should return a result
set, you can use mysql_field_count() to
check for this. See Section 25.2.3.22, “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 a null pointer
if the query didn't return a result set (if the query was, for
example, an INSERT statement).
mysql_store_result() also returns a null
pointer if reading of the result set failed. You can check
whether an error occurred by checking if
mysql_error() returns a non-empty string,
if mysql_errno() returns non-zero, or if
mysql_field_count() returns zero.
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.)
Once you have called mysql_store_result()
and got a result back that isn't a null pointer, you may 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.
You must call mysql_free_result() once you
are done with the result set.
See Section 25.2.13.1, “Why mysql_store_result() Sometimes Returns NULL After mysql_query() Returns Success”.
Return Values
A MYSQL_RES result structure with the
results. NULL if an error occurred.
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.
