21.8.5. C Структуры данных API

Этот раздел описывает структуры данных API C кроме используемых для готовых операторов. Для получения информации о последнем см. Раздел 21.8.9, "API C Готовые Структуры данных Оператора".

MYSQL

Эта структура представляет дескриптор одному соединению с базой данных. Это используется для почти всех функций MySQL. Не пытайтесь сделать копию a MYSQL структура. Нет никакой гарантии, что такая копия будет применима.
MYSQL_RES

Эта структура представляет результат запроса, который возвращает строки (SELECT, SHOW, DESCRIBE, EXPLAIN). Информацию, возвращенную из запроса, вызывают набором результатов в остатке от этого раздела.
MYSQL_ROW

Это - безопасное с точки зрения типов представление одной строки данных. Это в настоящий момент реализуется как массив считаемых строк байтов. (Невозможно обработать их как завершенные нулем строки, если значения полей могут содержать двоичных данных, потому что такие значения могут содержать нулевые байты внутренне.) Строки получаются, вызывая mysql_fetch_row().
MYSQL_FIELD

Эта структура содержит метаданные: информация о поле, таком как имя поля, вводит, и размер. Его элементы описываются более подробно позже в этом разделе. Можно получить MYSQL_FIELD структуры для каждого поля, вызывая mysql_fetch_field() неоднократно. Значения полей не являются частью этой структуры; они содержатся в a MYSQL_ROW структура.
MYSQL_FIELD_OFFSET

Это - безопасное с точки зрения типов представление смещения в cписок полей MySQL. (Используемый mysql_field_seek().) Смещения являются полевыми числами в строке, начинающейся в нуле.
my_ulonglong

Тип, используемый для числа строк и для mysql_affected_rows(), mysql_num_rows(), и mysql_insert_id(). Этот тип обеспечивает диапазон 0 к 1.84e19.

На некоторых системах, пытаясь напечатать значение типа my_ulonglong не работает. Чтобы напечатать такое значение, преобразуйте это в unsigned long и используйте a %lu формат печати. Пример:
```
printf ("Number of rows: %lu\n",        (unsigned long) mysql_num_rows(result));
```
my_bool

Булев тип, для значений, которые являются истиной (ненулевой) или ложной (нуль).

MYSQL_FIELD структура содержит элементы, описанные в следующем списке. Определения применяются прежде всего для столбцов наборов результатов, таких как произведенные SELECT операторы. В MySQL 5.7, MYSQL_FIELD структуры также используются, чтобы обеспечить метаданные для OUT и INOUT параметры, возвращенные из хранимых процедур, выполняемых, используя подготовленный CALL операторы. Для таких параметров у некоторых из элементов структуры есть значение, отличающееся от значения для значений столбцов.

char * name

Имя поля, как завершенная нулем строка. Если полю дали псевдоним с AS пункт, значение name псевдоним. Для параметра процедуры, названия параметра.
char * org_name

Имя поля, как завершенная нулем строка. Псевдонимы игнорируются. Для выражений значение является пустой строкой. Для параметра процедуры, названия параметра.
char * table

Имя таблицы, содержащей это поле, если это не вычисляемое поле. Для вычисляемых полей, table значение является пустой строкой. Если столбец выбирается из представления, table называет представление. Если таблице или представлению дали псевдоним с AS пункт, значение table псевдоним. Для a UNION, значение является пустой строкой. Для параметра процедуры, имени процедуры.
char * org_table

Имя таблицы, как завершенная нулем строка. Псевдонимы игнорируются. Если столбец выбирается из представления, org_table называет представление. Для a UNION, значение является пустой строкой. Для параметра процедуры, имени процедуры.
char * db

Имя базы данных, что поле прибывает из как завершенная нулем строка. Если поле является вычисляемым полем, db пустая строка. Для a UNION, значение является пустой строкой. Для параметра процедуры, имени базы данных, содержащей процедуру.
char * catalog

Имя каталога. Это значение всегда "def".
char * def

Значение по умолчанию этого поля, как завершенная нулем строка. Это устанавливается, только если Вы используете mysql_list_fields().
unsigned long length

width поля. Это соответствует длине дисплея в байтах.

Сервер определяет length значение прежде, чем это генерирует набор результатов, таким образом, это - минимальная длина, требуемая для типа данных, способного к содержанию самого большого значения от столбца результата, не зная заранее фактические значения, которые будут произведены запросом для набора результатов.
unsigned long max_length

