[ новости /+++ | форум | теги | ]

Каталог документации / Раздел "Базы данных, SQL" / Оглавление документа

6 MySQL DELPHI API

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

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

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

6.1 Типы данных в DELPHI API

TMYSQL

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

TMYSQL_RES

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

TMYSQL_ROW

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

TMYSQL_FIELD

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

TMYSQL_FIELD_OFFSET

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

Tmy_ulonglong

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

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

name:pchar;

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

table:pchar;

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

def:pchar;

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

typ:TFIELD_TYPES;

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

Значение Typ	Используемый тип
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

length:longword;

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

max_length:longword;

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

flags:longword;

Различные биты задают флажки для поля. Значение 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
BLOB_FLAG	Поле имеет тип BLOB или TEXT
TIMESTAMP_FLAG	Поле имеет тип TIMESTAMP

Использование BLOB_FLAG, ENUM_FLAG и TIMESTAMP_FLAG не рекомендуется потому, что они указывают тип поля, а не атрибут типа. Предпочтительно проверить field.typ вместо FIELD_TYPE_BLOB, FIELD_TYPE_ENUM или FIELD_TYPE_TIMESTAMP. Пример ниже иллюстрирует типичное использование flags:

if (field.flags & NOT_NULL_FLAG) write("Field can't be null");

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

IS_NOT_NULL(flags)	Истина, если это поле определено как NOT NULL
IS_PRI_KEY(flags)	Истина, если это поле первичный ключ
IS_BLOB(flags)	Истина, если это поле BLOB или TEXT

decimals:longword;

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

6.2 Обзор функций Delphi API

Функции, доступные в Delphi API, перечислены ниже и описаны более подробно в следующем разделе. Подробности в разделе "Описание функций Delphi 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(). Они возвращают код ошибки или сообщение об ошибке для последней вызванной функции, позволяя Вам определить, когда ошибка произошла, и что это было.

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

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

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

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

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

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

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

6.3.1 mysql_affected_rows()

tmy_ulonglong mysql_affected_rows(mysql:PMYSQL):TMY_ULONGLONG; stdcall;

Описание

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

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

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

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

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

6.3.2 mysql_close()

mysql_close(sock:PMYSQL);stdcall;

Описание

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

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

Нет.

6.3.3 mysql_connect()

mysql_connect(mysql: PMYSQL; const host,user,passwd:pchar):PMYSQL; stdcall;

Описание

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

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

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

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

Ошибки

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

6.3.4 mysql_change_user()

mysql_change_user(mysql: PMYSQL; const user,passwd, db:pchar):TMY_BOOL;stdcall;

Описание

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

Эта функция впервые была представлена в MySQL Version 3.23.3.

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

Параметр db может быть установлен в NULL, если Вы не хотите иметь заданную по умолчанию базу данных.

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

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

Ошибки

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

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

ER_UNKNOWN_COM_ERROR

Сервер MySQL не выполняет эту команду (вероятно, старая версия).

ER_ACCESS_DENIED_ERROR

Пользователь или пароль ошибочен.

ER_BAD_DB_ERROR

База данных не существует.

ER_DBACCESS_DENIED_ERROR

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

ER_WRONG_DB_NAME

Имя базы данных слишком длинное.

6.3.5 mysql_create_db()

mysql_create_db(mysql:PMYSQL; const db:pchar):integer;stdcall;

Описание

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

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.6 mysql_data_seek()

mysql_data_seek(res:PMYSQL_RES;offset:TMY_ULONGLONG); stdcall;

Описание

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

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

6.3.7 mysql_debug()

mysql_debug(const debug:pchar);stdcall;

Описание

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

Пример

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

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

6.3.8 mysql_drop_db()

mysql_drop_db(mysql:PMYSQL; const db:pchar):integer;stdcall;

Описание

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

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.9 mysql_dump_debug_info()

mysql_dump_debug_info(mysql:PMYSQL):integer;stdcall;

Описание

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

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.10 mysql_eof()

mysql_eof(res:PMYSQL_RES):TMY_BOOL;stdcall;

Описание

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() возвращает только булево значение, в то время как функции ошибки указывают причину.

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

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

6.3.11 mysql_errno()

mysql_errno(mysql:PMYSQL):longword;stdcall;

Описание

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

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

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

6.3.12 mysql_error()

