MYSQL_RES *mysql_use_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.
mysql_use_result()
initiates a
result set retrieval but does not actually read the result set
into the client like
mysql_store_result()
does.
Instead, each row must be retrieved individually by making calls
to mysql_fetch_row()
. This reads
the result of a query directly from the server without storing
it in a temporary table or local buffer, which is somewhat
faster and uses much less memory than
mysql_store_result()
. The client
allocates memory only for the current row and a communication
buffer that may grow up to
max_allowed_packet
bytes.
On the other hand, you shouldn't use
mysql_use_result()
if you are
doing a lot of processing for each row on the client side, or if
the output is sent to a screen on which the user may type a
^S
(stop scroll). This ties up the server and
prevent other threads from updating any tables from which the
data is being fetched.
When using mysql_use_result()
,
you must execute
mysql_fetch_row()
until a
NULL
value is returned, otherwise, the
unfetched rows are returned as part of the result set for your
next query. The C API gives the error Commands out of
sync; you can't run this command now
if you forget to
do this!
You may not use
mysql_data_seek()
,
mysql_row_seek()
,
mysql_row_tell()
,
mysql_num_rows()
, or
mysql_affected_rows()
with a
result returned from
mysql_use_result()
, nor may you
issue other queries until
mysql_use_result()
has finished.
(However, after you have fetched all the rows,
mysql_num_rows()
accurately
returns the number of rows fetched.)
You must call
mysql_free_result()
once you are
done with the result set.
When using the libmysqld
embedded server, the
memory benefits are essentially lost because memory usage
incrementally increases with each row retrieved until
mysql_free_result()
is called.
Return Values
A MYSQL_RES
result structure.
NULL
if an error occurred.
Errors
mysql_use_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.
User Comments
Add your own comment.