Справочное руководство по MySQL
mysql_use_result()
MYSQL_RES *mysql_use_result(MYSQL *mysql)
8.4.3.218 Описание
Функцию mysql_store_result() или mysql_use_result() необходимо вызывать после каждого выполненного запроса, извлекающего данные (SELECT, SHOW, DESCRIBE, EXPLAIN).
Функция mysql_use_result() инициализирует извлечение результирующего набора, но фактически не производит чтение в клиенте подобно тому, как это делает функция mysql_store_result(). Вместо этого каждая строка должна извлекаться индивидуально посредством вызова функции mysql_fetch_row(). При этом методе результат запроса читается непосредственно на сервере без промежуточного хранения его во временной таблице или локальном буфере, что быстрее и требует намного меньше памяти, чем использование функции mysql_store_result(). Клиент будет выделять память только для текущей строки и буфер связи может расти до величины max_allowed_packet байтов.
С другой стороны, функцию mysql_use_result() нельзя использовать, если выполняется много операций по обработке каждой строки на клиентской стороне, или если вывод делается на терминал, на котором пользователь может нажать ^S (остановить вывод).
Это будет ограничивать работу сервера и будет мешать другим потокам в обновлении таблиц, из которых выбираются данные.
При использовании mysql_use_result() необходимо выполнять mysql_fetch_row(), пока не возвратится величина NULL, в противном случае невыбранные строки данного запроса будут возвращены как часть результирующего набора для следующего запроса. Если вы забыли сделать это, то интерфейс C будет выдавать ошибку Commands out of sync; you can't run this command now!
Нельзя использовать функции 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() сразу же после окончания действий с результирующим набором.
8.4.3.219 Возвращаемые значения
Результирующая структура MYSQL_RES с результатами. NULL, если произошла ошибка.
8.4.3.220 Ошибки
- CR_COMMANDS_OUT_OF_SYNC
- Команды были выполнены в ненадлежащем порядке.
- CR_OUT_OF_MEMORY
- Нехватка памяти.
- CR_SERVER_GONE_ERROR
- Сервер MySQL неожиданно завершил работу.
- CR_SERVER_LOST
- Соединение с сервером прервалось в процессе данного запроса.
- CR_UNKNOWN_ERROR
- Произошла неизвестная ошибка.
