2 MySQL C API

Код C API распространяется в комплекте с MySQL. Он включен в библиотеку mysqlclient и позволяет программам на C обращаться к базе данных.

Многие клиенты в дистрибутиве исходного кода MySQL написаны на C. Если Вы ищете примеры, которые показывают, как использовать C API, посмотрите код этих клиентов. Их можно найти в каталоге clients дистрибутива исходного кода MySQL.

Большинство других клиентских API (кроме поддержки Java) использует библиотеку mysqlclient, чтобы связаться с сервером MySQL. Это означает, что, например, Вы можете воспользоваться большинством системных переменных, которые используются другими программами потому, что реально они вызваны из библиотеки.

Пользователь имеет максимальный размер буфера связи. Размер буфера, который распределен первоначально (16 килобайт), автоматически увеличивается до максимального размера (максимум 16 мегабайт). Поскольку размеры буфера растут только по запросу, просто увеличивая заданное по умолчанию максимальное ограничение, Вы не заставите большее количество ресурсов использоваться. Эта проверка размера обычно применяется в сложных ситуациях.

Буфер связи должен быть достаточно большим, чтобы хранить одиночную инструкцию SQL (для трафика "клиент-на сервер") и одну строку возвращенных данных (для трафика "сервер-на-клиент"). Буфер связи каждого потока будет динамически расширен до максимального ограничения, чтобы обработать любой запрос или строку. Например, если Вы имеете значения BLOB, которые содержат до 16M данных, Вы должны иметь ограничение буфера связи по крайней мере в 16M (на клиенте и на сервере сразу). Заданный по умолчанию максимум пользователя равен 16M, но заданный по умолчанию максимум сервера равен всего 1M. Вы можете увеличивать это, меняя значение параметра max_allowed_packet при запуске сервера.

Сервер MySQL сокращает каждый буфер связи до net_buffer_length байт после каждого запроса. Для клиентуры размер буфера, связанного с подключением, не будет уменьшен, пока подключение не будет закрыто.

Для программирования с потоками, обратитесь к разделу "2.8 Как делать поточные клиенты". Для создания автономной прикладной программы, которая включает клиент и сервер в той же самой программе (и не связывается с внешним сервером MySQL) обратитесь к разделу "2.9 libmysqld, библиотека встроенного сервера MySQL".

2.1 Типы данных в C API

MYSQL

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

MYSQL_RES

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

MYSQL_ROW

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

MYSQL_FIELD

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

MYSQL_FIELD_OFFSET

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

my_ulonglong

Тип, используемый для числа строк и для mysql_affected_rows(), mysql_num_rows() и mysql_insert_id(). Этот тип обеспечивает диапазон от 0 до 1.84e19. На некоторых системах попытка печатать значение типа my_ulonglong не будет работать. Чтобы отпечатать такое значение, преобразуйте его к типу unsigned long и используйте формат вывода %lu. Например:

printf (Number of rows: %lu\n", 
	   (unsigned long) mysql_num_rows(result));

Структура MYSQL_FIELD содержит члены, перечисленные ниже:

char * name

Имя поля, как строка с нулевым символом в конце.

char * table

Имя таблицы, содержащей это поле, если это не расчетное поле. Для расчетных полей, значение table представлено пустой строкой.

char * def

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

enum enum_field_types type

Тип поля. Значение type может быть один из следующего:

Значение Type	Используемый тип
FIELD_TYPE_TINY	TINYINT
FIELD_TYPE_SHORT	SMALLINT
FIELD_TYPE_LONG	INTEGER
FIELD_TYPE_INT24	MEDIUMINT
FIELD_TYPE_LONGLONG	BIGINT
FIELD_TYPE_DECIMAL	DECIMAL или NUMERIC
FIELD_TYPE_FLOAT	FLOAT
FIELD_TYPE_DOUBLE	DOUBLE или REAL
FIELD_TYPE_TIMESTAMP	TIMESTAMP
FIELD_TYPE_DATE	DATE
FIELD_TYPE_TIME	TIME
FIELD_TYPE_DATETIME	DATETIME
FIELD_TYPE_YEAR	YEAR
FIELD_TYPE_STRING	Строка (CHAR или VARCHAR)
FIELD_TYPE_BLOB	BLOB или TEXT (используйте max_length, чтобы определить максимальную длину поля)
FIELD_TYPE_SET	SET
FIELD_TYPE_ENUM	ENUM
FIELD_TYPE_NULL	NULL
FIELD_TYPE_CHAR	Не рекомендуется: используйте FIELD_TYPE_TINY

Вы можете использовать макрос IS_NUM(), чтобы проверить имеет или нет поле числовой тип. Передайте значение type в IS_NUM(). Вернется TRUE, если поле числовое:

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

unsigned int length

Ширина поля, как она определена в описании таблицы.

unsigned int max_length

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

unsigned int flags

Различные биты задают флажки для поля. Значение flags может иметь ноль или большее количество из следующего набора битов:

Значение Flag	Что это значит
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
BLOB_FLAG	Поле имеет тип BLOB или TEXT
TIMESTAMP_FLAG	Поле имеет тип TIMESTAMP

Использование BLOB_FLAG, ENUM_FLAG и TIMESTAMP_FLAG не рекомендуется потому, что они указывают тип поля, а не атрибут типа. Предпочтительно проверить field->type вместо FIELD_TYPE_BLOB, FIELD_TYPE_ENUM или FIELD_TYPE_TIMESTAMP. Пример ниже иллюстрирует типичное использование 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)	Истина, если это поле BLOB или TEXT

unsigned int decimals

Число допустимых десятичных чисел для числовых полей.

2.2 Обзор функций C API

Функции, доступные в C API, перечислены ниже и описаны более подробно в следующем разделе. Подробности в разделе "2.3 Описание функций C API".

Чтобы соединиться с сервером, вызовите mysql_init(), чтобы инициализировать драйвер подключения, затем вызовите mysql_real_connect() с этим драйвером (наряду с другой информацией типа hostname, имени пользователя и пароля). При подключении mysql_real_connect() устанавливает флажок reconnect (часть структуры MYSQL) в значение 1. Этот флажок указывает, что когда запрос не может выполняться из-за потерянного подключения, надо попробовать повторно соединиться с сервером перед отказом. Когда Вы закончите работу с подключением, вызовите mysql_close() для его закрытия.

В то время как подключение активно, пользователь может посылать запросы SQL серверу, применяя функции mysql_query() или mysql_real_query(). Различие между ними в том, что mysql_query() ожидает, что запрос будет определен как строка с нулевым символом в конце, в то время как mysql_real_query() ожидает рассчитанную строку. Если несет в себе двоичные данные (которые сами по себе могут включать нулевые байты), Вы должны использовать только mysql_real_query().

Для каждого запроса не-SELECT (например, INSERT, UPDATE, DELETE), Вы можете выяснить, сколько строк были изменены, вызывая mysql_affected_rows().

Для запросов SELECT Вы получаете выбранные строки в наборе результатов. Обратите внимание, что некоторые инструкции подобны SELECT в том плане, что они возвращают строки. Сюда входят SHOW, DESCRIBE и EXPLAIN. Они должны обработаться тем же самым методом, что и обычный SELECT.

Имеются два пути для пользователя, чтобы обработать наборы результатов. Один путь состоит в том, чтобы получить весь набор результатов, вызывая mysql_store_result(). Эта функция получает с сервера все строки, возвращенные запросом и сохраняет их на клиенте. Второй путь инициализировать построчный набор результатов, вызывая mysql_use_result(). Эта функция инициализирует поиск, но фактически не получает никаких строк.

В обоих случаях Вы обращаетесь к строкам, вызывая mysql_fetch_row(). В случае mysql_store_result() mysql_fetch_row() обращается к строкам, которые уже были выбраны из сервера. В случае же mysql_use_result() mysql_fetch_row() фактически получает строку с сервера самостоятельно. Информация относительно размера данных в каждой строке доступна через вызов mysql_fetch_lengths().

После того, как Вы закончите работу с набором результатов, вызовите mysql_free_result(), чтобы освободить используемую память.

Два механизма поиска дополняют друг друга. Программы пользователя должны выбрать подход, который является наиболее подходящим для их требований. Практически же, клиентура имеет тенденцию обычно использовать mysql_store_result().

Преимущество mysql_store_result() в том, что, поскольку все строки были переданы пользователю, Вы не только можете обращаться к строкам последовательно, Вы можете также двигаться обратно в наборе результатов, используя mysql_data_seek() или mysql_row_seek(), чтобы изменить текущую (актуальную) позицию строки внутри набора результатов. Вы можете также выяснять, сколько там строк, вызывая mysql_num_rows(). С другой стороны, требования к памяти для mysql_store_result() могут быть очень высоки для больших наборов результатов, и Вы, вероятно, столкнетесь с проблемами нехватки памяти.

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

API позволяет клиентам ответить соответственно на запросы (получая строки только по мере необходимости) без того, чтобы знать, является или нет запрос SELECT. Вы можете делать это, вызывая mysql_store_result() после каждого mysql_query() (или mysql_real_query()). Если обращение к набору результатов прошло успешно, запросом был SELECT, и Вы можете читать строки. Если произошел сбой, вызовите mysql_field_count(), чтобы определить, должен или нет фактически ожидаться результат. Если mysql_field_count() возвращает ноль, запрос не возвратил никаких данных (это показывает, что это был INSERT, UPDATE, DELETE или что-то в этом роде) и не возвратит строки. Если mysql_field_count() отличен от нуля, запрос должен был возвратить строки, но не сделал этого. Это указывает, что запросом был SELECT, который потерпел неудачу.

Вызовы mysql_store_result() и mysql_use_result() позволяют Вам получать информацию относительно полей, которые составляют набор результатов (число полей, их имена, типы и т.п.). Вы можете обращаться к информации поля последовательно внутри строки, вызывая mysql_fetch_field() неоднократно, или по номеру поля внутри строки, вызывая mysql_fetch_field_direct() напрямую. Текущая (актуальная) позиция курсора поля может быть изменена вызовом mysql_field_seek(). Установка курсора поля воздействует на последующие обращения к mysql_fetch_field(). Вы можете также получать информацию для полей в любой момент, вызывая mysql_fetch_fields().

