21.8.9. C API Готовые Структуры данных Оператора

21.8.9.1. C API Готовые Коды Типа Оператора
21.8.9.2. C API Готовые Преобразования типов Оператора

Готовые операторы используют несколько структур данных:

Чтобы получить дескриптор оператора, передайте a MYSQL обработчик соединения к mysql_stmt_init(), который возвращает указатель на a MYSQL_STMT структура данных. Эта структура используется для дальнейших операций с оператором. Чтобы определить оператор, чтобы подготовиться, передайте MYSQL_STMT указатель и оператор представляют в виде строки к mysql_stmt_prepare().
Чтобы обеспечить входные параметры для готового оператора, установить MYSQL_BIND структуры и передают их к mysql_stmt_bind_param(). Чтобы получить выходные значения столбцов, установить MYSQL_BIND структуры и передают их к mysql_stmt_bind_result().
MYSQL_TIME структура используется, чтобы передать временные данные в обоих направлениях.

Следующее обсуждение описывает готовые типы данных оператора подробно. Для примеров, которые показывают, как использовать их, см. Раздел 21.8.11.10,"mysql_stmt_execute()" , и Раздел 21.8.11.11,"mysql_stmt_fetch()".

MYSQL_STMT

Эта структура является дескриптором для готового оператора. Дескриптор создается, вызывая mysql_stmt_init(), который возвращает указатель на a MYSQL_STMT. Дескриптор используется для всех последующих операций с оператором, пока Вы не закрываете это с mysql_stmt_close(), в которой точке дескриптор становится недопустимым.

MYSQL_STMT у структуры нет никаких элементов, предназначенных для использования приложения. Приложения не должны попытаться скопировать a MYSQL_STMT структура. Нет никакой гарантии, что такая копия будет применима.

Многократные дескрипторы оператора могут быть связаны с единственным соединением. Предел на числе дескрипторов зависит от доступных системных ресурсов.
MYSQL_BIND

Эта структура используется оба для ввода оператора (значения данных, отправленные серверу), и выводила (значения результата, возвращенные из сервера):
- Для ввода использовать MYSQL_BIND структуры с mysql_stmt_bind_param() связывать значения данных параметра с буферами для использования mysql_stmt_execute().
- Для вывода использовать MYSQL_BIND структуры с mysql_stmt_bind_result() связывать буферы со столбцами набора результатов, для использования в выборке строк с mysql_stmt_fetch().
Использовать a MYSQL_BIND структура, обнулите ее содержание, чтобы инициализировать это, затем установите ее элементы соответственно. Например, чтобы объявить и инициализировать массив три MYSQL_BIND структуры, используйте этот код:
```
MYSQL_BIND bind[3];memset(bind, 0, sizeof(bind));
```
MYSQL_BIND структура содержит следующие элементы для использования прикладными программами. Для нескольких из элементов способ использования зависит от того, используется ли структура для ввода или вывода.
- enum enum_field_types buffer_type
  
  Тип буфера. Этот элемент указывает на тип данных переменной языка C, связанной со столбцом параметра оператора или набора результатов. Для ввода, buffer_type указывает на тип переменной, содержащей значение, которое будет отправлено серверу. Для вывода это указывает на тип переменной, в которую должно быть сохранено значение, полученное от сервера. Для допустимого buffer_type значения, см. Раздел 21.8.9.1, "API C Готовые Коды Типа Оператора".
- void *buffer
  
  Указатель на буфер, который будет использоваться для передачи данных. Это - адрес переменной языка C.
  
  Для ввода, buffer указатель на переменную, в которой Вы храните значение данных для параметра оператора. Когда Вы вызываете mysql_stmt_execute(), Использование MySQL значение, сохраненное в переменной вместо соответствующего маркера параметра в операторе (определенный с ? в строке оператора).
  
  Для вывода, buffer указатель на переменную, в которой можно возвратить значение столбца набора результатов. Когда Вы вызываете mysql_stmt_fetch(), MySQL хранит значение столбца от текущей строки набора результатов в этой переменной. Можно получить доступ к значению, когда вызов возвращается.
  
  Чтобы минимизировать потребность в MySQL, чтобы выполнить преобразования типов между значениями языка C на стороне клиента и значениями SQL на стороне сервера, используйте переменные C, у которых есть типы, подобные таковым из соответствующих значений SQL:
  - Для типов числовых данных, buffer должен указать на переменную надлежащего числового типа C. Для целочисленных переменных (который может быть char для однобайтовых значений или целочисленного типа для больших значений), следует также указать, имеет ли переменная unsigned атрибут, устанавливая is_unsigned элемент, описанный позже.
  - Для символьных (недвоичных) и типов данных двоичных строк, buffer должен указать на символьный буфер.
  - Для даты и типов данных времени, buffer должен указать на a MYSQL_TIME структура.
  Для направляющих линий об отображении между типами C и типами SQL и примечаниями о преобразованиях типов, см. Раздел 21.8.9.1, "API C Готовые Коды Типа Оператора", и Раздел 21.8.9.2, "API C Готовые Преобразования типов Оператора".
- unsigned long buffer_length
  
  Фактический размер *buffer в байтах. Это указывает на максимальный объем данных, который может быть сохранен в буфере. Для символа и двоичного файла C данные, buffer_length значение определяет длину *buffer когда использующийся с mysql_stmt_bind_param() определить входные значения, или максимальное количество байтов выходных данных, которые могут быть выбраны в буфер когда использующийся с mysql_stmt_bind_result().
- unsigned long *length
  
  Указатель на unsigned long переменная, которая указывает на фактическое число байтов данных, хранивших в *buffer. length используется для символа или двоичного файла C данные.
  
  Для входной привязки данных параметра, набора *length указать на фактическую длину значения параметра, сохраненного в *buffer. Это используется mysql_stmt_execute().
  
  Для привязки выходного значения, наборов MySQL *length когда Вы вызываете mysql_stmt_fetch(). mysql_stmt_fetch() возвращаемое значение определяет, как интерпретировать длину:
  - Если возвращаемое значение 0, *length указывает на фактическую длину значения параметра.
  - Если возвращаемое значение MYSQL_DATA_TRUNCATED, *length указывает на неусеченную длину значения параметра. В этом случае, минимум *length и buffer_length указывает на фактическую длину значения.
  length игнорируется для числовых и временных типов данных потому что buffer_type значение определяет длину значения данных.
  
  Если следует определить длину возвращенного значения прежде, чем выбрать это, см. Раздел 21.8.11.11,"mysql_stmt_fetch()", для некоторых стратегий.
- my_bool *is_null
  
  Этот элемент указывает на a my_bool переменная, которая является истиной, если значение NULL, ложь, если это не NULL. Для ввода, набора *is_null к истине, чтобы указать, что Вы передаете a NULL оцените как параметр оператора.
  
  is_null указатель на булев скаляр, не булев скаляр, чтобы обеспечить гибкость в том, как Вы определяете NULL значения:
  - Если Ваши значения данных всегда NULL, использовать MYSQL_TYPE_NULL как buffer_type оцените, когда Вы связываете столбец. Другой MYSQL_BIND элементы, включая is_null, не иметь значения.
  - Если Ваши значения данных всегда NOT NULL, набор is_null = (my_bool*) 0, и набор другие элементы соответственно для переменной Вы связываете.
  - Во всех других случаях, набор другие элементы соответственно и набор is_null к адресу a my_bool переменная. Набор, что значение переменной к истине или лжи соответственно между выполнением, чтобы указать, является ли соответствующее значение данных NULL или NOT NULL, соответственно.
  Для вывода, когда Вы выбираете строку, MySQL устанавливает значение, которым указывают is_null к истине или лжи согласно тому, является ли значение столбца набора результатов, возвращенное из оператора, или не NULL.
- my_bool is_unsigned
  
  Этот элемент просит переменные C с типами данных, которые могут быть unsigned (char, short int, int, long long int). Набор is_unsigned к истине, если переменная, которой указывают buffer unsigned и ложь иначе. Например, если Вы связываете a signed char переменная к buffer, определите код типа MYSQL_TYPE_TINY и набор is_unsigned ко лжи. Если Вы связываете unsigned char вместо этого, код типа является тем же самым, но is_unsigned должна быть истина. (Для char, это не определяется, подписывается ли это или без знака, так лучше быть явным о signedness при использовании signed char или unsigned char.)
  
  is_unsigned применяется только к переменной языка C на стороне клиента. Это указывает, что ничто о signedness соответствующего SQL не оценивает стороной сервера. Например, если Вы используете int переменная, чтобы предоставить значение для a BIGINT UNSIGNED столбец, is_unsigned должна быть ложь потому что int подписанный тип. Если Вы используете unsigned int переменная, чтобы предоставить значение для a BIGINT столбец, is_unsigned должна быть истина потому что unsigned int тип без знака. MySQL выполняет надлежащее преобразование между подписанными и значениями без знака в обоих направлениях, хотя предупреждение происходит, если усечение заканчивается.
- my_bool *error
  
  Для вывода, набор этот элемент, чтобы указать на a my_bool переменная, чтобы иметь информацию об усечении для параметра, сохраненного там после работы выборки строки. Когда создание отчетов усечения включается, mysql_stmt_fetch() возвраты MYSQL_DATA_TRUNCATED и *error истина в MYSQL_BIND структуры для параметров, в которых произошло усечение. Усечение указывает на потерю знака или существенных цифр, или что строка была слишком длинной, чтобы поместиться в столбец. Создание отчетов усечения включается по умолчанию, но может управляться, вызывая mysql_options() с MYSQL_REPORT_DATA_TRUNCATION опция.

MYSQL_TIME

Эта структура используется, чтобы отправить и получить DATE, TIME, DATETIME, и TIMESTAMP данные непосредственно к и от сервера. Установите buffer элемент, чтобы указать на a MYSQL_TIME структура, и набор buffer_type элемент a MYSQL_BIND структура к одному из временных типов (MYSQL_TYPE_TIME, MYSQL_TYPE_DATE, MYSQL_TYPE_DATETIME, MYSQL_TYPE_TIMESTAMP).

MYSQL_TIME структура содержит элементы, перечисленные в следующей таблице.

Элемент	Описание
`unsigned int year`	Год
`unsigned int month`	Месяц года
`unsigned int day`	День месяца
`unsigned int hour`	Час дня
`unsigned int minute`	Минута часа
`unsigned int second`	Вторая из минуты
`my_bool neg`	Булев флаг, указывающий, отрицательно ли время
`unsigned long second_part`	Дробная часть второго в микросекундах

Только те части a MYSQL_TIME структура, которые применяются к данному типу временного значения, используется. year, month, и day элементы используются для DATE, DATETIME, и TIMESTAMP значения. hour, minute, и second элементы используются для TIME, DATETIME, и TIMESTAMP значения. См. Раздел 21.8.19, "API C Готовая Обработка Оператора Даты и Временных стоимостей".