• Глава N19. Справочник С
• MySQL С API
• mSQLCAPI

Глава N19.

Справочник С

MySQL С API

MySQL С API кроме стандартных типов данных языка С использует некоторые свои типы данных. Они определены в заголовочном файле 'mysql.h', который необходимо подключать при компиляции всех программ, использующих библиотеку MySQL.

Типы данных

MYSQL

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

MYSQL_FIELD

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

char *name

Имя поля.

char *table

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

char *def

Значение по умолчанию этого поля, если таковое существует. Это значение всегда будет null до вызова mysql_list_f ields, после чего в переменной будет корректное значение для полей, у которых есть значение по умолчанию.

еnum enum_field_types type

Тип поля. Он является одним из типов данных MySQL SQL.

unsigned int length

Размер поля, основанный на типе поля.

unsigned int max_length

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

unsigned int flags

Ноль или более флагов. В настоящее время определены следующие флаги:

NOT_NULL_FLAG

Если установлен, поле не может содержать значение

NULL. PRI_KEY_FLAG

Если установлен, поле является первичным ключом.

UNIQUE_KEY_FLAG

Если установлен, поле является частью уникального ключа.

MULTIPLE_KEY_FLAG

Если установлен, поле является частью ключа.

BLOB_FLAG

Если установлен, поле имеет тип BLOB или TEXT.

UNSIGNED_FLAG

Если установлен, поле имеет числовой тип и содержит беззнаковое значение.

ZEROFILL_FLAG

Если установлен, поле было создано с флагом ZEROFILL.

BINARY_FLAG

Если установлен, поле имеет тип CHAR или VARCHAR с флагом BINARY.

ENUM_FLAG

Если установлен, поле имеет тип ENUM.

AUTO_INCREMENT_FLAG

Если установлен, поле имеет атрибут AUTO_INCREMENT.

TIMESTAMP_FLAG

Если установлен, поле имеет тип TIMESTAMP.

unsigned int decimals

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

Для облегчения использования данных MYSQL_FIELD созданы следующие макросы:

IS_PRI_KEY( flags)

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

IS_NOT_NULL(flags)

Возвращает true, если поле имеет ограничение NOT NULL.

IS_ELOE(flags)

Возвращает true, если поле имеет тип BLOB или TEXT.

IS_NUM(type)

Возвращает true, если тип поля является числовым.

MYSQL_FIELD_OFFSET

Числовой тип, указывающий на позицию «курсора» в строке (записи).

MYSQL_RES

Структура, содержащая результат команды SELECT (или SHOW). Доступ к данным из запросов следует осуществлять через элемент этой структуры MYSQL_ROW.

MYSQL_ROW

Одна запись из данных, возвращаемых запросом SELECT. Все результаты, полученные от MySQL, хранятся в этом типе (как массив символьных строк).

my_ulonglong

Числовой тип, используемый для кодов возврата MySQL. Значение может находиться в диапазоне от 0 до 1.8Е19, и —1 используется для указания на ошибку.

my sql_affected_ro ws

my_ulonglong mysql_affected_rows(MYSQL*mysql)

Возвращает число записей, измененных последним запросом. При использовании с запросом SELECT эта функция идентична mysql_num_rows (вернет число записей в результирующем наборе). С остальными запросами функция может быть использована после вызова mysql_query, которая послала запрос.

Пример

/* Вставить запись в таблицу 'people' */

mysql_query(&mysql, "INSERT INTO people VALUES ('', 'Illyana Rasputin',

16)";

num = fflysql_affected_rows(&mysql);

/* Если операция INSERT удалась, переменная num должна быть равна 1, и -1, если произошла ошибка */

mysql_close

void mysql_close(MYSQL*mysql)

Завершает соединение с сервером баз данных MySQL. Если при разрыве соединения возникли проблемы, сообщение об ошибке можно посмотреть, используя функцию mysql_err.

Пример

mysql_close(&mysql);

/* Теперь подключение должно быть завершено */

mysql_connect

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

Создает подключение к серверу баз данных MySQL. Первым параметром должна быть предварительно объявленная структура MYSQL. Второй параметр - это имя хоста или IP-адрес сервера MySQL. Если хост задан пустой строкой или как localhost, будет выполнено подключение к серверу MySQL на той же машине. Последние два параметра -это используемые для подключения имя пользователя и пароль. Пароль вводится открытым текстом и не шифруется. Функция возвращает структуру MYSQL, переданную первым аргументом, либо NULL, если соединение не было установлено. (Так как структура содержится в аргументе, единственное применение возвращаемого значения - это проверка успешности подключения.)

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

