20.4.50 mysql_use_result()
MYSQL_RES *mysql_use_result(MYSQL *mysql)
20.4.50.1 Description
You must call mysql_store_result() or mysql_use_result() for
every query which 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 will only allocate memory 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 will tie up the server and prevent other threads from updating any
tables from which the data are fetched.
When using mysql_use_result(), you must execute
mysql_fetch_row() until a NULL value is returned, otherwise the
unfetched rows will be returned as part of the result set for your next
query. The C API will give 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 requêtesuntil the
mysql_use_result() has finished. (However, after you have fetched all
the rows, mysql_num_rows() will accurately return the number of rows
fetched.)
You must call mysql_free_result() once you are done with the result
set.
20.4.50.2 Return values
A MYSQL_RES result structure. NULL if an error occurred.
20.4.50.3 Errors
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.
