MySQL 5.6 C API Developer Guide
MYSQL_RES * mysql_store_result(MYSQL *mysql)
After invoking mysql_query()
or mysql_real_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_query()
or
mysql_real_query()
by using a
loop that calls
mysql_next_result()
to
determine whether there are more results. For an example, see
Chapter 16, C API Multiple Statement Execution Support.
To determine whether a statement returns a result set, call
mysql_field_count()
. See
Section 7.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
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 21.1, “Why mysql_store_result() Sometimes Returns NULL After mysql_query() Returns Success”.
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.
mysql_store_result()
resets
mysql_error()
and
mysql_errno()
if it succeeds.
Commands were executed in an improper order.
Out of memory.
The MySQL server has gone away.
The connection to the server was lost during the query.
An unknown error occurred.