Справочное руководство по MySQL версии 4.1.1-alpha
Обзор функций интерфейса C
В приведенной ниже таблице перечислены доступные в интерфейсе C функции. Более детально они описаны в следующем разделе (see section 8.4.3 Описание функций интерфейса C).
Возвращает количество строк, измененных/удаленных/вставленных последним запросом UPDATE, DELETE или INSERT.
| mysql_fetch_row() | Извлекает следующую строку из результирующего набора. |
| mysql_field_seek() | Устанавливает курсор столбцов на заданный столбец. |
| mysql_field_count() | Возвращает количество столбцов в результате для последнего запроса. |
| mysql_field_tell() | Возвращает значение положения курсора поля для последнего вызова mysql_fetch_field(). |
| mysql_free_result() | Освобождает память, использованную для результирующего набора. |
| mysql_get_client_info() | Возвращает информацию о версии клиента. |
| mysql_get_host_info() | Возвращает строку, описывающую параметры текущего соединения. |
| mysql_get_server_version() | Возвращает номер версии сервера как целое число (новое с 4.1) |
| mysql_get_proto_info() | Возвращает версию протокола, используемого для данного соединения. |
| mysql_get_server_info() | Возвращает номер версии сервера баз данных. |
| mysql_info() | Возвращает информацию о последнем выполненном запросе. |
| mysql_init() | Выделяет или инициализирует какую-либо структуру MYSQL. |
| mysql_insert_id() | Возвращает идентификатор, сгенерированный для столбца AUTO_INCREMENT предыдущим запросом. |
| mysql_kill() | Уничтожает заданный поток. |
| mysql_list_dbs() | Возвращает имена баз данных, совпадающие с простым регулярным выражением. |
| mysql_list_fields() | Возвращает имена полей, совпадающих с простым регулярным выражением. |
| mysql_list_processes() | Возвращает список текущих потоков на сервере. |
| mysql_list_tables() | Возвращает имена таблиц, совпадающих с простым регулярным выражением. |
| mysql_num_fields() | Возвращает количество столбцов в результирующем наборе. |
| mysql_num_rows() | Возвращает количество строк в результирующем наборе. |
| mysql_options() | Устанавливает параметры соединения для mysql_connect(). |
| mysql_ping() | Проверяет, работает ли данное соединение с сервером, и восстанавливает соединение при необходимости. |
| mysql_query() | Выполняет SQL-запрос, заданный в виде строки с нулевым символом в конце. |
| mysql_real_connect() | Создает соединение с сервером баз данных MySQL. |
| mysql_real_escape_string() | Экранирует специальные символы в строке, чтобы обеспечить возможность использования ее в команде SQL, с учетом установленной для данного соединения кодировки. |
| mysql_real_query() | Выполняет SQL-запрос, заданный в виде фиксированной строки. |
| mysql_reload() | Предписывает серверу перегрузить таблицы привилегий. |
| mysql_row_seek() Устанавливает курсор на заданную строку в результирующем наборе, используя величину, возвращенную из mysql_row_tell(). | |
| mysql_row_tell() | Возвращает положение курсора строки. |
| mysql_select_db() | Выбирает базу данных. |
| mysql_shutdown() | Останавливает сервер баз данных. |
| mysql_stat() | Возвращает информацию о текущем статусе сервера баз данных в виде строки. |
| mysql_store_result() | Извлекает полный результирующий набор для данного клиента. |
| mysql_thread_id() | Возвращает идентификатор текущего потока. |
| mysql_thread_safe() | Возвращает 1, если клиенты скомпилированы как поддерживающие потоки. |
| mysql_use_result() | Инициализирует построчное извлечение результирующего набора. |
При подсоединения к серверу необходимо вызвать функцию mysql_init() для инициализации дескриптора соединения, затем с этим дескриптором вызвать функцию mysql_real_connect() (которая содержит такую информацию, как имя данного хоста, имя пользователя и пароль). После соединения функция 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() может быть быстрее). Недостатками являются: необходимость обрабатывать каждую строку быстро, чтобы избежать связывания сервера, невозможность произвольного доступа к строкам внутри результирующего набора (возможен только последовательный доступ к строкам), невозможность узнать количество строк в результирующем наборе до его полного извлечения. Более того, необходимо извлекать все строки, даже если в середине извлечения станет ясно, что искомая информация найдена.
Благодаря интерфейсу клиенты получают возможность соответствующим образом реагировать на запросы (извлекать строки только при необходимости) без уточнения, являлся или нет данный запрос выборкой. Это можно делать, вызывая функцию mysql_store_result() после каждого вызова mysql_query() (или mysql_real_query()). Если вызов результирующего набора был успешным, то данный запрос принадлежал к виду SELECT и можно производить чтение строк. Если вызов результирующего набора не удался, можно вызвать функцию mysql_field_count() для определения, можно ли было действительно ожидать результат. Если mysql_field_count() возвращает нуль, то данный запрос не возвратил никаких данных (это указывает, что запрос был вида INSERT, UPDATE, DELETE и т.д.), и не следовало ожидать возвращенных строк. Если функция mysql_field_count() является ненулевой, данный запрос должен был возвратить результат, но не сделал этого. Это указывает, что данный запрос был типа SELECT, но его выполнение оказалось неуспешным (см. пример в описании функции mysql_field_count()).
Как 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(). Они возвращают код ошибки или сообщение об ошибке для последней запущенной функции (которая может быть успешной или не выполниться), позволяя определить место возникновения и характер ошибки.
