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
不明なエラーが発生しました。