23.8.7.72 mysql_use_result()

MYSQL_RES *mysql_use_result(MYSQL *mysql)

説明

mysql_query() または mysql_real_query() を呼び出したあとに、結果セットを正常に生成するすべてのステートメント (SELECT、SHOW、DESCRIBE、EXPLAIN、CHECK TABLE など) に対して、mysql_store_result() または mysql_use_result() を呼び出す必要があります。結果セットの処理を終了したら、mysql_free_result() も呼び出す必要があります。

mysql_use_result() は結果セットの取得を開始しますが、mysql_store_result() のように、実際に結果セットをクライアントに読み込みません。代わりに、mysql_fetch_row() への呼び出しを行うことによって、各行を個別に取得する必要があります。これは、クエリーの結果を一時テーブルやローカルバッファーに保存することなく、サーバーから直接読み取ります。これは、mysql_store_result() よりいくぶん高速で、使用するメモリーがはるかに少なくなります。クライアントは現在の行と max_allowed_packet バイトまで拡大する可能性のある通信バッファーにのみメモリーを割り当てます。

一方、クライアント側で、各行について大量の処理を行う場合またはユーザーが ^S (スクロール停止) を入力する可能性のある画面に出力が送信される場合は、mysql_use_result() を使用しないでください。これはサーバーを拘束し、ほかのスレッドが、データのフェッチ元のテーブルを更新するのを妨げます。

mysql_use_result() を使う場合は、NULL 値が返されるまで mysql_fetch_row() を実行する必要があり、そうしないと、次のクエリーの結果セットの一部として、フェッチされていない行が返されます。この実行を忘れると、C API によって、エラー「コマンドは同期されていません。このコマンドは現在実行できません」が生成されます。

mysql_data_seek()、mysql_row_seek()、mysql_row_tell()、mysql_num_rows()、または mysql_affected_rows() を mysql_use_result() から返される結果と一緒に使用できません。また、mysql_use_result() が終了するまで、ほかのクエリーを発行することもできません。(ただし、すべての行をフェッチしたあとに、mysql_num_rows() はフェッチした行数を正確に返します。)

結果セットの処理を終了したら、mysql_free_result() を呼び出す必要があります。

libmysqld 組み込みサーバーを使用する場合、mysql_free_result() が呼び出されるまで、取得される各行によって、メモリーの使用量が徐々に増加するため、メモリーのメリットが本質的に失われます。

戻り値

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

エラー

mysql_use_result() は成功すると、mysql_error() と mysql_errno() をリセットします。

• CR_COMMANDS_OUT_OF_SYNC

  コマンドが正しくない順番で実行されました。

• CR_OUT_OF_MEMORY

  メモリー不足。

• CR_SERVER_GONE_ERROR

  MySQL サーバーが存在しなくなりました。

• CR_SERVER_LOST

  サーバーへの接続がクエリー中に失われました。

• CR_UNKNOWN_ERROR

  不明なエラーが発生しました。