Для обнаружения и сообщения об ошибках MySQL обеспечивает доступ к информации ошибки посредством функций mysql_errno() и mysql_error(). Они возвращают код ошибки или сообщение об ошибке для последней вызванной функции, позволяя Вам определить, когда ошибка произошла, и что это было.

2.3 Описание функций C API

В описаниях ниже параметр или значение возврата NULL означает NULL в смысле языка программирования C, а не MySQL-значение NULL.

Функции, которые возвращают значение, возвращают указатель или целое число. Если не определено иное, функции, возвращающие указатель, возвращают значение не-NULL, чтобы указать успех, или значение NULL, чтобы указать ошибку, а функции, возвращающие число, возвращают целочисленный ноль, чтобы указать успех, или отличное от нуля значение, чтобы указать ошибку. Обратите внимание, что "отличное от нуля" означает только это. Если функциональное описание не говорит иного, не надо проверять результат на соответствие каким-либл числам, кроме нуля.

if (result)             /* правильно */
    ... error ...

if (result < 0)      /* неправильно */
    ... error ...

if (result == -1)       /* неправильно */
    ... error ...

Когда функция возвращает ошибку, подраздел Ошибки описания функции вносит в список возможные типы ошибок. Вы можете выяснить, который из них произошел, вызывая mysql_errno(). Представление строки ошибки может быть получено, вызывая mysql_error().

2.3.1 mysql_affected_rows()

my_ulonglong mysql_affected_rows(MYSQL *mysql)

2.3.2 Описание

Возвращает число строк, измененных последним UPDATE, удаленных последним DELETE или вставленных последней инструкцией INSERT. Может быть вызвана немедленно после mysql_query() для UPDATE, DELETE или INSERT. Для инструкции SELECT mysql_affected_rows() работает подобно mysql_num_rows().

2.3.3 Возвращаемые значения

Целое число, большее, чем ноль, указывает количество обработанных строк. Ноль указывает, что никакие записи обработаны не были. -1 указывает, что запрос возвратил ошибку или то, что для запроса SELECT mysql_affected_rows() был вызван до вызова mysql_store_result().

2.3.4 Ошибки

Нет.

2.3.5 Пример

mysql_query(&mysql,"UPDATE products SET cost=cost*1.25 WHERE group=10");
printf("%ld products updated",(long) mysql_affected_rows(&mysql));

Если определен флажок CLIENT_FOUND_ROWS, при соединение с mysqld mysql_affected_rows() возвратит число строк, согласованных инструкцией WHERE для UPDATE.

Обратите внимание, что, когда использована команда REPLACE, mysql_affected_rows() вернет 2 потому, что в этом случае одна строка была вставлена, а затем дубликат был удален.

2.3.6 mysql_close()

void mysql_close(MYSQL *mysql)

2.3.7 Описание

Закрывает предварительно открытое подключение. mysql_close() также освободит дескриптор подключения, указанный в mysql, если дескриптор был распределен автоматически mysql_init() или mysql_connect().

2.3.8 Возвращаемые значения

Нет.

2.3.9 Ошибки

Нет.

2.3.10 mysql_connect()

MYSQL *mysql_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd)

2.3.11 Описание

пытается устанавливать подключение с сервером MySQL на компьютере host. mysql_connect() должна завершиться успешно прежде, чем Вы сможете выполнить любую из функций API, за исключением mysql_get_client_info().

Значения параметров такие же, как для соответствующих параметров mysql_real_connect() с тем различием, что параметр подключения может быть NULL. В этом случае C API распределяет память для структуры подключения автоматически и освобождает ее, когда Вы вызываете mysql_close(). Недостаток этого подхода в том, что Вы не можете получить сообщение об ошибке, если подключение терпит неудачу. Чтобы получать информацию об ошибке из mysql_errno() или mysql_error(), Вы должны обеспечить имеющий силу указатель на структуру MYSQL.

2.3.12 Возвращаемые значения

Аналогично mysql_real_connect().

2.3.13 Ошибки

Аналогично mysql_real_connect().

2.3.14 mysql_change_user()

if (mysql_change_user(&mysql, "user", "password", "new_database"))
{
   fprintf(stderr, "Failed to change user.  Error: %s\n",
           mysql_error(&mysql));
}

2.3.19 mysql_character_set_name()

const char *mysql_character_set_name(MYSQL *mysql)

2.3.20 Описание

Возвращает заданный по умолчанию набор символов для текущего (актуального) подключения.

2.3.21 Возвращаемые значения

Заданный по умолчанию набор символов

2.3.22 Ошибки

Нет.

2.3.23 mysql_create_db()

int mysql_create_db(MYSQL *mysql, const char *db)

2.3.24 Описание

Создает базу данных с именем db.

2.3.25 Возвращаемые значения

Ноль, если база данных была создана успешно. Отличное от нуля, если в процессе произошла ошибка.

2.3.26 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.Произошла неизвестная ошибка.

2.3.27 Пример

if (mysql_create_db(&mysql, "my_database"))
{
   fprintf(stderr, "Failed to create new database. Error: %s\n",
           mysql_error(&mysql));
}

2.3.28 mysql_data_seek()

void mysql_data_seek(MYSQL_RES *result, unsigned long long offset)

2.3.29 Описание

Переходит к произвольной строке в наборе результатов запроса. Это требует, чтобы структура набора результата содержала весь результат запроса, так что mysql_data_seek() может использоваться только в конъюнкции с mysql_store_result(), но никак не с mysql_use_result().

Смещение должно быть значением в диапазоне от 0 до mysql_num_rows(result)-1.

2.3.30 Возвращаемые значения

Нет.

2.3.31 Ошибки

Нет.

2.3.32 mysql_debug()

void mysql_debug(char *debug)

2.3.33 Описание

Делает DBUG_PUSH с заданной строкой. Вызов mysql_debug() использует библиотеку отладки Fred Fish. Чтобы использовать эту функцию, Вы должны компилировать библиотеку клиентов так, чтобы поддерживать отладку.

2.3.34 Возвращаемые значения

Нет.

2.3.35 Ошибки

Нет.

2.3.36 Пример

Обращение, показанное ниже, заставляет библиотеку клиентов генерировать файл трассировки /tmp/client.trace на машине пользователя:

mysql_debug("d:t:O,/tmp/client.trace");

2.3.37 mysql_drop_db()

int mysql_drop_db(MYSQL *mysql, const char *db)

2.3.38 Описание

Удвляет базу данных, упомянутую как параметр db.

2.3.39 Возвращаемые значения

Ноль, если база данных была удалена успешно. Отличное от нуля, если в процессе произошла ошибка.

2.3.40 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.41 Пример

if (mysql_drop_db(&mysql, "my_database"))
   fprintf(stderr, "Failed to drop the database: Error: %s\n",
           mysql_error(&mysql));

2.3.42 mysql_dump_debug_info()

int mysql_dump_debug_info(MYSQL *mysql)

2.3.43 Описание

Инструктирует сервер, чтобы писать некоторую информацию отладки в файл регистрации. Отдавший команду пользователь должен иметь привилегию process, чтобы работать.

2.3.44 Возвращаемые значения

Ноль, если команда была успешно выполнена. Отличное от нуля, если в процессе произошла ошибка.

2.3.45 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.46 mysql_eof()

my_bool mysql_eof(MYSQL_RES *result)

2.3.47 Описание

mysql_eof() определяет, читалась или нет последняя строка набора результатов.

Если Вы приобретаете результат из успешного обращения к mysql_store_result(), клиент получает весь набор в одной операции. В этом случае возврат NULL из mysql_fetch_row() всегда означает, что конец набора результатов был достигнут и не нужно вызвать mysql_eof().

С другой стороны, если Вы используете mysql_use_result(), чтобы инициализировать поиск набора результата, строки набора получены с сервера по одной, поскольку Вы вызываете mysql_fetch_row() неоднократно. Потому что ошибка может происходить на подключении в течение этого процесса, значение NULL из функции mysql_fetch_row() не обязательно означает, что конец набора результатов был достигнут. В этом случае, Вы можете использовать mysql_eof(), чтобы определить, что там случилось. Функция mysql_eof() возвращает значение, отличное от нуля, если конец набора результатов был достигнут и ноль, если произошла ошибка.

Исторически mysql_eof() предшествует стандартной функции MySQL mysql_errno() и mysql_error(). Так как те функции ошибки обеспечивают ту же самую информацию, их использование предпочтительнее mysql_eof(). Фактически, они обеспечивают большее количество информации потому, что mysql_eof() возвращает только булево значение, в то время как функции ошибки указывают причину.

2.3.48 Возвращаемые значения

Функция mysql_eof() возвращает значение, отличное от нуля, если конец набора результатов был достигнут и ноль, если произошла ошибка.

2.3.49 Ошибки

Нет.

2.3.50 Пример

Следующий пример показывает, как Вы могли бы использовать mysql_eof():

mysql_query(&mysql,"SELECT * FROM some_table");
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
  // Что-то делается с данными
}
if (!mysql_eof(result))  // mysql_fetch_row() потерпел неудачу из-за ошибки
{
   fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
}

Однако, Вы можете достичь того же самого эффекта с помощью стандартных функций обработки ошибок в MySQL:

mysql_query(&mysql,"SELECT * FROM some_table");
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
  // Что-то делается с данными
}
if (mysql_errno(&mysql))
   // mysql_fetch_row() потерпел неудачу из-за ошибки
{
   fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
}

2.3.51 mysql_errno()

unsigned int mysql_errno(MYSQL *mysql)

2.3.52 Описание

Для подключения, определенного в mysql, mysql_errno() возвращает код ошибки для вызванной функции API, которая может сработать нормально или потерпеть неудачу. Значение возврата 0 означает, что никакой ошибки не произошло. Числа сообщений об ошибках клиента перечислены в файле заголовка MySQL errmsg.h. Серверные ошибки перечислены в mysqld_error.h. В дистрибутиве исходного кода MySQL Вы можете найти полный список сообщений об ошибках и их кодов в файле Docs/mysqld_error.txt.

2.3.53 Возвращаемые значения

Значение кода ошибки. 0, если никакая ошибка не произошла.

2.3.54 Ошибки

Нет.

2.3.55 mysql_error()

char *mysql_error(MYSQL *mysql)

2.3.56 Описание

Для подключения, определенного в mysql, mysql_error() возвращает сообщение об ошибках для вызванной функции API, которая может сработать нормально или потерпеть неудачу. Пустая строка ("") вернется, если никакой ошибки не произошло. Это означает, что следующие тесты эквивалентны:

if (mysql_errno(&mysql))
{
   // an error occurred
}
if (mysql_error(&mysql)[0] != '\0')
{
   // an error occurred
}

Язык сообщений об ошибках пользователя может быть изменен перекомпиляцией библиотеки клиента MySQL. В настоящее время Вы можете выбирать сообщения об ошибках на нескольких различных языках.

2.3.57 Возвращаемые значения

Символьная строка, которая описывает ошибку. Пустая строка, если никакой ошибки не произошло.

2.3.58 Ошибки

Нет.

2.3.59 mysql_escape_string()

Это идентично mysql_real_escape_string() за исключением того, что требуется подключение как первый параметр. mysql_real_escape_string() обработает строку согласно текущему (актуальному) набору символов, в то время как mysql_escape_string() игнорирует установку charset.

2.3.60 mysql_fetch_field()

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

2.3.61 Описание

Возвращает определение одного столбца набора результатов как структуру MYSQL_FIELD. Вызовите эту функцию неоднократно, чтобы собрать информацию относительно всех столбцов в наборе результатов. mysql_fetch_field() возвращает NULL, когда все поля уже обработаны или их не было вовсе.

mysql_fetch_field() будет сброшен так, чтобы возвратить информацию относительно первого поля каждый раз, когда Вы выполняете новый запрос SELECT. На поле, возвращенное mysql_fetch_field() также воздействуют обращения к mysql_field_seek().

Если Вы вызвали mysql_query() чтобы выполнить SELECT на таблице, но не вызвали mysql_store_result(), MySQL возвращает заданную по умолчанию длину blob (8K), если Вы вызываете mysql_fetch_field(), чтобы спросить о длине поля типа BLOB. Размер в 8K выбран потому, что MySQL не знает максимальную длину для BLOB. Это должно быть сделано с перестраиваемой конфигурацией когда-нибудь. Как только Вы получили набор результатов, field->max_length хранит длину самого большого значения для этого столбца в специфическом запросе.

2.3.62 Возвращаемые значения

Структура типа MYSQL_FIELD для текущего (актуального) столбца. NULL, если никакие столбцы не обработаны.

2.3.63 Ошибки

Нет.

2.3.64 Пример

MYSQL_FIELD *field;

while((field = mysql_fetch_field(result)))
{
  printf("field name %s\n", field->name);
}

2.3.65 mysql_fetch_fields()

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

2.3.66 Описание

Возвращает массив всех структур MYSQL_FIELD для набора результатов. Каждая структура обеспечивает определение поля для одного столбца набора результатов.

2.3.67 Возвращаемые значения

Массив структур MYSQL_FIELD для всех столбцов набора результатов.

2.3.68 Ошибки

Нет.

2.3.69 Пример

unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *fields;

num_fields = mysql_num_fields(result);
fields = mysql_fetch_fields(result);
for (i = 0; i < num_fields; i++)
{
  printf("Field %u is %s\n", i, fields[i].name);
}

2.3.70 mysql_fetch_field_direct()

MYSQL_FIELD *mysql_fetch_field_direct(MYSQL_RES *result, unsigned int fieldnr)

2.3.71 Описание

Получает код поля fieldnr для столбца внутри набора результатов, возвращает определение поля столбца как структура MYSQL_FIELD. Вы можете использовать эту функцию, чтобы получить описание для произвольного столбца. Значение fieldnr должно быть в диапазоне от 0 до mysql_num_fields(result)-1.

2.3.72 Возвращаемые значения

Структура MYSQL_FIELD для определенного столбца.

2.3.73 Ошибки

Нет.

2.3.74 Пример

unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *field;

num_fields = mysql_num_fields(result);
for (i = 0; i < num_fields; i++)
{
  field = mysql_fetch_field_direct(result, i);
  printf("Field %u is %s\n", i, field->name);
}

2.3.75 mysql_fetch_lengths()

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

2.3.76 Описание

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

Длина для пустых столбцов и для столбцов, содержащих значения NULL, равна нулю. Чтобы видеть, как отличить эти два случая, обратитесь к описанию mysql_fetch_row().

2.3.77 Возвращаемые значения

Массив длинных целых чисел без знака, представляющих размер каждого столбца (не включая любые символы пробелов в хвосте). NULL, если что-то пошло не так.

2.3.78 Ошибки

mysql_fetch_lengths() имеет силу только для текущей строки набора результатов. Этот вызов возвращает NULL, если Вы вызываете его перед mysql_fetch_row() или после получения всех строк в результате.

2.3.79 Пример

MYSQL_ROW row;
unsigned long *lengths;
unsigned int num_fields;
unsigned int i;

row = mysql_fetch_row(result);
if (row)
{
   num_fields = mysql_num_fields(result);
   lengths = mysql_fetch_lengths(result);
   for (i = 0; i < num_fields; i++)
   {
     printf("Column %u is %lu bytes in length.\n", i, lengths[i]);
   }
}

2.3.80 mysql_fetch_row()

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

2.3.81 Описание

Получает следующую строку набора результатов. Когда используется после mysql_store_result(), mysql_fetch_row() возвращает NULL, когда не имеется больше строк, чтобы получить. Когда используется после mysql_use_result(), mysql_fetch_row() вернет NULL, когда не имеется больше строк, чтобы получить, или произошла ошибка.

Число значений в строке задано mysql_num_fields(result). Если row хранит значение возврата от обращения к mysql_fetch_row(), указатели на значения меняются с row[0] на row[mysql_num_fields(result)-1]. Значения NULL в строке обозначены указателями NULL.

Длины значений полей в строке могут быть получены, вызывая mysql_fetch_lengths(). Пустые поля и поля, содержащие NULL имеют длину 0. Вы можете отличать их, проверяя указатель для значения поля. Если указатель равен NULL, поле NULL, иначе поле пустое.

2.3.82 Возвращаемые значения

Структура MYSQL_ROW для следующей строки. NULL, если не имеется больше строк, чтобы получить, или произошла ошибка.

2.3.83 Ошибки

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.84 Пример

MYSQL_ROW row;
unsigned int num_fields;
unsigned int i;

num_fields = mysql_num_fields(result);
while ((row = mysql_fetch_row(result)))
{
  unsigned long *lengths;
  lengths = mysql_fetch_lengths(result);
  for (i = 0; i < num_fields; i++)
  {
    printf("[%.*s] ", (int) lengths[i], row[i] ? row[i] : "NULL");
  }
  printf("\n");
}

2.3.85 mysql_field_count()

unsigned int mysql_field_count(MYSQL *mysql)

Если Вы используете версию MySQL ранее, чем Version 3.22.24, Вы должны вместо этого использовать unsigned int mysql_num_fields(MYSQL *mysql).

2.3.86 Описание

Возвращает число столбцов для самого последнего запроса на подключении.

Нормальное использование этой функции: когда mysql_store_result() возвращает NULL (и таким образом Вы не имеете никакого указателя на набор результатов). В этом случае Вы можете вызывать mysql_field_count(), чтобы определить, должен или нет mysql_store_result() произвести не пустой результат. Это позволяет программе пользователя выбрать соответствующее действие без того, чтобы знать, был или нет запрос SELECT (или SELECT-подобным). Пример, показанный ниже иллюстрирует, как это может быть выполнено.

2.3.87 Возвращаемые значения

Целое число без знака, представляющее число полей в наборе результатов.

2.3.88 Ошибки

Нет.

2.3.89 Пример

MYSQL_RES *result;
unsigned int num_fields;
unsigned int num_rows;

if (mysql_query(&mysql,query_string))
{
   // error
}
else // query succeeded, process any data returned by it
{
  result = mysql_store_result(&mysql);
  if (result)  // there are rows
  {
     num_fields = mysql_num_fields(result);
     // retrieve rows, then call mysql_free_result(result)
  }
  else  // mysql_store_result() returned nothing; should it have?
  {
    if (mysql_field_count(&mysql) == 0)
    {
       // query does not return data
       // (it was not a SELECT)
       num_rows = mysql_affected_rows(&mysql);
    }
    else // mysql_store_result() should have returned data
    {
      fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
    }
  }
}

Вариант: можно заменить mysql_field_count(&mysql) на mysql_errno(&mysql). В этом случае Вы проверяете непосредственно для ошибки из mysql_store_result() вместо анализа значения mysql_field_count() на предмет того, является или нет оператор SELECT.

2.3.90 mysql_field_seek()

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

2.3.91 Описание

Устанавливает курсор поля к данному смещению. Следующее обращение к mysql_fetch_field() получит определение поля столбца, связанного именно с этим смещением.

Чтобы перейти к началу строки, передайте 0 как значение offset.

2.3.92 Возвращаемые значения

Предыдущее значение курсора поля.

2.3.93 Ошибки

Нет.

2.3.94 mysql_field_tell()

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

2.3.95 Описание

Возвращает позицию курсора поля, используемого для последнего mysql_fetch_field(). Это значение может использоваться как параметр для mysql_field_seek().

2.3.96 Возвращаемые значения

Текущее смещение курсора поля.

2.3.97 Ошибки

Нет.

2.3.98 mysql_free_result()

void mysql_free_result(MYSQL_RES *result)

2.3.99 Описание

Освобождает память, распределенную для набора результатов mysql_store_result(), mysql_use_result(), mysql_list_dbs() и другими подобными функциями. Когда Вы закончили работу с набором результатов, Вы должны освободить память, которую он использует, вызывая mysql_free_result().

2.3.100 Возвращаемые значения

Нет.

2.3.101 Ошибки

Нет.

2.3.102 mysql_get_client_info()

char *mysql_get_client_info(void)

2.3.103 Описание

Возвращает строку, которая представляет версию клиентской библиотеки.

2.3.104 Возвращаемые значения

Символьная строка, которая представляет версию клиентской библиотеки MySQL.

2.3.105 Ошибки

Нет.

2.3.106 mysql_get_host_info()

char *mysql_get_host_info(MYSQL *mysql)

2.3.107 Описание

Возвращает строку, описывающую тип используемого подключения, включая имя главного компьютера сервера.

2.3.108 Возвращаемые значения

Символьная строка, представляющая имя компьютера и тип подключения.

2.3.109 Ошибки

Нет.

2.3.110 mysql_get_proto_info()

unsigned int mysql_get_proto_info(MYSQL *mysql)

2.3.111 Описание

Возвращает код версии протокола, используемой текущим подключением.

2.3.112 Возвращаемые значения

Целое число без знака, представляющее версию протокола, используемую текущим (актуальным) подключением.

2.3.113 Ошибки

Нет.

2.3.114 mysql_get_server_info()

char *mysql_get_server_info(MYSQL *mysql)

2.3.115 Описание

Возвращает строку, которая представляет номер версии сервера.

2.3.116 Возвращаемые значения

Символьная строка, которая представляет номер версии станции.

2.3.117 Ошибки

Нет.

2.3.118 mysql_info()

char *mysql_info(MYSQL *mysql)

2.3.119 Описание

Возвращает строку, обеспечивающую информацию относительно недавно выполненного запроса, но только для инструкций, перечисленных ниже. Для других инструкций mysql_info() всегда возвращает NULL. Формат строки изменяется в зависимости от типа запроса, как описано ниже. Числа только иллюстративны: строка будет содержать значения, соответствующие запросу.

INSERT INTO ... SELECT ...

Формат строки: Records: 100 Duplicates: 0 Warnings: 0

INSERT INTO ... VALUES (...),(...),(...)...

Формат строки: Records: 3 Duplicates: 0 Warnings: 0

LOAD DATA INFILE ...

Формат строки: Records: 1 Deleted: 0 Skipped: 0 Warnings: 0

ALTER TABLE

Формат строки: Records: 3 Duplicates: 0 Warnings: 0

UPDATE

Формат строки: Rows matched: 40 Changed: 40 Warnings: 0

Обратите внимание, что mysql_info() возвращает значение не-NULL для инструкции INSERT ... VALUES только, если много списков значений было определено в инструкции.

2.3.120 Возвращаемые значения

Символьная строка, представляющая дополнительную информацию относительно последнего выполненного запроса. NULL, если никакая информация не доступна для запроса.

2.3.121 Ошибки

Нет.

2.3.122 mysql_init()

MYSQL *mysql_init(MYSQL *mysql)

2.3.123 Описание

Распределяет или инициализирует объект MYSQL, подходящий для mysql_real_connect(). Если mysql является указателем NULL, функция распределяет память, инициализирует и возвращает новый объект. Иначе объект будет просто инициализирован, и адрес объекта возвращен. Если mysql_init() распределяет новый объект, место будет освобождено, когда будет вызвана mysql_close().

2.3.124 Возвращаемые значения

Инициализированный дескриптор MYSQL*. NULL, если недостаточно памяти, чтобы распределить и инициализировать новый объект.

2.3.125 Ошибки

В случае недостаточной памяти вернется NULL.

2.3.126 mysql_insert_id()

my_ulonglong mysql_insert_id(MYSQL *mysql)

2.3.127 Описание

Возвращает ID, сгенерированный предыдущим запросом для столбца с поддержкой AUTO_INCREMENT. Используйте эту функцию после того, как Вы выполнили запрос INSERT для таблицы, которая содержит поле AUTO_INCREMENT.

Обратите внимание, что mysql_insert_id() возвращает 0, если предыдущий запрос не генерирует значение AUTO_INCREMENT. Если Вы должны сохранить значение для последующего неспешного потребления убедитесь, что вызвали mysql_insert_id() немедленно после того запроса, который генерирует значение.

mysql_insert_id() модифицируется после инструкций INSERT и UPDATE, которые генерируют значение AUTO_INCREMENT, или установки значения столбца с помощью LAST_INSERT_ID(expr).

Также обратите внимание, что значение функции SQL LAST_INSERT_ID() всегда содержит самое последнее сгенерированное значение AUTO_INCREMENT, и оно не будет сброшено между запросами потому, что значение этой функции поддерживается сервером.

2.3.128 Возвращаемые значения

Значение поля AUTO_INCREMENT, которое модифицировалось предыдущим запросом. 0, если не имелось никакого предыдущего запроса на подключении, или если запрос не модифицировал AUTO_INCREMENT.

2.3.129 Ошибки

Нет.

2.3.130 mysql_kill()

int mysql_kill(MYSQL *mysql, unsigned long pid)

2.3.131 Описание

Просит, чтобы сервер уничтожил поток, определенный как pid.

2.3.132 Возвращаемые значения

Ноль для успеха. Отличное от нуля, если произошла ошибка.

2.3.133 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.134 mysql_list_dbs()

MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char *wild)

2.3.135 Описание

Возвращает набор результатов, состоящий из имен баз данных на сервере, которые соответствуют простому регулярному выражению, определенному параметром wild. Здесь wild может содержать групповые символы % или _, или может быть NULL, чтобы соответствовать всем базам данных. Вызов mysql_list_dbs() подобен выполнению запроса SHOW databases [LIKE wild].

Вы должны освободить набор результатов с помощью mysql_free_result().

2.3.136 Возвращаемые значения

Набор результатов MYSQL_RES для успеха, NULL, если произошла ошибка.

2.3.137 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_OUT_OF_MEMORY

Не хватило памяти.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.138 mysql_list_fields()

MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char *table, const char *wild)

2.3.139 Описание

Возвращает набор результатов, состоящий из имен полей в данной таблице, которые соответствуют простому регулярному выражению, определенному параметром wild. Здесь wild может содержать групповые символы % или _, или может быть NULL, чтобы соответствовать всем полям. Вызов mysql_list_fields() подобен выполнению запроса SHOW COLUMNS FROM tbl_name [LIKE wild].

Обратите внимание, что рекомендуется, чтобы Вы использовали SHOW COLUMNS FROM tbl_name вместо mysql_list_fields().

Вы должны освободить набор результатов с помощью mysql_free_result().

2.3.140 Возвращаемые значения

Набор результатов MYSQL_RES для успеха. NULL, если произошла ошибка.

2.3.141 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.142 mysql_list_processes()

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

2.3.143 Описание

Возвращает набор результатов, описывающий текущие потоки сервера. Это тот же самый вид информации, что и сообщаемый командой mysqladmin processlist или запросом SHOW PROCESSLIST.

Вы должны освободить набор результатов с помощью mysql_free_result().

2.3.144 Возвращаемые значения

Набор результатов MYSQL_RES для успеха. NULL, если произошла ошибка.

2.3.145 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.146 mysql_list_tables()

MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char *wild)

2.3.147 Описание

Возвращает набор результатов, состоящий из имен таблиц в текущей базе данных, которые соответствуют простому регулярному выражению, определенному параметром wild. Здесь wild может содержать групповые символы % или _, или может быть NULL, чтобы соответствовать всем таблицам. Вызов mysql_list_tables() подобен выполнению запроса SHOW tables [LIKE wild].

Вы должны освободить набор результатов с помощью mysql_free_result().

2.3.148 Возвращаемые значения

Набор результатов MYSQL_RES для успеха. NULL, если произошла ошибка.

2.3.149 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.150 mysql_num_fields()

unsigned int mysql_num_fields(MYSQL_RES *result)

или

unsigned int mysql_num_fields(MYSQL *mysql)

Вторая форма не работает в MySQL Version 3.22.24 или выше. Чтобы передавать параметр MYSQL*, Вы должны использовать unsigned int mysql_field_count(MYSQL *mysql).

2.3.151 Описание

Возвращает число столбцов в наборе результатов.

Обратите внимание, что Вы можете получать число столбцов из указателя набора результатов или от дескриптора подключения. Вы используете дескриптор подключения, если mysql_store_result() или mysql_use_result() возвращает NULL (и таким образом Вы не имеете никакого указателя набора результата). В этом случае Вы можете вызывать mysql_field_count() чтобы определить, должен или нет mysql_store_result() произвести непустой результат. Это позволяет программе пользователя выбрать соответствующее действие без того, чтобы знать, был или нет запрос SELECT (или SELECT-подобным). Пример, показанный ниже иллюстрирует, как это может быть выполнено.

2.3.152 Возвращаемые значения

Целое число без знака, представляющее число полей в наборе результатов.

2.3.153 Ошибки

Нет.

2.3.154 Пример

MYSQL_RES *result;
unsigned int num_fields;
unsigned int num_rows;

if (mysql_query(&mysql,query_string))
{
   // error
}
else // query succeeded, process any data returned by it
{
  result = mysql_store_result(&mysql);
  if (result)  // there are rows
  {
     num_fields = mysql_num_fields(result);
     // retrieve rows, then call mysql_free_result(result)
  }
  else // mysql_store_result() returned nothing; should it have?
  {
    if (mysql_errno(&mysql))
    {
       fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
    }
    else if (mysql_field_count(&mysql) == 0)
    {
      // query does not return data
      // (it was not a SELECT)
      num_rows = mysql_affected_rows(&mysql);
    }
  }
}

Вариант (если Вы ЗНАЕТЕ, что ваш запрос должен был возвратить набор результатов): заменить обращение mysql_errno(&mysql) на проверку mysql_field_count(&mysql)=0.

2.3.155 mysql_num_rows()

my_ulonglong mysql_num_rows(MYSQL_RES *result)

2.3.156 Описание

Возвращает число строк в наборе результатов.

Использование mysql_num_rows() зависит от того, используете ли Вы mysql_store_result() или mysql_use_result(), чтобы получить набор результатов. Если Вы используете mysql_store_result(), mysql_num_rows() может быть вызван немедленно. Если Вы используете mysql_use_result(), mysql_num_rows() не будет возвращать правильное значение, пока все строки в наборе результатов не будут получены.

2.3.157 Возвращаемые значения

Число строк в наборе результатов.

2.3.158 Ошибки

Нет.

2.3.159 mysql_options()

int mysql_options(MYSQL *mysql, enum mysql_option option, const char *arg)

2.3.160 Описание

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

mysql_options() должна быть вызвана после mysql_init(), но перед mysql_connect() или mysql_real_connect().

Параметр option представляет собой опцию, которую Вы хотите устанавливать, arg задает значение для опции. Если опция целое число, то arg должен указывать на значение целого числа.

Возможные значения параметров:

Обратите внимание, что группа client всегда читается, если Вы используете MYSQL_READ_DEFAULT_FILE или MYSQL_READ_DEFAULT_GROUP.

Определенная группа в файле опций может содержать следующие параметры:

Обратите внимание, что timeout был заменен на connect_timeout, но timeout будет все еще работать некоторое время для совместимости.

2.3.161 Возвращаемые значения

Ноль для успеха. Отличное от нуля, если Вы использовали неизвестную опцию.

2.3.162 Пример

MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_OPT_COMPRESS,0);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"odbc");
if (!mysql_real_connect(&mysql,"host","user","passwd",
    "database",0,NULL,0))
{
   fprintf(stderr, "Failed to connect to database: Error: %s\n",
           mysql_error(&mysql));
}

Вышеупомянутое запрашивает использовать сжатый протокол клиент-сервер и читать дополнительные параметры из группы odbc в файле опций my.cnf.

2.3.163 mysql_ping()

int mysql_ping(MYSQL *mysql)

2.3.164 Описание

Проверяет работает или нет подключение. В случае неработоспособности будет предпринято автоматическое переподключение.

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

2.3.165 Возвращаемые значения

Ноль, если подключение работает. Отличное от нуля, если произошла ошибка.

2.3.166 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.167 mysql_query()

int mysql_query(MYSQL *mysql, const char *query)

2.3.168 Описание

Выполняет запрос SQL, указанный строкой с нулевым символом в конце. Запрос должен состоять из одиночной инструкции SQL. Вы не должны добавлять точку с запятой (;) или \g для завершения запроса.

mysql_query() не может использоваться для запросов, которые содержат двоичные данные, взамен Вы должны использовать mysql_real_query(). Двоичные данные могут содержать в себе символ \0, который mysql_query() интерпретирует как конец строки запроса.

Если Вы хотите знать, возвратил ли запрос набор результатов или нет, Вы можете использовать mysql_field_count(), чтобы проверить это. Подробности в разделе "2.3.85 mysql_field_count()".

2.3.169 Возвращаемые значения

Ноль, если запрос был успешен. Отличное от нуля, если произошла ошибка.

2.3.170 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.171 mysql_real_connect()

MYSQL *mysql_real_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd, const char *db, unsigned int port, const char *unix_socket, unsigned int client_flag)

2.3.172 Описание

mysql_real_connect() пытается установить подключение с сервером MySQL, запущенным на машине host. mysql_real_connect() должен завершиться успешно прежде, чем Вы сможете выполнить любую из других функций API, за исключением mysql_get_client_info().

Параметры определены следующим образом:

• Первый параметр должен быть адресом существующей структуры типа MYSQL. Перед вызовом mysql_real_connect() Вы должны вызвать mysql_init(), чтобы инициализировать структуру MYSQL. Вы можете изменять много параметров подключения через вызов mysql_options(). Подробности в разделе "2.3.159 mysql_options()".
• Значением host может быть имя или адрес IP. Если это NULL или строка localhost, выполняется подключение к локальной системе. Если OS поддерживает сокеты (Unix) или именованные каналы (Windows), именно они используются вместо стека протоколов TCP/IP, чтобы соединиться с сервером.
• Аргумент user содержит ID пользователя MySQL. Если user равен NULL, предполагается текущий пользователь. Под Unix это текущее (актуальное) имя входа в систему. Под Windows ODBC имя пользователя должно быть определено явно.
• Параметр passwd содержит пароль для user. Если passwd равен NULL, только записи в таблице user, которые имеют пустое поле пароля, будут проверены на соответствие. Это позволяет администратору базы данных устанавливать систему привилегий MySQL таким способом, которым пользователи получают различные привилегии в зависимости от того, определили или нет они пароль. ОБРАТИТЕ ВНИМАНИЕ: Не пытайтесь шифровать пароль перед вызовом mysql_real_connect(): шифрование пароля обработано автоматически.
• db задает имя базы данных. Если db не NULL, подключение установит заданную по умолчанию базу данных.
• Если port не равен 0, значение будет использоваться как номер порта для подключения по TCP/IP. Обратите внимание, что параметр host определяет тип подключения.
• Если unix_socket не равен NULL, строка определяет сокет или именованный канал, который должен использоваться. Обратите внимание, что параметр host определяет тип подключения.
• Значение client_flag как правило равно 0, но может быть установлено к комбинации из следующих флажков в специальных обстоятельствах:

  Имя флажка	Что он делает
  CLIENT_COMPRESS	Использовать протокол сжатия.
  CLIENT_FOUND_ROWS	Возвратить число найденных, а не обработанных строк.
  CLIENT_IGNORE_SPACE	Позволить использовать пробелы после имен функций. Делает все зарезервированные слова именами функций.
  CLIENT_INTERACTIVE	Позволить interactive_timeout секунд (вместо wait_timeout секунд) бездеятельности перед закрытием подключения.
  CLIENT_NO_SCHEMA	Не позволять синтаксис db_name.tbl_name.col_name. Это сделано для ODBC. Это заставляет синтаксический анализатор генерировать ошибку, если Вы используете тот синтаксис, который является полезным для заманивания в ловушку ошибок в некоторых программах ODBC.
  CLIENT_ODBC	Работает клиент ODBC.
  CLIENT_SSL	Использовать шифрованный протокол SSL.

2.3.173 Возвращаемые значения

Дескриптор MYSQL*, если подключение было успешно, NULL, если подключение было неудачно. Для успешного подключения, значение возврата: такое же, как значение первого параметра, если Вы не передаете NULL для этого параметра.

2.3.174 Ошибки

CR_CONN_HOST_ERROR

Не удалось связаться с сервером.

CR_CONNECTION_ERROR

Не удалось связаться с локальным сервером.

CR_IPSOCK_ERROR

Не удалось создать IP-сокет.

CR_OUT_OF_MEMORY

Не хватило памяти.

CR_SOCKET_CREATE_ERROR

Не удалось создать Unix-сокет.

CR_UNKNOWN_HOST

Не удалось найти IP-адрес для hostname.

CR_VERSION_ERROR

Несоответствие протоколов следовало из попытки соединиться с сервером с помощью клиентской библиотеки, которая использует иную версию протокола. Это может случиться, если Вы используете очень старую библиотеку, чтобы соединиться с новым сервером, который не был запущен с параметром --old-protocol.

CR_NAMEDPIPEOPEN_ERROR

Не удалось создать именованный канал в Windows.

CR_NAMEDPIPEWAIT_ERROR

Не удалось дождаться именованного канала в Windows.

CR_NAMEDPIPESETSTATE_ERROR

Не удалось получить дескриптор для именованного канала в Windows.

CR_SERVER_LOST

Если connect_timeout> 0 и требуется более, чем connect_timeout секунд, чтобы соединиться с сервером, или если сервер свалился при выполнении init-command, вернется это.

2.3.175 Пример

MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");
if (!mysql_real_connect(&mysql,"host","user","passwd","database",
    0,NULL,0))
{
   fprintf(stderr, "Failed to connect to database: Error: %s\n",
           mysql_error(&mysql));
}

Используя mysql_options() библиотека клиентов MySQL будет читать группы [client] и your_prog_name в файле my.cnf, что гарантирует, что Ваша программа будет работать, даже если кто-то установил MySQL некоторым ненормативным способом.

Обратите внимание, что на подключение mysql_real_connect() устанавливает флажок reconnect (часть структуры MYSQL) в значение 1. Этот флажок указывает, что когда запрос не может выполниться из-за потерянного подключения, надо попробовать повторно соединиться с сервером перед отказом.

2.3.176 mysql_real_escape_string()

unsigned int mysql_real_escape_string(MYSQL *mysql, char *to, const char *from, unsigned int length)

2.3.177 Описание

Эта функция используется, чтобы создать допустимую строку, которую Вы можете использовать в инструкции SQL.

Строка в from бужет закодирована до экранированной строки SQL, принимая во внимание текущий (актуальный) набор символов подключения. Результат будет помещен в to и завершающий байт пустого указателя допишется автоматически. Символы NUL (ASCII 0), \n, \r, \, ', ", а также Control-Z, будуь экранированы.

Строка, указанная в from должна быть length байтов длины. Вы должны распределить буфер по крайней мере length*2+1 байт. В худшем случае каждый символ должен быть закодирован как использование двух байтов, и Вы нуждаетесь в участке памяти для завершающего байта пустого указателя. Когда mysql_escape_string() завершится, в to будет строка с нулевым байтом в конце. Значение возврата: длина закодированной строки, не включая символ завершения.

2.3.178 Пример

char query[1000],*end;