Пример

/* Создать подключение к локальному серверу MySQL, используя имя "bob" и

пароль "mypass" */ MYSQL mysql;

if(!mysql_connect(&mysql, "", "bob", "mypass")) {

printf("Oшибкa при подключении!\n");

exit(0); }

/* Если мы дошли сюда, значит, успешно подключились к серверу баз данных*/

mysql_create_db

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

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

Эта функция потеряла значение в последних версиях MySQL. Теперь MySQL поддерживает оператор SQL CREATE DATABASE. Следует использовать его с помощью функции mysql_query.

Пример

/* Создать новую базу данных 'new_database' */

result = mysql_create_db(&mysql, "new_database");

mysql_data_seek

void mysql_data_seek(MYSQL_RES*res, unsigned int offset)

Передвигает курсор на определенную запись в наборе записей. Первый аргумент является структурой MYSQL_RES, которая содержит записи. Второй аргумент указывает на номер записи, которую вы хотите найти. Номер первой записи - 0. Эта функция работает, только если данные были выбраны с помощью mysql_store_ result.

Пример

/* Перейти к последней записи в результате */

mysql_data_seek(results, mysql_num_rows(results)-1);

mysql_debug

mysql_debug(char *debug)

Управляет отладочными функциями, если при компиляции клиента была разрешена отладка. MySQL использует отладочную библиотеку Fred Fish, которая имеет слишком много параметров и особенностей, чтобы быть описанной в этой книге.

Пример

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

клиентских программ записывается в файл "debug.out"*/

mysql_debug("d:t:0, debug. out");

mysql_drop_db

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

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

Эта функция потеряла значение в последних версиях MySQL. Теперь MySQL поддерживает оператор SQL DROP DATABASE. Его следует использовать через mysql_query вместо функции mysql_drop_db.

Пример

/* Уничтожить базу данных 'old_database' */

result = mysql_drop_db(&mysql, "old_database");

mysql_dump_debug_info

int mysql_dump_debug_info(MYSQL*mysql)

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

Пример

result = mysql_dump_debug_info(&mysql);

/* Теперь журналы сервера должны содержать информацию о текущем

подключении */

mysql_eof

my_bool mysql_eof(MYSQL_RES* result)

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

Пример

/* Прочитать до конца набор записей */

while((row = mysql_fetch_row( results.))) {

/'Обработка 7 }

if(!mysql_eof(results))

{

printf("Ошибка. Конец результата не достигнут.\n");

mysql_errno

unsigned int mysql_errno(MYSQL*mysql)

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

Пример

error = mysql_errno(&mysql);

printf("HoMep последней ошибки: %d\n", error);

mysql_error

char *mysql_error(MYSQL*mysql)

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

Пример

printf("Последняя ошибка была: '%s'\n", mysql_error(&mysql));

mysq l_esca pe_strin g

unsigned int mysql_escape_string(char*to, const char "from, unsigned int

length)

unsigned int mysql_escape_string(char*to, const char *from)

Кодирует строку таким образом, что ее можно безопасно вставить в таблицу MySQL. Первый аргумент - это получающая строка, которая должна быть по крайней мере на один символ больше двойной длины исходной строки, задаваемой вторым аргументом (то есть to >= from*2+l). Если есть третий аргумент, он указывает количество байт, копируемое из исходной строки перед кодированием. Функция возвращает число байт в кодированной строке, исключая цустой символ в конце строки.

Пример

char name[15] = "Bob Marley's";

char enc_name[31];

mysql_escape_string(enc_name, name);

/* enc_name теперь будет содержать "Bob Marley\'s" (единичная кавычка

закодирована).

mysql_fetch_field

MYSQL_FIELD*mysql_fetch_field(MYSQL_RES* result)

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

Пример

MYSQL_FIELD*field;

while((field = mysql_fetch_field(results)))

{

/* Здесь вы можете проверить информацию о поле */

}

mysql_fetch_field_direct

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

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

Пример

MYSQL_FIELD *field;

/* Получить информацию о третьем поле в наборе записей */

field = mysql_fetch_field_direct(results, 2);

mysql_fetch_fields

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES* result)

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

Пример

MYSQL_FIELD 'field; MYSQL_FIELD 'fields;

/* Получить всю информацию о полях в наборе записей */

fields = mysql_fetch_fields(results);

/* Приписать третье поле переменной 'field' */

field = fields[2];

mysql_fetch_lengths

unsigned long *mysql_fetch_lengths(MYSQL_RES*result)

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

Пример

unsigned long *lengths;

row = mysql_fetch_row(results);

lengths = mysql_fetch_lengths(results);

printf("Tpetbe поле имеет длину %d байт\n", lengths[2]);

mysql_fetch_row

MYSQL_ROW mysql_fetch_row(MYSQL_RESresult)

Выбирает следующую запись в наборе и возвращает ее как структуру MYSQL__ROW. Если записей больше нет или в случае ошибки, возвращается нулевое значение. В текущей реализации структура MY.SQI _ROW - это массив символьных строк, который может представлять любые данные.

Пример

MYSQL_ROW row;

row = mysql_fetch_row(results);

printf("Данные в третьем поле этой записи: %s\n", row[2]);

mysql_field_seek

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

Ищет указанное поле в текущей записи результирующего набора. Позиция, установленная этой функцией, используется при вызове mysql_fetch_field. Переданное значение MYSQL_FIELD_OFFSET должно быть значением, возвращаемым функцией mysql_field_tell (или другим вызовом mysql_f ield_seek). Если это значение равно 0, поиск будет осуществляться с начала записи. Функция возвращает позицию курсора перед вызовом функции.

Пример

MYSQL_FIELD field;

/* Перейти к началу записи */

old_pos = mysql_field_seek(results, 0);

/* Выбрать первое поле записи */

field = mysql_field_field(results);

/* Вернуться к исходному состоянию */

mysql_field_seek(results, old_pos);

mysql_field_tell

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RESresult)

Возвращает значение текущей позиции поля в текущей записи результирующего набора. Это значение используется с mysql_f ield_seek.

Пример

MYSQL_FIELD fieldl, field2, fieldS;

/* Запомнить текущую позицию */

old_pos = mysql_field_tell(results);

/* Выбрать еще три поля */

field1 = mysqLfield_field(results);

field2 = mysql_field_field(results);

field3 = mysql_field_field(results);

/* Вернуться к исходной позиции */

mysql_field_seek(results, old_pos);

mysql_free_result

void mysql_free_result(MYSQL_RESresult)

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

Пример

MYSQL_RES "results;

/* Выполнить операции с результатами */

mysql_free_result(results);

mysql_get_client_info

char *mysql_get_client_info(void)

Возвращает строку с версией библиотеки MySQL, используемой клиентской программой.

Пример

printf("Этa программа использует клиентскую библиотеку MySQL версии %s\n",

mysql_get_client_info()));

mysql_get_host_jnfo

char *mysql_get_host_info(MYSQL*mysql)

Возвращает строку, содержащую имя хоста сервера баз данных MySQL и тип используемого подключения (например, Unix-сокет или TGP).

Пример

print("Информация о подключении: %s", mysql_get_host_info(&mysql));

mysq l_get_proto_i nf о

unsigned int mysql_get_proto_info(MYSQtmysql)

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

Пример

printf("Этo подключение использует протокол соединений MySQL версии %d\n",

mysql_get_proto_info());

mysql_get_server_info

char *mysql_get_server_info(MYSQL*mysql)

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

Пример