Максимальный width поля для набора результатов (длина в байтах самого долгого значения поля для строк фактически в наборе результатов). Если Вы используете mysql_store_result() или mysql_list_fields(), это содержит максимальную длину для поля. Если Вы используете mysql_use_result(), значение этой переменной является нулем.

Значение max_length продолжительность строкового представления значений в наборе результатов. Например, если Вы получаете a FLOAT столбец и "самое широкое" значение -12.345, max_length 7 (длина '-12.345').

Если Вы используете подготовленные операторы, max_length не устанавливается по умолчанию, потому что для протокола двоичной синхронной передачи данных длины значений зависят от типов значений в наборе результатов. (См. Раздел 21.8.9, "API C Готовые Структуры данных Оператора".), Если Вы хотите max_length значения так или иначе, включите STMT_ATTR_UPDATE_MAX_LENGTH опция с mysql_stmt_attr_set() и длины будут установлены, когда Вы вызовете mysql_stmt_store_result(). (См. Раздел 21.8.11.3,"mysql_stmt_attr_set()" , и Раздел 21.8.11.28,"mysql_stmt_store_result()".)
unsigned int name_length

Длина name.
unsigned int org_name_length

Длина org_name.
unsigned int table_length

Длина table.
unsigned int org_table_length

Длина org_table.
unsigned int db_length

Длина db.
unsigned int catalog_length

Длина catalog.
unsigned int def_length

Длина def.

unsigned int flags

Битовые флаги, которые описывают поле. flags у значения могут быть нуль или больше набора битов, которые показывают в следующей таблице.

Флаговое значение	Описание флага
`NOT_NULL_FLAG`	Поле не может быть `NULL`
`PRI_KEY_FLAG`	Поле является частью первичного ключа
`UNIQUE_KEY_FLAG`	Поле является частью уникального ключа
`MULTIPLE_KEY_FLAG`	Поле является частью группового ключа
`UNSIGNED_FLAG`	Поле имеет `UNSIGNED` атрибут
`ZEROFILL_FLAG`	Поле имеет `ZEROFILL` атрибут
`BINARY_FLAG`	Поле имеет `BINARY` атрибут
`AUTO_INCREMENT_FLAG`	Поле имеет `AUTO_INCREMENT` атрибут
`ENUM_FLAG`	Поле `ENUM`
`SET_FLAG`	Поле является a `SET`
`BLOB_FLAG`	Поле является a `BLOB` или`TEXT` (осуждаемый)
`TIMESTAMP_FLAG`	Поле является a `TIMESTAMP` (осуждаемый)
`NUM_FLAG`	Поле является числовым; см., что дополнительные примечания следуют за таблицей
`NO_DEFAULT_VALUE_FLAG`	У поля нет никакого значения по умолчанию; см., что дополнительные примечания следуют за таблицей

Некоторые из этих флагов указывают на информацию о типе данных и заменяются или используются в соединении с MYSQL_TYPE_xxx значение в field->type элемент, описанный позже:

Проверять на BLOB или TIMESTAMP значения, проверьте ли type MYSQL_TYPE_BLOB или MYSQL_TYPE_TIMESTAMP. ( BLOB_FLAG и TIMESTAMP_FLAG флаги являются ненужными.)
ENUM и SET значения возвращаются как строки. Для них проверьте что type значение MYSQL_TYPE_STRING и что ENUM_FLAG или SET_FLAG флаг устанавливается в flags значение.

NUM_FLAG указывает, что столбец является числовым. Это включает столбцы с типом MYSQL_TYPE_DECIMAL, MYSQL_TYPE_NEWDECIMAL, MYSQL_TYPE_TINY, MYSQL_TYPE_SHORT, MYSQL_TYPE_LONG, MYSQL_TYPE_FLOAT, MYSQL_TYPE_DOUBLE, MYSQL_TYPE_NULL, MYSQL_TYPE_LONGLONG, MYSQL_TYPE_INT24, и MYSQL_TYPE_YEAR.

NO_DEFAULT_VALUE_FLAG указывает, что столбец имеет нет DEFAULT пункт в его определении. Это не применяется к NULL столбцы (потому что у таких столбцов есть значение по умолчанию NULL), или к AUTO_INCREMENT столбцы (у которых есть подразумеваемое значение по умолчанию).

Следующий пример иллюстрирует типичное использование flags значение:

if (field->flags & NOT_NULL_FLAG)    printf("Field can't be null\n");

Можно использовать макросы удобства, которые, как показывают в следующей таблице, определили булево состояние flags значение.

