25.2.3.68. mysql_use_result()
MYSQL_RES *mysql_use_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).
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.
-
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.