printf("Bы подключены к серверу MySQL версии %s\n", mysql_get__server_info(&mysql);

mysqljnfo

char *mysql_info(MYSQL*mysql)

Возвращает строку, содержащую информацию о последнем запросе, если этот запрос был одним из указанных ниже. В настоящее время дополнительную информацию через эту функцию выдают следующие SQL-запросы: INSERT INTO (при использовании с оператором SELECT); LOAD DATA INFILE; ALTER TABLE; INSERT INTO TABLE (при использовании с множеством записей). Если последний запрос не имел дополнительной информации (например, это был один из других запросов), функция возвращает нулевое значение.

Пример

/* Только что был послан запрос LOAD DATA INFILE, загрузивший набор записей из файла

в существующую таблицу */ printf("Результат загрузки данных: %s\n", mysql_info(&mysql));

mysql_init

MYSQL *mysql_init(MYSQL*mysql)

Инициализирует структуру MYSQL, используемую для создания подключения к серверу баз данных MySQL. Наряду с mysql_real_connect, это является способом инициализации подключения к серверу. Вы передаете этой функции объявленную структуру MYSQL либо пустой указатель, в случае чего структура MYSQL будет создана и возвращена. Созданные этой функцией структуры корректно освобождаются функцией mysql_close. Если для инициализации структуры не хватило памяти, возвращается нулевое значение.

Пример

MYSQL mysql;

if (!mysql_init(&mysql)) {

printf("Ошибка инициализации клиента MySQL\n");

exit(1); }

mysqljnsertjd

my_ulonglong mysql_insert_id(MYSQL*mysql)

Вернет последнее число, сгенерированное для поля AUTO_INCREMENT. Данная функция обычно используется сразу после ввода значения в поле AUTO_INCREMENT, чтобы выяснить значение, которое было введено.

Пример

/* Мы только что ввели запись о сотруднике с автоматически генерируемым ID в

таблицу */

id = mysql_insert_id(&mysql);

printf(''Новый сотрудник получил ID %d\n", id);

mysql_kill

int mysql_kill(MYSQL*mysql, unsigned long pid)

Пытается завершить поток сервера MySQL с указанным ID процесса (PID). Эта функция возвращает ноль в случае успешного выполнения операции и ненулевое значение в случае неудачи. Чтобы воспользоваться этой функцией, вы должны иметь право Process для текущего подключения.

Пример

/* Завершить поток с номером 4 */

result = mysql_kill(&mysql, 4);

mysql_list_dbs

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

Возвращает структуру MYSQL_RES, содержащую имена всех существующих баз данных, которые отвечают выражению, заданному во втором аргументе. Этот аргумент может быть любым стандартным регулярным выражением SQL. Если передать нулевой указатель, будут возвращены имена всех баз данных. Как и все структуры MYSQL_RES, значение, возвращаемое этой функцией, должно быть освобождено с помощью mysql_f ree_result. Эта функция возвращает нулевое значение в случае ошибки.

Пример

MYSQL_RES databases;

databases = mysql_list_dbs(&mysql, (char*)MULL);

/* 'databases' теперь содержит имена всех баз данных на сервере MySQL */

mysql_list_fields

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

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

Пример

MYSQL_RES fields;

fields = mysql_list_fields(&mysql, "people", "address%");

/* 'fields' теперь содержит имена всех полей в таблице 'people', начинающихся с 'address' */

mysql_list_processes

MYSQL_RES*mysql_list_processes(MYSQL*mysql)

Возвращает структуру MYSQL_RES, содержащую информацию о всех текущих потоках, запущенных на сервере баз данных MySQL. Эта информация может быть использована с mysql_kill для завершения потоков, вызывающих ошибки. Как и все структуры MYSQL_RES, значение, возвращаемое этой функцией, должно быть освобождено с помощью mysql_f ree_result. Эта функция возвращает нулевое значение в случае ошибки.

Пример

MYSQL_RES threads;

threads = mysql_list_processes(&mysql);

mysql_list_tables

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

Возвращает-структуру MYSQL_RES, содержащую имена всех существующих таблиц в текущей базе данных, которые отвечают выражению, заданному во втором аргументе. Этот аргумент может быть любым стандартным регулярным выражением SQL. Если передать нулевой указатель вместо выражения, будет возвращен список имен всех таблиц. Как и все структуры MYSQL_RES, значение, возвращаемое этой функцией, должно быть освобождено с помощью mysql_f ree_result. Эта функция возвращает нулевое значение в случае ошибки.

Пример

MYSQL_RES tables;

tables = mysql_list_tables(&mysql, "p%");

/* 'tables' теперь содержит имена всех таблиц в текущей базе данных, начинающиеся с 'р' */

mysql_num_fields

unsigned int mysql_num_fields(MYSQL_RESresult)

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

Пример

num_fields = mysql_num_fields(results);

printf("There are %d fields in each row\n", num_fields);

mysql_num_rows

int mysqi_num_rows(MYSQL_RESresult)

Эта функция вернет количество записей в возвращаемом наборе записей. Работает корректно, только если набор был получен функцией mysql_store_result. Если была использована функция mysql_use_result, значением, возвращаемым функцией mysql_num_rows, будет количество записей, к которым уже был осуществлен доступ.

Пример

num_rows = mysql_num_rows(results);

printf("Было возвращено %d записей \n", num_rows);

mysql_ping

int mysql_ping(MYSQL*mysql)

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

Пример

while(mysql_ping(&mysql))

printf("Ошибка, попытка повторного подключения...\n");

mysql_query

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

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

Пример

error = mysql_query(&mysql, "SELECT FROM people WHERE name like

'Bill%'");

if (error) {

printf("Ошибка при выполнении запроса!\n");

exit(1);

}

mysql_real_connect

MYSQL *mysql_real_connect(MYSQL*mysql, const char*host, const char *user,

const char *passwd, const char*db, uint port, const char*unix_socket, uint client_flag)

Создает соединение с сервером баз данных MySQL. У этой функции есть восемь аргументов:

• Инициализированная структура MYSQL, созданная с помощью mysql_init.
  
• Имя хоста или IP-адрес сервера баз данных MySQL (для локального подключения к серверу MySQL через сокет Unix можно использовать пустую строку или localhost).
  
• Имя пользователя, используемое при подключении к серверу баз данных (пустой строкой можно указать на использование логина пользователя, запустившего клиента).
  
• Пароль, используемый для идентификации указанного пользователя. Если используется пустая строка, будет производиться аутентификация только пользователей без пароля.
  
• Начальная база данных, используемая при подключении (чтобы не выбирать при подключении начальную базу данных, можно передать пустую строку).
  
• Порт, используемый для удаленного подключения к серверу баз данных MySQL по протоколу TCP (чтобы принять порт по умолчанию, можно передать 0).
  
• Имя сокета Unix для подключения к серверу на локальном компьютере (чтобы принять сокет по умолчанию, можно использовать пустую строку).
  
• Ноль или более из набора флагов, используемых при особых обстоятельствах:
  

CLIENT_FOUND_ROWS

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

CLIENT_NO_SCHEMA

Запретить клиенту использование полной формы указания на столбец базы данных database, table.column , чтобы скрыть структуру базы данных.

CLIENT_COMPRESS

Использовать сжатие при соединении с сервером.

CLIENT_ODBC

Указать серверу, что клиент является подключением ODBC.

Пример

/* Подключиться к серверу на локальном хосте, используя стандартные

параметры. */

if (! mysql_real_connect(&mysql, "localhost", "bob", "mypass", "", 0, 0))

{

print "Ошибка подключения!\n";

exit(1); }

mysql_real_query

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

Выполняет SQL-запрос, заданный вторым аргументом. В третьем аргументе должна быть указана длина запроса. Указав длину, вы можете использовать в запросе двоичные данные, включая пустые (null) символы. Эта функция действует быстрее, чем mysql_query. Функция возвращает ноль, если запрос был успешно выполнен, и ненулевое значение в случае ошибки.

Пример

error = mysql_real_query(&ntysql, "SELECT FROM people WHERE name like Bill%'",

44);

if (error)

{

printf("Ошибка при выполнении запроса!\n");

exit(1);

}

mysql_reload

int mysql_reload(MYSQL*mysql)

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

Пример

result = mysql_reload(&mysql);

mysql_row_tell

unsigned int mysql_row_tell(MYSQL_RESresult)

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

Пример

saved_pos = mysql_row_tell(results);

/* Теперь в любой момент я могу вернуться к этой записи */

mysql_select_db

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

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

Пример

result = mysql_select_db(&mysql, "newdb");

mysql_shutdown

int mysql_shutdown(MYSQL*mysql)

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

Пример

result = mysql_shutdown(&mysql);

mysql_stat

char *mysql_stat(MYSQL*mysql)

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

Пример

printf("Информация о сервере \n-------\n%s\n", mysql_stat(&mysql));

mysql_store_result

MYSQL_RES *mysql_store_result(MYSQL*mysql)

Читает весь результат запроса и сохраняет его в структуре MYSQL_RES. Для доступа к возвращаемым из запроса данным должна использоваться либо эта функция, либо mysql_use_result. Вы должны вызвать mysql_f ree_result для освобождения структуры MYSQL_RES после завершения работы с ней. Функция возвращает нулевое значение в случае ошибки.

Пример

MYSQL_RES results;

mysql_query(&mysql, "SELECT* FROM people");

results = mysql_store_result(&mysql);

/* 'results' теперь содержит всю информацию из таблицы'people*/

mysql_thread_id

unsigned long mysql_thread_id(MYSQL* mysql)

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

Пример

thread_ld = mysql_thread_id(&mysql);

mysql_use_result

MYSQL_RES*mysql_use_result(MYSQL*mysql)

Читает результат запроса построчно и позволяет получить доступ к данным через структуру MYSQL_RES. Для доступа к возвращаемым из запроса данным должна использоваться или эта функция, или mysql_store_result. Так как эта функция не читает весь набор данных за один раз, она более быстрая, чем mysql_store_result, и более эффективно использует память. Однако при использовании этой функции вы должны прочесть все записи из набора данных, иначе следующий запрос получит оставшиеся данные. Также вы не сможете выполнять другие запросы до окончания работы с данными из этого запроса. После завершения работы с ними следует вызвать mysql_f ree_result для освобождения структуры MYSQL_RES. Функция возвращает нулевое значение в случае ошибки.

Пример

MYSQL_RES results;

mysql_query(&mysql, "SELECT* FROM people");

results = mysql_store_result(&mysql);

/* 'results' теперь позволяет получить доступ к данным таблицы (используя mysql_fetch_row), по одной записи за раз*/

mSQLCAPI

API для языка С в mSQL версии 2 не имеет принципиальных отличий от реализации в mSQL 1. Однако были добавлены некоторые новые функции, и было внесено несколько изменений в уже существующие функции. Если функция может быть использована только в mSQL 2, на это обращается особое внимание.

Типы данных

mSQL С API кроме стандартных типов данных языка С использует некоторые свои типы. Они определены в заголовочном файле 'msql.h', который необходимо подключать при компиляции всех программ, использующих библиотеку mSQL.

m_result

Структура, содержащая результаты оператора SELECT (или SHOW). Доступ к результатам запроса следует осуществлять через элемент этой структуры m_row.

m_row

Одна запись из данных, возвращаемых запросом SELECT. Результаты всех типов данных mSQL хранятся в этом типе (как массив символьных строк).

m_field

Структура, содержащая всю информацию, которая касается отдельного поля таблицы. Элементы структуры m_field могут быть проверены напрямую и имеют следующее строение:

char *name

Имя поля.

char *table

Имя таблицы, содержащей поле. Это значение пустое (null), если результирующий набор не относится к настоящей таблице.

int type

Тип поля. Является целым числом, соответствующим типам данных mSQL SQL, определенным в заголовочном файле msql.h.

int length

Длина поля в байтах.

int flags

Ноль или более флагов. Доступ к флагам осуществляется- через следующие макросы:

IS_PRI_KEY(flags)

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

IS_NOT_NULL(flags)

Возвращает true, если поле определено как NOT NULL.

msqIConnect

int msqIConnect ( char*host )

Создает подключение к серверу mSQL с указанным именем хоста или IP-адресом. Если в аргументе передать пустое значение, будет создано подключение к серверу mSQL на локальном хосте, с использованием сокетов Unix. Функция возвращает описатель базы данных, применяемый для связи с сервером баз данных. В случае ошибки вернется — 1.

Пример

/* Создать подключение к серверу баз данных на локальном хосте*/

dbh = msqlConnect( (char*)NULL );

if (dbh == -1) {

print " Ошибка при подключении!\n";

exit(1); }

msqISelectDB

int msqISelectDB ( int sock , char*dbName )

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

Пример

/* Выбрать базу данных "mydatabase" */

result = msqlSelectDB( dbh, "mydatabase" );

if (result == -1) {

print "Ошибка при выборе базы данных! \n";

exit(1); }

msqIQuery

int msqlQuery( int sock , char*query )

Выполняет указанный SQL-запрос. В mSQL 2 в возвращаемом значении содержится количество записей, измененных запросом (или выбранных запросом SELECT). В mSQL 1 при успешном выполнении возвращается ноль. В случае ошибки обе версии возвращают — 1.

Пример

rows_returned = msqlQuery( dbh, "SELECT FROM people" );

msqIStoreResult

m_result *msqlStoreResult()

Сохраняет результат запроса SELECT. Эту функцию вызывают сразу после вызова msqIQuery с запросом SELECT. Результаты запроса сохраняются в структуре m_result. Новые запросы посылаются серверу баз данных только после вызова этой функции. Каждая структура m_result должна быть освобождена с помощью msqlFreeResult по завершении работы с ней.

Пример

m_result *results;

rows_returned = msqlQuery( dbh, "SELECT FROM people" );

results = msqlStoreResult();

IK. 897

/* К данным из этого запроса можно обращаться через'results'. Теперь можно выполнять новые запросы */

msqIFreeResult

void msqIFreeResult ( m_result*result )

Освобождает память, связанную со структурой m_result.

Пример

m_result "results;

rows_returned = msqlQuery( dbh, "SELECT FROM people" );

results = msqlStoreResult();

/* Выполнить работу */

msqIFreeResult(results);

msqIFetchRow

m_row msqIFetchRow ( m_result*result )

Выбирает одну запись из результирующего набора. Данные помещаются в структуру m_row, которая является массивом символьных строк. Каждый успешный вызов функции msqIFetchRow возвращает следующую запись до тех пор, пока не будет достигнут конец набора, тогда будет возвращено нулевое значение.

Пример

m_result *results;

m_row "row;

rows_returned = msqlQuery( dbh, "SELECT FROM people" );

results = msqlStoreResult();

row = msqlFetchRow(results);

printf("Третье поле первой записи в таблице: %s\n", row[2]);

msqlDataSeek

void msqlDataSeek ( m_result* result, int pos )

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

Пример

m_result *results;

m_row Vow;

rows_returned = msqlQuery( dbh, "SELECT FROM people" );

results = msqlStoreResult();

row = msqlFetchRow(results);

/* Вернуться к исходной позиции */ msqlDataSeek(results, 0);

msqINumRows

int msqINumRows ( m_result*result )

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

Пример

rows_returned = msqlQuery( dbh, "SELECT FROM people" );

results = msqlStoreResult(); rows = msqlNumRows(results);

msqIFetchField

m_field "msqIFetchField ( m_result*result )

Возвращает информацию о полях в результирующем наборе. Каждый успешный вызов функции msqIFetchField вернет структуру m_f ield для очередного поля, пока полей больше не останется, и тогда будет возвращено пустое значение.

Пример

m_field *field;

rows_returned = msqlQuery( dbh, "SELECT FROM people" );

results = msqlStoreResult();

field = msqlFetchField(results);

/* 'field' теперь содержит информацию о первом поле

в результирующем наборе */

field = msqlFetchField(results);

/* 'field' теперь содержит информацию о втором поле в том же наборе записей */

msqlFieldSeek

void msqlFieldSeek ( m_result*result , int pos )

Устанавливает курсор, указывающий функции msqlFetchField какое поле выбирать в следующий раз. Установив курсор в позицию после последнего поля, вы, собственно, установите его просто после последнего поля.

Пример

m_result "results; m_field 'field;

rows_returned = msqlQuery( dbh, "SELECT FROM people" );

results = msqlStoreResult();

field = msqlFetchField(results);

/* Вернутся к исходной позиции */

msqlFieldSeek(results, .0);

msqlNumFields

int msqlNumFields ( m_result* result )

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

Пример

rows_returned = msqlQuery( dbh, "SELECT FROM people" );

results = msqlStoreResult();

fields = msqlNumFields(results);

msqICIose

int msqICIose ( int sock )

Закрывает подключение к серверу баз данных mSQL.

Пример

dbh = msqlConnect( (char')NULL );

/* Do work */

msqlClose(dbh);

msqIListDBs

m_result *msqlListDBs ( int sock )

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

Пример

databases = msqlListDBs(dbh);

/* 'databases' содержит теперь имена всех баз данных на сервере*/

msqIListTables

m_result *msqIListTables ( int sock )

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

Пример

tables = msqlListTables(dbh);

/* 'tables' содержит теперь имена всех таблиц текущей базы данных*/

msqIListFields

m_result 'msqIListFields ( int sock , char*tableName )

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

Пример

fields = msqlListFields(dbh, "people");

/* 'fields' содержит теперь имена всех полей

в таблице'people' */

msqIListlndex

m_result 'msqIListlndex ( int sock , char*tableName , char*index )

Возвращает структуру m_result, содержащую информацию о заданном индексе. Возвращаемый набор данных будет содержать тип индекса (в настоящее время поддерживается только тип 'avl') и содержащиеся в индексе имена полей. Как и все структуры m_result, значение, возвра щаемое этой функцией, должно быть освобождено с помощью msqlFreеResult после завершения работы с ним.

Пример

index = msqll_istIndex(dbh, "people", "idx1");

/* Теперь'index' содержит информацию об индексе 'idx1' в таблице 'people' */