MYSQL_RES *mysql_store_result(MYSQL *mysql)
Description
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 don't have to 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 on).
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
Section 22.9.13, “C API Support for Multiple Statement Execution”.
If you want to know whether a statement should return a result
set, you can use
mysql_field_count()
to check for
this. See Section 22.9.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 statement didn't return a result set (for
example, if it was 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 whether
mysql_error()
returns a nonempty
string, mysql_errno()
returns
nonzero, or 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.)
After you have called
mysql_store_result()
and gotten
back a result that isn't 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.
Return Values
A MYSQL_RES
result structure with the
results. NULL
(0) if an error occurred.
Errors
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.