MySQL :: MySQL 8.4 C API Developer Guide :: 5.4.86 mysql_use_result() (original) (raw)

5.4.86 mysql_use_result()

MYSQL_RES *
mysql_use_result(MYSQL *mysql)

Description

After invokingmysql_real_query() ormysql_query(), you must callmysql_store_result() ormysql_use_result() for every statement that successfully produces a result set (SELECT,SHOW,DESCRIBE,EXPLAIN,CHECK TABLE, and so forth). You must also callmysql_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 likemysql_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 thanmysql_store_result(). The client allocates memory only for the current row and a communication buffer that may grow up tomax_allowed_packet bytes.

On the other hand, you should not usemysql_use_result() for locking reads 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 executemysql_fetch_row() until aNULL 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 usemysql_data_seek(),mysql_row_seek(),mysql_row_tell(),mysql_num_rows(), ormysql_affected_rows() with a result returned frommysql_use_result(), nor may you issue other queries untilmysql_use_result() has finished. (However, after you have fetched all the rows,mysql_num_rows() accurately returns the number of rows fetched.)

You must callmysql_free_result() once you are done with the result set.

Return Values

A MYSQL_RES result structure.NULL if an error occurred.