6.1 Overview of the C API Prepared Statement Interface — MySQL Connectors 1.0

6.1 Обзор интерфейса подготовленных запросов C API

Для подготовки и выполнения запроса приложение выполняет следующие шаги:

Создайте обработчик подготовленного запроса с помощью mysql_stmt_init(). Для подготовки запроса на сервере вызовите mysql_stmt_prepare() и передайте строку с SQL-запросом.
Установите значения параметров, используя mysql_stmt_bind_param(). Все параметры должны быть установлены. В противном случае выполнение запроса вернёт ошибку или даст неожиданные результаты.

Если есть большие значения текстовых или двоичных данных, которые необходимо отправить, вы можете отправлять их частями на сервер, используя mysql_stmt_send_long_data().
Вызовите mysql_stmt_execute() для выполнения запроса.
Если запрос является запросом, возвращающим набор результатов, или любым другим запросом, который генерирует набор результатов, вызовите mysql_stmt_result_metadata(), если нужно получить метаданные набора результатов. Эти метаданные сами представляют собой набор результатов MYSQL_RES, хотя и отдельный от набора строк, возвращаемых запросом. Набор метаданных указывает количество столбцов в результате и содержит информацию о каждом из них.
Если запрос генерирует набор результатов, свяжите буферы данных для получения значений строк, вызвав mysql_stmt_bind_result().
Вычитывайте данные в буферы строка за строкой, вызывая mysql_stmt_fetch() повторно до тех пор, пока не будут найдены все строки.
Повторите шаги 3-6 по необходимости. Вы можете повторить mysql_stmt_execute() для повторного выполнения запроса, изменив значения параметров в соответствующих буферах, предоставленных через mysql_stmt_bind_param().
Когда выполнение запроса завершено, закройте обработчик запроса, используя mysql_stmt_close(), чтобы все связанные с ним ресурсы были освобождены. В этот момент обработчик становится недействительным и больше не должен использоваться.
Если вы получили метаданные набора результатов запроса, вызвав mysql_stmt_result_metadata(), вы также должны освободить метаданные, используя mysql_free_result().

При вызове mysql_stmt_prepare() протокол MySQL клиент/сервер выполняет следующие действия:

Сервер парсит запрос и отправляет клиенту статус подтверждения, назначив идентификатор запроса. Также он отправляет общее количество параметров, количество столбцов и метаданные, если это ориентированный на набор результатов запрос. Все синтаксические и семантические аспекты запроса проверяются сервером во время этого вызова.
Клиент использует этот идентификатор запроса для дальнейших операций, чтобы сервер мог идентифицировать запрос среди своего пула запросов.

При вызове mysql_stmt_execute() протокол MySQL клиент/сервер выполняет следующие действия:

Клиент использует обработчик запроса и отправляет данные параметров на сервер.
Сервер идентифицирует запрос с помощью предоставленного клиентом идентификатора, заменяет маркеры параметров новыми данными и выполняет запрос. Если запрос генерирует набор результатов, сервер возвращает данные клиенту. В противном случае он отправляет статус подтверждения и количество изменённых, удалённых или вставленных строк.

При вызове mysql_stmt_fetch() протокол MySQL клиент/сервер выполняет следующие действия:

Клиент считывает данные из текущей строки набора результатов и помещает их в буферы данных приложения, выполнив необходимые преобразования. Если тип буфера приложения совпадает с типом поля, возвращённым сервером, преобразования выполняется непосредственно.

Если произошла ошибка, вы можете получить номер ошибки запроса, сообщение об ошибке и код SQLSTATE, используя mysql_stmt_errno(), mysql_stmt_error() и mysql_stmt_sqlstate() соответственно.

Ведение журнала подготовленных запросов

Для подготовленных запросов, выполняемых с помощью функций C API mysql_stmt_prepare() и mysql_stmt_execute(), сервер записывает строки Prepare и Execute в общий журнал запросов, чтобы вы могли отследить подготовку и выполнение запросов.

Предположим, что вы готовите и выполняете запрос следующим образом:

Вызовите mysql_stmt_prepare() для подготовки строки запроса "SELECT ?".
Вызовите mysql_stmt_bind_param() для привязки значения 3 к параметру в подготовленном запросе.
Вызовите mysql_stmt_execute() для выполнения подготовленного запроса.

В результате предыдущих вызовов сервер запишет в общий журнал запросов следующие строки:

Prepare  [1] SELECT ?
Execute  [1] SELECT 3

Каждая строка Prepare и Execute в журнале помечена идентификатором подготовленного запроса [N], чтобы вы могли отслеживать, какой подготовленный запрос регистрируется. N — целое положительное число. Если для клиента одновременно активны несколько подготовленных запросов, N может быть больше 1. Каждая строка Execute отображает подготовленный запрос после подстановки значений данных для параметров ?.