MYSQL_RES *mysql_use_result(MYSQL *mysql)

説明

正常にデータを取得したクエリ（SELECT、SHOW、DESCRIBE、EXPLAIN）については、mysql_store_result() または mysql_use_result() を呼び出す必要があります。

mysql_use_result() は、結果セットの取得を開始しますが、mysql_store_result() のように実際に結果セットをクライアントに読み込むわけではありません。代わりに、mysql_fetch_row() を呼び出して、1 行ずつ個別に取得する必要があります。その場合、クエリの結果は直接サーバから読み込まれ、テンポラリテーブルやローカルバッファには格納されません。これは mysql_store_result() を使用する場合よりも多少高速であり、使用するメモリも少なくてすみます。クライアントは、カレントレコードおよび max_allowed_packet バイトまで増える可能性のある通信バッファにメモリを割り当てるだけです。

一方、それぞれのレコードに対するクライアント側での処理量が多い場合、またはユーザが ^S を入力する（スクロールを停止する）可能性がある画面にデータを出力する場合は、mysql_use_result() の使用は避ける必要があります。そのような処理の場合、サーバの動作が停止して、読み取られているデータが格納されているテーブルを他のスレッドが更新できなくなります。

mysql_use_result() を使用する場合、NULL が返されるまで mysql_fetch_row() を繰り返し呼び出す必要があります。そうしないと、取得されなかったレコードが、次に実行するクエリの結果セットの一部として返されます。取得されなかったレコードが残っている場合、C API はエラー Commands out of sync; you can't run this command now を返します。

mysql_use_result() が返した結果セットに対して mysql_data_seek()、mysql_row_seek()、mysql_row_tell()、mysql_num_rows()、または mysql_affected_rows() を使用することはできません。また、mysql_use_result() が完了するまでは他のクエリを発行できません（ただし、すべてのレコードを取得した後であれば mysql_num_rows() は取得したレコードの数を正確に返します）。

結果セットが必要なくなったら、mysql_free_result() を呼び出す必要があります。

戻り値

MYSQL_RES 構造体。エラーが発生した場合は NULL。

エラー

mysql_use_result() は、正常終了した場合に mysql_error および mysql_errno をリセットします。