mysql_error(mysql:PMYSQL):pchar;stdcall;

Описание

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

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

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

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

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

6.3.13 mysql_escape_string()

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

6.3.14 mysql_fetch_field()

mysql_fetch_field(res:PMYSQL_RES):PMYSQL_FIELD;stdcall;

Описание

Возвращает определение одного столбца набора результатов как структуру 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 хранит длину самого большого значения для этого столбца в специфическом запросе.

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

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

6.3.15 mysql_fetch_fields()

mysql_fetch_fields(res:PMYSQL_RES):PMYSQL_FIELDS;stdcall;

Описание

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

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

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

6.3.16 mysql_fetch_field_direct()

mysql_fetch_field_direct(res:PMYSQL_RES; fieldnr:integer):PMYSQL_FIELD;stdcall;

Описание

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

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

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

6.3.17 mysql_fetch_lengths()

mysql_fetch_lengths(res:PMYSQL_RES):longword;stdcall;

Описание

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

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

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

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

Ошибки

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

6.3.18 mysql_fetch_row()

mysql_fetch_row(res:PMYSQL_RES):PMYSQL_ROW;stdcall;

Описание

Получает следующую строку набора результатов. Когда используется после 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, иначе поле пустое.

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

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

Ошибки

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.19 mysql_field_count()

mysql_field_count(mysql:PMYSQL):longword;stdcall;

Если Вы используете версию MySQL ранее, чем Version 3.22.24, Вы должны вместо этого использовать mysql_num_fields(res:PMYSQL_RES):longword; stdcall;.

Описание

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

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

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

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

6.3.20 mysql_field_seek()

mysql_field_seek(res:PMYSQL_RES; offset:TMYSQL_FIELD_OFFSET): TMYSQL_FIELD_OFFSET; stdcall;

Описание

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

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

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

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

6.3.21 mysql_field_tell()

mysql_field_tell(res:PMYSQL_RES):longword;stdcall;

Описание

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

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

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

6.3.22 mysql_free_result()

mysql_free_result(res:PMYSQL_RES);stdcall;

Описание

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

6.3.23 mysql_get_client_info()

mysql_get_client_info:pchar;stdcall;

Описание

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

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

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

6.3.24 mysql_get_host_info()

mysql_get_host_info(mysql:PMYSQL):pchar;stdcall;

Описание

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

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

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

6.3.25 mysql_get_proto_info()

mysql_get_proto_info(mysql:PMYSQL):longword;stdcall;

Описание

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

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

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

6.3.26 mysql_get_server_info()

mysql_get_server_info(mysql:PMYSQL):pchar;stdcall;

Описание

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

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

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

6.3.27 mysql_info()

mysql_info(mysql:PMYSQL):pchar;stdcall;

Описание

Возвращает строку, обеспечивающую информацию относительно недавно выполненного запроса, но только для инструкций, перечисленных ниже. Для других инструкций 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 только, если много списков значений было определено в инструкции.

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

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

6.3.28 mysql_init()

mysql_init(mysql: PMYSQL):PMYSQL;stdcall;

Описание

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

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

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

Ошибки

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

6.3.29 mysql_insert_id()

mysql_insert_id(mysql:PMYSQL):TMY_ULONGLONG;stdcall;

Описание

Возвращает 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, и оно не будет сброшено между запросами потому, что значение этой функции поддерживается сервером.

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

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

6.3.30 mysql_kill()

mysql_kill(mysql:PMYSQL;pid:longword):integer;stdcall;

Описание

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

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.31 mysql_list_dbs()

mysql_list_dbs(mysql:PMYSQL;const wild:pchar):PMYSQL_RES;stdcall;

Описание

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

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

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_OUT_OF_MEMORY

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.32 mysql_list_fields()

mysql_list_fields(mysql:PMYSQL;const table,wild:pchar):PMYSQL_RES; stdcall;

Описание

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

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

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

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.33 mysql_list_processes()

mysql_list_processes(mysql:PMYSQL):PMYSQL_RES;stdcall;

Описание

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

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

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.34 mysql_list_tables()

mysql_list_tables(mysql:PMYSQL;const wild:pchar):PMYSQL_RES;stdcall;

Описание

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

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

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.35 mysql_num_fields()

mysql_num_fields(res:PMYSQL_RES):longword;stdcall;