end = strmov(query,"INSERT INTO test_table values(");
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"What's this",11);
*end++ = '\'';
*end++ = ',';
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"binary data: \0\r\n",16);
*end++ = '\'';
*end++ = ')';

if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))
{
   fprintf(stderr, "Failed to insert row, Error: %s\n",
           mysql_error(&mysql));
}

Функция strmov(), используемая в примере, включена в библиотеку mysqlclient и работает подобно strcpy(), но возвращает указатель на завершающий символ первого параметра.

2.3.179 Возвращаемые значения

Длина значения, помещенного в to, не включая нулевой символ завершения.

2.3.180 Ошибки

Нет.

2.3.181 mysql_real_query()

int mysql_real_query(MYSQL *mysql, const char *query, unsigned int length)

2.3.182 Описание

Выполняет запрос SQL, указанный в query, который должен быть строкой длиной в length байт. Запрос должен состоять из одиночной инструкции SQL. Вы не должны добавлять точку с запятой (`;') или \g для завершения запроса.

Вы должны использовать mysql_real_query() вместо mysql_query() для запросов, которые содержат двоичные данные, потому, что двоичные данные могут сами содержать символ \0. Кроме того, mysql_real_query() быстрее, чем mysql_query() потому, что не вызывает strlen().

Если Вы хотите знать, возвратил ли запрос набор результатов или нет, Вы можете использовать mysql_field_count(), чтобы проверить это. Подробности в разделе "2.3.85 mysql_field_count()".

2.3.183 Возвращаемые значения

Ноль, если запрос был успешным. Отличное от нуля, если произошла ошибка.

2.3.184 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.185 mysql_reload()

int mysql_reload(MYSQL *mysql)

2.3.186 Описание

Просит, чтобы сервер MySQL перезагрузил таблицы предоставления привилегий. Пользователь должен иметь привилегию reload.

2.3.187 Возвращаемые значения

Ноль для успеха. Отличное от нуля, если произошла ошибка.

2.3.188 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.189 mysql_row_seek()

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)

2.3.190 Описание

Устанавливает курсор строки на произвольную строку в наборе результатов запросов. Это требует, чтобы структура набора результата содержала весь результат запроса, так что mysql_row_seek() может использоваться в конъюнкции только с mysql_store_result(), но не с mysql_use_result().

Смещение должно быть значением, возвращенным из mysql_row_tell() для mysql_row_seek(). Это значение не просто номер строки, если Вы хотите перейти к строке внутри набора результатов, используйте mysql_data_seek().

2.3.191 Возвращаемые значения

Предыдущее значение курсора строки. Это значение может быть передано последующему обращению к mysql_row_seek().

2.3.192 Ошибки

Нет.

2.3.193 mysql_row_tell()

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)

2.3.194 Описание

Возвращает текущую (актуальную) позицию курсора строки для последнего вызова mysql_fetch_row(). Это значение может использоваться как параметр для mysql_row_seek().

Вы должны использовать mysql_row_tell() только после mysql_store_result(), но не после mysql_use_result().

2.3.195 Возвращаемые значения

Текущее (актуальное) смещение курсора строки.

2.3.196 Ошибки

Нет.

2.3.197 mysql_select_db()

int mysql_select_db(MYSQL *mysql, const char *db)

2.3.198 Описание

Заставляет базу данных, определенную через db, стать заданной по умолчанию базой данных на подключении, определенном в mysql. В последующих запросах эта база данных будет значением по умолчанию для ссылок на таблицы, которые не включают явный спецификатор базы данных.

mysql_select_db() терпит неудачу, если связанный пользователь не имеет прав доступа, чтобы использовать базу данных.

2.3.199 Возвращаемые значения

Ноль для успеха. Отличное от нуля, если произошла ошибка.

2.3.200 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.201 mysql_shutdown()

int mysql_shutdown(MYSQL *mysql)

2.3.202 Описание

Выключает сервер. Связанный пользователь должен иметь привилегии закрытия системы (shutdown).

2.3.203 Возвращаемые значения

Ноль для успеха. Отличное от нуля, если произошла ошибка.

2.3.204 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.205 mysql_stat()

char *mysql_stat(MYSQL *mysql)

2.3.206 Описание

Возвращает символьную строку, содержащую информацию, подобную обеспечиваемой командой mysqladmin status. Это включает uptime в секундах, число работающих потоков, количество запросов, перезагрузок и открытых таблиц.

2.3.207 Возвращаемые значения

Символьная строка, описывающая состояние сервера. NULL, если произошла ошибка.

2.3.208 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.209 mysql_store_result()

MYSQL_RES *mysql_store_result(MYSQL *mysql)

2.3.210 Описание

Вы должны вызвать mysql_store_result() или mysql_use_result() для каждого запроса, который успешно получает данные (SELECT, SHOW, DESCRIBE, EXPLAIN).

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

Если Вы хотите знать, возвратил ли запрос набор результатов или нет, Вы можете использовать mysql_field_count(), чтобы проверить это. Подробности в разделе "2.3.85 mysql_field_count()".

mysql_store_result() читает весь результат запроса, распределяет структуру MYSQL_RES и помещает результат в эту структуру.

mysql_store_results() вернет пустой указатель, если запрос не возвращал набор результатов вообще (если запрос был, например, инструкцией INSERT).

mysql_store_results() также возвращает пустой указатель, если чтение набора результатов потерпело неудачу. Вы можете проверить, получили ли Вы ошибку, проверяя возвращает ли mysql_error() пустой указатель. Если mysql_errno() <> 0, или если mysql_field_count() <> 0, значит, ошибочка.

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

Как только Вы вызвали mysql_store_result() и получили результат, который не пустой указатель, Вы можете вызывать mysql_num_rows(), чтобы выяснить, сколько строк находится в наборе результатов.

Вы можете вызвать mysql_fetch_row(), чтобы выбрать строки из набора результатов, или mysql_row_seek() и mysql_row_tell(), чтобы получить или установить текущую позицию строки внутри набора результатов.

Вы должны вызвать mysql_free_result() как только Вы закончите работу с данным набором результатов.

2.3.211 Возвращаемые значения

Структура MYSQL_RES с результатами. NULL, если произошла ошибка.

2.3.212 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_OUT_OF_MEMORY

Не хватило памяти.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.3.213 mysql_thread_id()

unsigned long mysql_thread_id(MYSQL *mysql)

2.3.214 Описание

Возвращает ID потока текущего (актуального) подключения. Это значение может использоваться как параметр для mysql_kill(), чтобы уничтожить этот поток.

Если подключение потеряно, и Вы повторно соединяетесь через mysql_ping(), ID потока изменится. Это означает, что Вы не должны получить ID потока и хранить его. Надо получать ID по мере надобности.

2.3.215 Возвращаемые значения

ID потока текущего (актуального) подключения.

2.3.216 Ошибки

Нет.

2.3.217 mysql_use_result()

MYSQL_RES *mysql_use_result(MYSQL *mysql)

2.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 API выдает ошибку "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() как только Вы закончили с этим набором результатов.

2.3.219 Возвращаемые значения

Структура MYSQL_RES. NULL, если произошла ошибка.

2.3.220 Ошибки

CR_COMMANDS_OUT_OF_SYNC

Команды были выполнены в неподходящем порядке.

CR_OUT_OF_MEMORY

Не хватило памяти.

CR_SERVER_GONE_ERROR

Сервер MySQL занят.

CR_SERVER_LOST

Подключение было потеряно в течение запроса.

CR_UNKNOWN_ERROR

Произошла неизвестная ошибка.

2.4 Описание поточных функций C

Вы должны использовать следующие функции, когда Вы хотите создавать поточного клиента. Подробности в разделе "2.8 Как делать поточного клиента".

2.4.1 my_init()

2.4.2 Описание

Эта функция должна быть вызвана однажды в программе перед вызовом любой функции MySQL. Это инициализирует некоторые глобальные переменные. Если Вы используете поточно-безопасную библиотеку клиентов, это также вызовет для этого потока функцию mysql_thread_init().

Это автоматически вызвано функциями mysql_init(), mysql_server_init() и mysql_connect().

2.4.3 Возвращаемые значения

Нет.

2.4.4 mysql_thread_init()

2.4.5 Описание

Эту функцию должен запрашивать каждый созданный поток, чтобы инициализировать специфические переменные.

Это автоматически вызвано my_init() и mysql_connect().

2.4.6Возвращаемые значения

Нет.

2.4.7 mysql_thread_end()

2.4.8 Описание

Эта функция должна быть вызвана перед вызовом pthread_exit(), чтобы освободить память, распределенную в mysql_thread_init().

Обратите внимание, что эта функция не вызывается автоматически библиотекой. Это должно быть вызвано явно, чтобы избежать утечки памяти.

2.4.9 Возвращаемые значения

Нет.

2.5 Описание C-функций встроенного сервера

Вы должны использовать следующие функции, если Вы хотите, чтобы в Вашей прикладной программе была функциональность встроенного сервера MySQL. Подробности в разделе "2.9 libmysqld, библиотека встроенного сервера MySQL ".

Если программа скомпонована с -lmysqlclient вместо -lmysqld, эти функции не делают ничего. Это делает возможным выбирать между использованием встроенного и автономного сервера без изменения какого-либо кода.

2.5.1 mysql_server_init()

void mysql_server_init(int argc, const char **argv, const char **groups)

2.5.2 Описание

Эта функция должна быть вызвана в программе перед вызовом любой другой функции MySQL. Она запускает сервер и инициализирует все подсистемы (mysys, InnoDB и т.д.), используемые сервером. Если эта функция не была вызвана, программа разрушится.

Параметры argc и argv аналогичны параметрам main(). Первый элемент argv игнорируется (он обычно содержит имя программы). Для удобства argc может быть 0, если не имеется никаких параметров командной строки сервера.

Завершаемый символом NULL список строк в groups задает то, какие группы в файле опций будут активны. Для удобства groups может быть NULL, тогда будет активна группа [server].

2.5.3 Пример

#include <mysql.h>
#include <stdlib.h>

static char *server_args[] = {
  "this_program",       /* this string is not used */
  "--datadir=.",
  "--set-variable=key_buffer_size=32M"
};

static char *server_groups[] = {
  "server", "this_program_SERVER", (char *)NULL
};

int main(void) {
  mysql_server_init(sizeof(server_args) / sizeof(char *),
                    server_args, server_groups);
  /* Use any MySQL API functions here */
  mysql_server_end();
  return EXIT_SUCCESS;
}

2.5.4 Возвращаемые значения

Нет.

2.5.5 mysql_server_end()

2.5.6 Описание

Эта функция должна быть вызвана в программе, в конце. Она завершает сервер.

2.5.7 Возвращаемые значения

Нет.

2.6 Общие вопросы и проблемы при использовании C API

2.6.1 Почему при успехе mysql_query() вызов mysql_store_result() иногда возвращает NULL?

Когда это случается, это означает, что одно из следующего произошло:

• Имелся сбой malloc() (например, если набор результатов был слишком большой).
• Данные не могли прочитаться (произошла ошибка на подключении).
• Запрос не возвратил никакие данные (например, это был INSERT, UPDATE или DELETE).

Вы можете всегда проверить, должна или нет инструкция произвести непустой результат, вызывая mysql_field_count(). Если mysql_field_count() вернет ноль, результат пуст, и последний запрос был инструкцией, которая не возвращает значения (например, INSERT или DELETE). Если mysql_field_count() вернет не ноль, инструкция должна была произвести не пустой результат.

Вы можете проверить наличие ошибки вызовом mysql_error() или mysql_errno().

2.6.2 Какой результат я могу получить из запроса?

В дополнение к набору результатов, возвращенному запросом, Вы можете также получать следующую информацию:

• mysql_affected_rows() возвращает число строк, на которые воздействует последний запрос при выполнении INSERT, UPDATE или DELETE. Исключительная ситуация: DELETE используется без предложения WHERE, таблица будет пересоздана пустой, что намного быстрее! В этом случае mysql_affected_rows() возвращает ноль для числа записей.
• mysql_num_rows() возвращает число строк в наборе результатов. При использовании mysql_store_result() mysql_num_rows() может быть вызван, как только отработает mysql_store_result(). При использовании mysql_use_result() mysql_num_rows() может быть вызван только после того, как Вы выбрали все строки с помощью mysql_fetch_row().
• mysql_insert_id() возвращает ID, сгенерированный последним запросом, который вставил строку в таблицу с индексом AUTO_INCREMENT. Подробности в разделе "2.3.126 mysql_insert_id()".
• Некоторые запросы (LOAD DATA INFILE ..., INSERT INTO ... SELECT ..., UPDATE) возвращают дополнительную информацию. Результат возвращен через mysql_info(). mysql_info() вернет NULL если не имеется никакой дополнительной информации.

2.6.3 Как я могу получить уникальный ID для последней вставленной строки?

Если Вы вставляете запись в таблицу, содержащую столбец, который имеет атрибут AUTO_INCREMENT, Вы можете получать последнее значение ID вызовом mysql_insert_id().

Вы можете также получать ID, используя функцию LAST_INSERT_ID() в строке запроса, которую Вы передаете mysql_query().

Вы можете проверять, используется ли индекс AUTO_INCREMENT, выполняя следующий код. Это также проверит, был ли запрос INSERT с индексом AUTO_INCREMENT:

if (mysql_error(&mysql)[0] == 0 &&
    mysql_num_fields(result) == 0 && mysql_insert_id(&mysql) != 0)
{
   used_id = mysql_insert_id(&mysql);
}

Недавно сгенерированный ID хранится на сервере с привязкой к подключению. Это не будет изменено другим пользователем. Это не будет даже изменено, если Вы модифицируете другой столбец AUTO_INCREMENT не со специальным значением (то есть значением, которое не NULL и не 0).

Если Вы хотите использовать ID, который был сгенерирован для одной таблицы и вставлять его во вторую таблицу, Вы можете использовать инструкции SQL подобно этому:

INSERT INTO foo (auto,text)
    VALUES(NULL,'text');              # generate ID by inserting NULL
INSERT INTO foo2 (id,text)
    VALUES(LAST_INSERT_ID(),'text');  # use ID in second table

2.6.4 Проблемы компоновки с C API

При компоновке с C API следующие ошибки могут происходить на некоторых системах:

gcc -g -o client test.o -L/usr/local/lib/mysql -lmysqlclient -lsocket -lnsl
Undefined        first referenced
 symbol          in file
floor            /usr/local/lib/mysql/libmysqlclient.a(password.o)
ld: fatal: Symbol referencing errors. No output written to client

Если это случается на Вашей системе, Вы должны включить математическую библиотеку, добавляя -lm к концу строки для компоновки.

2.7 Построение клиентских программ

Если Вы компилируете MySQL клиентуру, которую вы написали самостоятельно или получили от третьего лица, программы должны быть скомпонованы, используя опцию -lmysqlclient -lz. Вы также должны определить опцию -L, чтобы сообщить компоновщику, где найти библиотеку. Например, если библиотека установлена в /usr/local/mysql/lib, используйте -L/usr/local/mysql/lib -lmysqlclient -lz на строке компоновки.

Для клиентуры, которая использует файлы заголовков MySQL, Вы должны определить опцию -I, когда Вы компилируете их (например, -I/usr/local/mysql/include), чтобы транслятор смог найти файлы.

2.8 Как делать поточные клиенты

Самая большая проблема состоит в том, что подпрограммы в net.c, которые читают из сокетов, не безопасны для прерываний. Это было выполнено с мыслью о том, что Вы могли бы иметь Вашу собственную функцию, которая может разорвать длинное чтение на сервер. Если Вы устанавливаете программы обработки прерывания для SIGPIPE, обработка сокета должна быть поточно-безопасной.

В старом двоичном коде библиотеки пользователей обычно не компилируются с опциями для поддержки поточной безопасности (код для Windows по умолчанию компилируются как поточно-безопасный). Более новые двоичные дистрибутивы имеют оба варианта библиотек.

Чтобы сделать поточный клиент, где Вы можете прерывать пользователя из других потоков и устанавливать времена ожидания при обмене данными с сервером MySQL, Вы должны использовать библиотеки -lmysys, -lstring и -ldbug, а также код net_serv.o, который использует сервер.

Если Вы не нуждаетесь в прерываниях или временах ожидания, Вы можете только скомпилировать поточно-безопасную библиотеку пользователей (mysqlclient_r) и использовать ее. В этом случае Вы не должны волноваться относительно объектного файла net_serv.o или других библиотек для MySQL.

При использовании поточного клиента, и если Вы хотите использовать времена ожидания и прерывания, Вы можете использовать код из файла thr_alarm.c. Если Вы используете подпрограммы из библиотеки mysys, Вы должны помнить, что нужно сначала вызвать my_init()! Подробности в разделе "2.4 Описание поточных функций C".

Все функции за исключением mysql_real_connect() по умолчанию безопасны для потоков. Следующие замечания описывают, как компилировать безопасную библиотеку клиентов и использовать ее соответственно. Замечания для mysql_real_connect() фактически применимы и для mysql_connect().

Чтобы сделать mysql_real_connect() поточно-безопасной, Вы должны перетранслировать библиотеку этой командой:

shell> ./configure --enable-thread-safe-client

Это создаст поточно-безопасную библиотеку libmysqlclient_r. Вы можете позволять двум потокам совместно использовать то же самое подключение, пока Вы делаете следующее:

• Два потока не могут посылать запрос MySQL в то же самое время на том же самом подключении. В частности Вы должны гарантировать, что между mysql_query() и mysql_store_result() другой поток никогда не использует то же самое подключение.
• Несколько потоков могут обращаться к различным наборам результатов, которые получены через mysql_store_result().
• Если Вы используете mysql_use_result, Вы должны гарантировать, что никакой другой поток не спрашивает что-нибудь относительно того же самого подключения, пока набор результатов не закрыт.
• Если Вы хотите использовать много потоков на том же самом подключении, Вы должны иметь блокировку mutex вокруг Вашей комбинации вызовов mysql_query() и mysql_store_result(). Когда mysql_store_result() готов, блокировка может быть снята, и другие потоки смогут сделать запрос с того же самого подключения.
• Если Вы программируете с потоками в стиле POSIX, Вы можете использовать pthread_mutex_lock() и pthread_mutex_unlock(), чтобы устанавливать и снимать блокировку mutex.

Вы должны знать следующее, если Вы имеете поток, который вызывает функции MySQL, но не создал подключение к базе данных MySQL:

Когда Вы вызываете mysql_init() или mysql_connect(), MySQL создаст специфические переменные для потока, которые используются библиотекой отладки.

Если Вы имеете в потоке вызов функции MySQL прежде, чем поток вызвал mysql_init() или mysql_connect(), поток не будет иметь необходимых специфических переменных, и Вы, вероятно, свалите программу в дамп рано или поздно (скорее рано, чем поздно). Чтобы работать спокойно, надо предпринять следующее:

1. Вызовите my_init() в начале Вашей программы, если она вызывает любую другую функцию MySQL, перед вызовом mysql_real_connect().
2. Вызовите mysql_thread_init() в драйвере потока перед вызовом любой функции MySQL.
3. В потоке вызовите mysql_thread_end() перед вызовом pthread_exit(). Это освободит память, используемую специфическими переменными MySQL.

Вы можете получать некоторые ошибки из-за неопределенных символов при компоновке Вашего клиента с mysqlclient_r. В большинстве случаев это потому, что Вы не включили библиотеки потоков в строку компоновки.

2.9 libmysqld, библиотека встроенного сервера MySQL

2.9.1 Обзор библиотеки встроенного сервера MySQL

Библиотека встроенного сервера MySQL делает возможным выполнить полнофункциональный сервер MySQL внутри прикладной программы. Основные выгоды: увеличивается быстродействие и упрощается управление.

2.9.2 Компиляция программ с libmysqld

В настоящее время, все библиотеки должны быть явно перечислены при компоновке с -lmysqld. В будущем mysql_config --libmysqld-libs назовет библиотеки, чтобы делать этот проще. Также, все библиотеки будут, вероятно, включены в libmysqld, чтобы упростить этот процесс еще сильнее.

Правильные флажки для компиляции и компоновки поточной программы должны использоваться, даже если Вы непосредственно не вызываете никакие функции потоков в Вашем коде.

2.9.3 Пример простого встроенного сервера

Эта программа должна работать без любых изменений на Linux или FreeBSD системе. Для других операционных систем будут необходимы маленькие изменения. Этот пример разработан, чтобы дать общее представление о том, как все делать.

Чтобы испытать пример, создайте каталог example в том же самом уровне, где лежит каталог с исходными текстами mysql-4.0. Сохраните в нем файлы example.c и GNUmakefile, после чего выполните GNU make из каталога example.

Файл example.c:

/*
 * A simple example client, using the embedded MySQL server library
 */
#include <mysql.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>

enum on_error {E_okay, E_warn, E_fail};

static void die(MYSQL *db, char *fmt, ...);
MYSQL *db_connect(const char *dbname);
void db_disconnect(MYSQL *db);
void db_do_query(MYSQL *db, const char *query, enum on_error on_error);

const char *server_groups[] = { "test_client_SERVER", "server", NULL };

int main(int argc, char **argv)
{
  MYSQL *one, *two;

  /* This must be called before any other mysql functions.
   *
   * You can use mysql_server_init(0, NULL, NULL), and it will
   * initialize the server using groups = { "server", NULL }.
   *
   * In your $HOME/.my.cnf file, you probably want to put:
[test_client_SERVER]
language = /path/to/source/of/mysql/sql/share/english

   * You could, of course, modify argc and argv before passing
   * them to this function. Or you could create new ones in any
   * way you like. But all of the arguments in argv (except for
   * argv[0], which is the program name) should be valid options
   * for the MySQL server.
   *
   * If you link this client against the normal mysqlclient
   * library, this function is just a stub that does nothing.
   */
  mysql_server_init(argc, argv, server_groups);
  one = db_connect("test");
  two = db_connect(NULL);
  db_do_query(one, "show table status", E_fail);
  db_do_query(two, "show databases", E_fail);
  mysql_close(two);
  mysql_close(one);

  /* This must be called after all other mysql functions */
  mysql_server_end();
  exit(EXIT_SUCCESS);
}

void die(MYSQL *db, char *fmt, ...)
{
  va_list ap;
  va_start(ap, fmt);
  vfprintf(stderr, fmt, ap);
  va_end(ap);
  putc('\n', stderr);
  if (db) db_disconnect(db);
  exit(EXIT_FAILURE);
}

MYSQL * db_connect(const char *dbname)
{
  MYSQL *db = mysql_init(NULL);
  if (!db) die(db, "mysql_init failed: no memory");
  mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "simple");
  if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0))
     die(db, "mysql_real_connect failed: %s", mysql_error(db));
  return db;
}

void db_disconnect(MYSQL *db)
{
  mysql_close(db);
}

/*
 * show_query: this code is snagged from mysql.cc; this function
 * is intended to be used internally to db_do_query()
 */
static char * show_query(MYSQL *db)
{
  MYSQL_RES   *res;
  MYSQL_FIELD *field;
  MYSQL_ROW    row;
  char sep[256], *psep = sep;
  char *is_num = 0;
  char *err = 0;
  unsigned int length = 1;      /* initial "|" */
  unsigned int off;

  if (!(res = mysql_store_result(db))) return mysql_error(db);
  if (!(is_num = malloc(mysql_num_fields(res))))
  {
     err = "Не хватило памяти";
     goto err;
  }
  /* set up */
  *psep++ = '+';
  while ((field = mysql_fetch_field(res)))
  {
    unsigned int len = strlen(field->name);
    if (len < field->max_length) len = field->max_length;
    if (len < 2 && !IS_NOT_NULL(field->flags)) len = 2; /* \N */
    field->max_length = len + 1;    /* bending the API... */
    len += 2; length += len + 1;        /* " " before, " |" after */
    if (length >= 255)
    {
       err = "row too long";
       goto err;
    }
    memset(psep, '-', len); psep += len;
    *psep++ = '+';
    *psep   = '\0';
  }
  /* column headings */
  puts(sep);
  mysql_field_seek(res,0);
  fputc('|',stdout);
  for (off=0; (field = mysql_fetch_field(res)) ; off++)
  {
    printf(" %-*s|",field->max_length, field->name);
    is_num[off]= IS_NUM(field->type);
  }
  fputc('\n',stdout);
  puts(sep);
  /* rows */
  while ((row = mysql_fetch_row(res)))
  {
    (void) fputs("|",stdout);
    mysql_field_seek(res,0);
    for (off=0; off < mysql_num_fields(res); off++)
    {
      field = mysql_fetch_field(res);
      printf(is_num[off] ? "%*s |" : " %-*s|",
             field->max_length, row[off] ? (char*) row[off] : "NULL");
    }
    (void) fputc('\n',stdout);
  }
  puts(sep);
err:
  if (is_num) free(is_num);
  mysql_free_result(res);
  return err;
}

void db_do_query(MYSQL *db, const char *query, enum on_error on_error)
{
  char *err = 0;

  if (mysql_query(db, query) != 0) goto err;
  if (mysql_field_count(db) > 0)
  {
     if ((err = show_query(db))) goto err;
  }
  else if (mysql_affected_rows(db))
          printf("Affected rows: %lld [%s]\n",
                 mysql_affected_rows(db),query);
  return;
err:
  switch (on_error)
  {
    case E_okay: break;
    case E_warn:
      fprintf(stderr, "db_do_query failed: %s [%s]\n",
              err ? err : mysql_error(db), query);
      break;
    case E_fail:
      die(db, "db_do_query failed: %s [%s]",
          err ? err : mysql_error(db), query);
      break;
  }
}

Файл GNUmakefile:

# Set this to your mysql source directory
m        := ../mysql-4.0
CC       := cc
CPPFLAGS := -I$m/include -D_THREAD_SAFE -D_REENTRANT
CFLAGS   := -g -W -Wall
LDFLAGS  := -static
LDLIBS    = $(embed_libs) -lz -lm -lcrypt

ifneq (,$(shell grep FreeBSD /COPYRIGHT 2>/dev/null))
# FreeBSD
LDFLAGS += -pthread
else
# Assume Linux
LDLIBS += -lpthread
endif

# Standard libraries
embed_libs := \
        $m/libmysqld/.libs/libmysqld.a \
        $m/isam/libnisam.a \
        $m/myisam/libmyisam.a \
        $m/heap/libheap.a \
        $m/merge/libmerge.a \
        $m/myisammrg/libmyisammrg.a

# Optionally-built libraries
ifneq (,$(shell test -r $m/innobase/usr/libusr.a && echo "yes"))
embed_libs += \
        $m/innobase/usr/libusr.a \
        $m/innobase/odbc/libodbc.a \
        $m/innobase/srv/libsrv.a \
        $m/innobase/que/libque.a \
        $m/innobase/srv/libsrv.a \
        $m/innobase/dict/libdict.a \
        $m/innobase/ibuf/libibuf.a \
        $m/innobase/row/librow.a \
        $m/innobase/pars/libpars.a \
        $m/innobase/btr/libbtr.a \
        $m/innobase/trx/libtrx.a \
        $m/innobase/read/libread.a \
        $m/innobase/usr/libusr.a \
        $m/innobase/buf/libbuf.a \
        $m/innobase/ibuf/libibuf.a \
        $m/innobase/eval/libeval.a \
        $m/innobase/log/liblog.a \
        $m/innobase/fsp/libfsp.a \
        $m/innobase/fut/libfut.a \
        $m/innobase/fil/libfil.a \
        $m/innobase/lock/liblock.a \
        $m/innobase/mtr/libmtr.a \
        $m/innobase/page/libpage.a \
        $m/innobase/rem/librem.a \
        $m/innobase/thr/libthr.a \
        $m/innobase/com/libcom.a \
        $m/innobase/sync/libsync.a \
        $m/innobase/data/libdata.a \
        $m/innobase/mach/libmach.a \
        $m/innobase/ha/libha.a \
        $m/innobase/dyn/libdyn.a \
        $m/innobase/mem/libmem.a \
        $m/innobase/sync/libsync.a \
        $m/innobase/ut/libut.a \
        $m/innobase/os/libos.a \
        $m/innobase/ut/libut.a
endif

ifneq (,$(shell test -r $m/bdb/build_unix/libdb.a && echo "yes"))
embed_libs += $m/bdb/build_unix/libdb.a
endif

# Support libraries
embed_libs += \
        $m/mysys/libmysys.a \
        $m/strings/libmystrings.a \
        $m/dbug/libdbug.a \
        $m/regex/libregex.a

# Optionally built support libraries
ifneq (,$(shell test -r $m/readline/libreadline.a && echo "yes"))
embed_libs += $m/readline/libreadline.a
endif

# This works for simple one-file test programs
sources := $(wildcard *.c)
objects := $(patsubst %c,%o,$(sources))
targets := $(basename $(sources))

all: $(targets)

clean:
  rm -f $(targets) $(objects) *.core

2.9.4 Лицензирование встроенного сервера

Исходный текст MySQL охвачен GNU GPL. Один результат этого: любая программа, которая компонуется с libmysqld и с исходным текстом MySQL, должна быть выпущена как свободное программное обеспечение (согласно лицензии, совместимой с GPL).

Авторы поощряют каждого поддерживать свободное программное обеспечение, выпуская код под GPL или совместимой лицензией. Для тех, кто не способен делать это, есть другой вариант: они должны приобрести MySQL у MySQL AB согласно более свободной лицензии.

содержание       назад       вперед