Состояние флага	Описание
`IS_NOT_NULL(flags)`	Истина, если это поле определяется как `NOT NULL`
`IS_PRI_KEY(flags)`	Истина, если это поле является первичным ключом
`IS_BLOB(flags)`	Истина, если это поле является a `BLOB` или `TEXT` (осуждаемый; тест`field->type` вместо этого)

unsigned int decimals

Число десятичных чисел для числовых полей, и точности долей секунды для временных полей.
unsigned int charsetnr

Идентификационный номер, который указывает на набор символов / пара сопоставления для поля.

Чтобы различить двоичный файл и недвоичных данных для строковых типов данных, проверьте ли charsetnr значение 63. Если так, набор символов binary, который указывает на двоичный файл, а не недвоичных данных. Это позволяет Вам различить BINARY от CHAR, VARBINARY от VARCHAR, и BLOB типы от TEXT типы.

charsetnr значения являются тем же самым как выведенными на экран в Id столбец SHOW COLLATION оператор или ID столбец INFORMATION_SCHEMA COLLATIONS таблица. Можно использовать те источники информации, чтобы видеть который набор символов и определенное сопоставление charsetnr значения указывают:
```
mysql> SHOW COLLATION WHERE Id =
                    63;+-----------+---------+----+---------+----------+---------+| Collation | Charset | Id | Default | Compiled | Sortlen |+-----------+---------+----+---------+----------+---------+| binary    | binary  | 63 | Yes     | Yes      |       1 |+-----------+---------+----+---------+----------+---------+mysql> SELECT COLLATION_NAME,
                    CHARACTER_SET_NAME    -> FROM
                    INFORMATION_SCHEMA.COLLATIONS WHERE ID = 33;+-----------------+--------------------+| COLLATION_NAME  | CHARACTER_SET_NAME |+-----------------+--------------------+| utf8_general_ci | utf8               |+-----------------+--------------------+
```

enum enum_field_types type

Тип поля. type значение может быть одним из MYSQL_TYPE_ символы, показанные в следующей таблице.

Введите Значение	Введите Описание
`MYSQL_TYPE_TINY`	`TINYINT` поле
`MYSQL_TYPE_SHORT`	`SMALLINT` поле
`MYSQL_TYPE_LONG`	`INTEGER` поле
`MYSQL_TYPE_INT24`	`MEDIUMINT` поле
`MYSQL_TYPE_LONGLONG`	`BIGINT` поле
`MYSQL_TYPE_DECIMAL`	`DECIMAL` или `NUMERIC` поле
`MYSQL_TYPE_NEWDECIMAL`	Математика точности `DECIMAL` или `NUMERIC`
`MYSQL_TYPE_FLOAT`	`FLOAT` поле
`MYSQL_TYPE_DOUBLE`	`DOUBLE` или `REAL` поле
`MYSQL_TYPE_BIT`	`BIT` поле
`MYSQL_TYPE_TIMESTAMP`	`TIMESTAMP` поле
`MYSQL_TYPE_DATE`	`DATE` поле
`MYSQL_TYPE_TIME`	`TIME` поле
`MYSQL_TYPE_DATETIME`	`DATETIME` поле
`MYSQL_TYPE_YEAR`	`YEAR` поле
`MYSQL_TYPE_STRING`	`CHAR` или `BINARY` поле
`MYSQL_TYPE_VAR_STRING`	`VARCHAR` или `VARBINARY` поле
`MYSQL_TYPE_BLOB`	`BLOB` или `TEXT` поле (использование `max_length` определить maximumlength)
`MYSQL_TYPE_SET`	`SET` поле
`MYSQL_TYPE_ENUM`	`ENUM` поле
`MYSQL_TYPE_GEOMETRY`	Пространственное поле
`MYSQL_TYPE_NULL`	`NULL`- вводят поле

MYSQL_TYPE_TIME2, MYSQL_TYPE_DATETIME2, и MYSQL_TYPE_TIMESTAMP2) коды типа используются только на стороне сервера. Клиенты видят MYSQL_TYPE_TIME, MYSQL_TYPE_DATETIME, и MYSQL_TYPE_TIMESTAMP коды.

Можно использовать IS_NUM() макрос, чтобы протестировать, есть ли у поля числовой тип. Передайте type значение к IS_NUM() и это оценивает к ИСТИНЕ, если поле является числовым:

if (IS_NUM(field->type))    printf("Field is numeric\n");

ENUM и SET значения возвращаются как строки. Для них проверьте что type значение MYSQL_TYPE_STRING и что ENUM_FLAG или SET_FLAG флаг устанавливается в flags значение.