mysql_use_result() retrieves a result set row by row.
Syntax
MYSQL_RES *
mysql_use_result(MYSQL *mysql)
Return values
A MYSQL_RES result structure. If an error occurs, NULL is returned.
Error messages
If mysql_use_result() is executed, it resets mysql_error() and mysql_errno().
CR_COMMANDS_OUT_OF_SYNC: Commands are executed in an incorrect order.CR_OUT_OF_MEMORY: The memory is insufficient.CR_SERVER_GONE_ERROR: The connection to the OBServer was interrupted.CR_SERVER_LOST: The connection to the server was lost during the query.CR_UNKNOWN_ERROR: An unknown error occurred.
Notes
After you call mysql_real_query() or mysql_query(), you must call mysql_store_result() or mysql_use_result() for each of the following statement that generates a result set: SELECT, SHOW, DESCRIBE, EXPLAIN, and CHECK TABLE. After you process the result set, you must call mysql_free_result().
mysql_use_result() can start a result set retrieval. However, it does not read the result set to the client like mysql_store_result() does. Instead, you must call mysql_fetch_row() to retrieve each row. In this way, query results are read directly from the server without being stored in temporary tables or local buffers. This is faster and less memory is used compared with mysql_store_result(). The client allocates memory only to the current row and communication buffers whose byte size is specified by max_allowed_packet.
If the client needs to perform lots of operations on each row or output each row to a screen on which the user can type ^S to stop scrolling, we recommend that you do not call mysql_use_result() to lock reads. It is because some server threads will be occupied and other threads will be prevented from updating tables that are used to obtain data.
When you use mysql_use_result(), you must execute mysql_fetch_row() until NULL is returned. Otherwise, the unobtained rows are returned as part of the result set for the next query. If you forget to perform the preceding operation, the C API returns the following error message: Commands out of sync; you can't run this command now!
You cannot use the results returned by mysql_use_result() in conjunction with mysql_data_seek(), mysql_row_seek(), mysql_row_tell(), mysql_num_rows(), or mysql_affected_rows(). In addition, you cannot initiate other queries before mysql_use_result() is executed.
After you process the result set, you must call mysql_free_result().