Описание

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

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

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

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

6.3.36 mysql_num_rows()

mysql_num_rows(res:PMYSQL_RES):TMY_ULONGLONG;stdcall;

Описание

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

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

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

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

6.3.37 mysql_options()

mysql_options(mysql:PMYSQL;option:TMYSQL_OPTION; const arg:pchar):integer;stdcall;

Описание

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

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 будет все еще работать некоторое время для совместимости.

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

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

6.3.38 mysql_ping()

mysql_ping(mysql:PMYSQL):integer;stdcall;

Описание

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

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

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_UNKNOWN_ERROR

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

6.3.39 mysql_query()

mysql_query(mysql:PMYSQL; const q:pchar):integer;stdcall;

Описание

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

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

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.40 mysql_real_connect()

mysql_real_connect(mysql: PMYSQL; const host,user,passwd,db:pchar; port:longword; const unix_socket:pchar; clientflag:longword):PMYSQL;stdcall;

Описание

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

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

• Первый параметр должен быть адресом существующей структуры типа TMYSQL. Перед вызовом mysql_real_connect() Вы должны вызвать mysql_init(), чтобы инициализировать структуру TMYSQL. Вы можете изменять много параметров подключения через вызов 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.

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

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

Ошибки

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, вернется это.

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

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

6.3.41 mysql_real_escape_string()

mysql_real_escape_string(mysql:PMYSQL; wto:pchar; const wfrom:pchar; wfromlength:longword):longword;stdcall;

Описание

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

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

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

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

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

6.3.42 mysql_real_query()

mysql_real_query(mysql:PMYSQL; const q:pchar; length:longword):integer;stdcall;

Описание

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

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

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

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.43 mysql_reload()

mysql_reload(mysql:PMYSQL):integer;stdcall;

Описание

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

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.44 mysql_row_seek()

mysql_row_seek(res:PMYSQL_RES; offset:PMYSQL_ROW_OFFSET):PMYSQL_ROW_OFFSET;stdcall;

Описание

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

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

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

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

6.3.45 mysql_row_tell()

mysql_row_tell(res:PMYSQL_RES):PMYSQL_ROWS;stdcall;

Описание

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

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

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

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

6.3.46 mysql_select_db()

mysql_select_db(mysql:PMYSQL; const db:pchar):integer;stdcall;

Описание

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

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

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.47 mysql_shutdown()

mysql_shutdown(mysql:PMYSQL):integer;stdcall;

Описание

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

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.48 mysql_stat()

mysql_stat(mysql:PMYSQL):pchar;stdcall;

Описание

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

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.49 mysql_store_result()

mysql_store_result(mysql:PMYSQL):PMYSQL_RES;stdcall;

Описание

Вы должны вызвать 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() , чтобы проверить это.

mysql_store_result() читает весь результат запроса, распределяет структуру TMYSQL_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() как только Вы закончите работу с данным набором результатов.

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_OUT_OF_MEMORY

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

6.3.50 mysql_thread_id()

mysql_thread_id(mysql:PMYSQL):longword;stdcall;

Описание

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

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

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

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

6.3.51 mysql_use_result()

mysql_use_result(mysql:PMYSQL):PMYSQL_RES;stdcall;

Описание

Вы должны вызвать 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, иначе невыбранные строки будут возвращены как часть набора результатов для Вашего следующего запроса. 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() как только Вы закончили с этим набором результатов.

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

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

Ошибки

CR_COMMANDS_OUT_OF_SYNC

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

CR_OUT_OF_MEMORY

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

CR_SERVER_GONE_ERROR

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

CR_SERVER_LOST

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

CR_UNKNOWN_ERROR

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

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

6.4.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().

6.4.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. Подробности в разделе "6.3.126 mysql_insert_id()".
• Некоторые запросы (LOAD DATA INFILE ..., INSERT INTO ... SELECT ..., UPDATE) возвращают дополнительную информацию. Результат возвращен через mysql_info(). mysql_info() вернет NULL если не имеется никакой дополнительной информации.

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

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

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

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

if (mysql_error(pmysql)[0]=0) && (mysql_num_fields(result)=0) &&
   (mysql_insert_id(pmysql) != 0) then begin
   used_id := mysql_insert_id(pmysql);
end;

Недавно сгенерированный 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

Партнёры:

Хостинг: