API поддерживает богатый ассортимент функций, которые обеспечивают доступ к СУБД MySQL из программы пользователя, независимо от того, запущена ли она в локальной или на удаленной системе.
Вы должны подключить файл mysql.h в начале Вашей программы на C:
< UL>< TT>#include "mysql.h"< /TT>< /UL>
Вы также должны компоновать программу с математической (для шифрования) и mysqlclient библиотеками:
$ cc -I/usr/include/mysql -L/usr/lib/mysql myapp.c -o myapp -lm -lmysqlclient
Включаемые файлы обычно размещены в /usr/include/mysql, а библиотеки могут быть найдены в /usr/lib/mysql.
Если Вы имеете утечку памяти в вашей программе-клиенте, Вы можете компилировать с опцией < TT>--with-debug=yes< /TT>. Это заставит код клиента использовать пакет 'safe_malloc' в библиотеке клиентов MySQL. Вызовите TERMINATE(stdout) или my_end(1) в вашей прикладной программе-клиенте перед выходом, чтобы получить список всех утечек памяти. Детали - в файле mysys/safemalloc.c из дистрибутива MySQL.
Рассмотрим простой пример MySQL-клиента, который только выполнит SELECT и выведет все возвращенные строки в STDOUT. В нем использованы далеко не все функции С API, он должен только дать Вам представление о типичном виде программы-клиента.
#include <stdio.h>
#include <stdlib.h>
#include "mysql.h"
MYSQL mysql;
MYSQL_RES *res;
MYSQL_ROW row;
void exiterr(int exitcode)
{
fprintf(stderr, "%s\n", mysql_error(&mysql));
exit(exitcode);
}
int main()
{
uint i = 0;
if (!(mysql_connect(&mysql,"host","username","password")))
exiterr(1);
if (mysql_select_db(&mysql,"payroll")) exiterr(2);
if (mysql_query(&mysql,"SELECT name,rate FROM emp_master"))
exiterr(3);
if (!(res = mysql_store_result(&mysql))) exiterr(4);
while((row = mysql_fetch_row(res))) {
for (i=0 ; i < mysql_num_fields(res); i++)
printf("%s\n",row[i]);
}
if (!mysql_eof(res)) exiterr(5);
mysql_free_result(res);
mysql_close(&mysql);
}
|
MySQL API использует структуры данных MYSQL (определены в mysql.h) чтобы установить связь с СУБД. Вы можете устанавливать много соединений из одной программы-клиента, однако, каждое соединений должно быть связано с собственной отдельной структурой MYSQL.
После успешного запроса, если данные должны быть возвращены пользователю, набор результатов должен быть передан через функции < TT>mysql_use_result< /TT> или через функцию < TT>mysql_store_result< /TT>. Обе эти функции сохраняют набор результатов в структуре MYSQL_RES. Разница в том, что < TT>mysql_store_result< /TT> передает весь набор результатов в память клиента, а < TT>mysql_use_result< /TT> инструктирует клиента, чтобы он мог получить строку динамически с сервера с каждым обращением к mysql_fetch_row. Имейте в виду, что < TT>mysql_use_result< /TT> занимает ресурсы сервера, и не должен использоваться для интерактивных прикладных программ, где действия пользователя часто непредсказуемы и могут привести к большим задержкам. Обратите внимание также, что Вы можете держать только одно соединение, которое использует < TT>mysql_user_result< /TT>, открытым, и это должно быть последнее созданное соединение. По умолчанию процесс mysqld закроет соединение после тридцати секунд неактивности.
Данные, переданные из набора результатов с помощью mysql_fetch_row, будут помещены в структуру MYSQL_ROW, которая является просто массивом указателей на начало каждого поля.
СИНТАКСИС: < UL>
< TT>int mysql_affected_rows(MYSQL *mysql)< /TT>< /UL>
ОПИСАНИЕ: < UL>Возвращает число строк, на которые воздействует последний UPDATE, DELETE или INSERT.< /UL>
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ: < UL >
ПРИМЕР:
mysql_query(&mysql,"INSERT INTO gl_transact(acctnbr, amount) VALUES(12345,
651.30)");
if (mysql_affected_rows(&mysql) < 0)
fprintf(stderr, "Attempted to add duplicate primary key\n");
MySQL оптимизирован для случая удаления всех записей в таблице. Побочный эффект этой оптимизации - то, что MySQL возвратится, ноль для числа строк, на которые воздействовал в этой ситуации. Выполнение 'select count(*) from the_table' перед удалением всех записей даст Вам значение = на сколько строк воздействовала система, хотя это значение может изменяться между SELECT и DELETE. MySQL 3.20.X не поддерживает блокировку таблицы. Это исправлено в версии 3.21.X
СИНТАКСИС:
void mysql_close(MYSQL *mysql);
ОПИСАНИЕ:
Закрывает открытое соединение подключение. mysql_close должен быть вызван после завершения всех операций, выполняемых через соединение с MySQL. Если это не сделать, поток, созданный mysql_connect, зависнет до окончания тайм-аута сервера. На сервере, работающем с сильной нагрузкой, это может быстро израсходовать много памяти, хотя нужно очень немного времени центрального процессора.
Если подключение закрыто до того, как запущенный запрос завершился, запрос будет продолжаться, пока не попытается вернуть результат пользователю. При этом он завершится аварийно, узнав, что соединение не активно.
По умолчанию тайм-аут = 30 секундам для активного запроса и 8 часам для открытого подключения.
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ:
СИНТАКСИС:
MYSQL *mysql_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd)
ОПИСАНИЕ:
Пытается установить соединение с сервером MySQL, работающем на компьютере host. Значение host может быть сетевым именем или IP адресом. Параметр user задает логин пользователя MySQL, параметр passwd задает пароль для user. ОБРАТИТЕ ВНИМАНИЕ: Не пытайтесь шифровать passwd перед вызовом mysql_connect. Шифрование выполняется автоматически клиентским API.
mysql_connect должен успешно завершиться до каких-либо действий с базой данных.
Вы можете опционально задать первый аргумент mysql_connect как (MYSQL*) 0. Это вынудит C API к автоматическому распределению памяти для структуры подключения и освобождению ее при завершении. Расплатой за это служит то, что Вы не сможете получать сообщения об ошибках из mysql_connect, когда используете эту опцию.
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ:
ПРИМЕР:
MYSQL *mysql;
if ((mysql = malloc(sizeof(MYSQL))) != NULL)
{
if (!(mysql_connect(mysql, "pr_server", "jqpublic", "mypasswd")))
{
free(mysql);
exit(1);
}
}
free(mysql);
|
СИНТАКСИС:
int mysql_create_db(MYSQL *mysql, const char *db);
ОПИСАНИЕ:
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ:
СИНТАКСИС:
void mysql_data_seek(MYSQL_RES *res, uint offset);
ОПИСАНИЕ:
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ:
СИНТАКСИС:
int mysql_drop_db(MYSQL *mysql, const char *db);
ОПИСАНИЕ:
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ:
СИНТАКСИС:
ОПИСАНИЕ:
Возвращает значение != 0, если последний вызов mysql_fetch_row не вернул ничего потому, что достигнут конец набора результатов.
СИНТАКСИС:
ОПИСАНИЕ:
СИНТАКСИС:
MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *handle);
ОПИСАНИЕ:
Находит тип поля таблицы.
СИНТАКСИС:
unsigned int *mysql_fetch_lengths(MYSQL_RES *mysql)
ОПИСАНИЕ:
Возвращает длину всех столбцов в наборе результатов запросов. Если Вы планируете получение данных, содержащих \0, Вы должны использовать эту функцию, чтобы получить фактическую длину значения поля.
СИНТАКСИС:
MYSQL_ROW mysql_fetch_row(MYSQL_RES *mysql);
ОПИСАНИЕ:
Выбирает следующую строку в результате запроса. Возвратит пустой указатель, когда все строки были получены.
СИНТАКСИС:
ОПИСАНИЕ:
СИНТАКСИС:
void mysql_free_result(MYSQL_RES *result);
ОПИСАНИЕ:
Освобождает память, использованную, чтобы сохранить результат запроса. Должна быть вызвана всякий раз, когда Вы закончили использовать результаты вызова mysql_store_result().
СИНТАКСИС:
char *mysql_get_client_info(void);
ОПИСАНИЕ:
Эта функция просто возвращает строку с информацией о версии используемой в настоящее время клиентской библиотеки. Иногда полезно.
СИНТАКСИС:
char *mysql_get_host_info(MYSQL *mysql);
ОПИСАНИЕ:
Возвращает имя сервера (заданное в аргументе "host" при вызове mysql_connect).
СИНТАКСИС:
int mysql_get_proto_info(MYSQL *mysql);
ОПИСАНИЕ:
Получает версию протокола, используемую подключением. MySQL поддерживает динамические протоколы, основанные на возможностях клиента. В версии 3.20.X это не делает ничего, но в будущих версиях, эта возможность позволит, например, одному пользователю подключать использование текущего протокола, в то время как другой использует шифрование и сжатие.
СИНТАКСИС:
char *mysql_get_server_info(MYSQL *mysql);
ОПИСАНИЕ:
Возвращает версию сервера.
СИНТАКСИС:
ОПИСАНИЕ:
СИНТАКСИС:
MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char *wild);
ОПИСАНИЕ:
Предоставляет простой способ переноса mSQL прикладных программ. Подобно выполнению 'SHOW databases [ LIKE wild-card ]', как запроса.
СИНТАКСИС:
MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char *table, const char *wild);
ОПИСАНИЕ:
Предоставляет простой способ переноса mSQL прикладных программ. Подобно выполнению 'SHOW fields [FROM table] [FROM database] [LIKE wild-card]', как запроса.
СИНТАКСИС:
MYSQL_RES *mysql_list_processes(MYSQL *mysql);
ОПИСАНИЕ:
Получает список потоков, в настоящее время запущенных на сервере MySQL. Вы должны иметь привилегии process.
СИНТАКСИС:
MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char *wild);
ОПИСАНИЕ:
Предоставляет простой способ переноса mSQL прикладных программ.
Вызывает как запрос 'SHOW tables [FROM database]'.
СИНТАКСИС:
int mysql_num_fields(MYSQL_RES *result);
ОПИСАНИЕ:
Возвращает количество столбцов (полей) в результате запроса.
ПРИМЕР:
MYSQL mysql;
MYSQL_RES *result;
int fields;
if (mysql_query(&mysql, "SELECT * FROM emp_master") == 0)
{
result = mysql_store_result( &mysql );
if (result != NULL )
{
fields = mysql_num_fields( result );
printf( "Retrieved %u fields\n", fields );
}
else printf( "Query failed\n" );
}
else abort();
|
См. также:
mysql_list_dbs, mysql_list_fields, mysql_list_processes, mysql_list_tables, mysql_store_result, mysql_use_result
СИНТАКСИС:
int mysql_num_rows(MYSQL_RES *result);
ОПИСАНИЕ:
Возвращает количество строк, возвращенных последним вызовом mysql_list_dbs, mysql_list_fields, mysql_list_processes, mysql_list_tables или mysql_store_result.
ПРИМЕР:
MYSQL mysql;
MYSQL_RES *result;
int rows;
if (mysql_query(&mysql, "SELECT * FROM emp_master") == 0)
{
result = mysql_store_result(&mysql );
if (result != NULL)
{
rows = mysql_num_rows(result);
printf("Retrieved %u rows\n", rows);
}
else printf("Query failed\n");
}
else abort();
|
См. также:
mysql_list_dbs, mysql_list_fields, mysql_list_processes, mysql_list_tables, mysql_store_result, mysql_use_result
СИНТАКСИС:
int mysql_query(MYSQL *mysql, const char *query);
ОПИСАНИЕ:
Выполняет SQL запрос указанный query к базе данных, указанной в mysql. Эта функция возвращает 0, если запрос выполнен успешно. Результат, отличный от нуля, указывает на ошибку. Обращение к mysql_error выведет текстовое сообщение об ошибке.
Вызов mysql_num_rows даст Вам число строк, возвращенных запросом.
Если Вы имеете поле AUTO_INCREMENT в модифицируемой таблице, и выполняете оператор INSERT, Вы можете получить последнее назначенное значение поля, проверяя mysql_insert_id.
СИНТАКСИС:
int mysql_real_query(MYSQL *mysql, const char *query, uint length);
ОПИСАНИЕ:
Эта функция вызывается mysql_query после того, как она выполнила обращение к функции strlen чтобы вычислить длину строки запроса. Это можно использовать, если Ваша программа распределяет фиксированный буфер для строки запроса.
Вы будете должны использовать эту функцию, если Вы имеете данные, в которые значение \0 входит не как последнее.
СИНТАКСИС:
int mysql_reload(MYSQL *mysql);
ОПИСАНИЕ:
Перезагружают таблицу доступа пользователей, очищает все кэши и закрывает все открытые неиспользуемые таблицы. Должна быть вызвана перед запуском isamchk на любой таблице. Требует, чтобы пользователь имел право на перезагрузку (reload).
СИНТАКСИС:
int mysql_select_db(MYSQL *mysql, const char *db);
ОПИСАНИЕ:
Пытается соединиться с базой данных, указанной в db, на сервере, указанном в mysql. Сервер СУБД MySQL использует логин и пароль, содержащиеся в mysql, чтобы опознать подключение. Перед использованием mysql_select_db необходимо успешно вызвать mysql_connect.
mysql_select_db должен быть вызван успешно перед попыткой сделать запрос к базе данных. Исключительные ситуации - запросы типа:
SHOW DATABASES like 'A%';
SELECT 1+1; # SELECT без использования таблиц(ы).
СИНТАКСИС:
int mysql_shutdown(MYSQL *mysql);
ОПИСАНИЕ:
Останавливает сервер СУБД MySQL. Пользователь должен иметь право shutdown.
СИНТАКСИС:
char *mysql_stat(MYSQL *mysql);
ОПИСАНИЕ:
Возвращает информацию, которую выдает команда 'mysqladmin version' в виде строки символов. Эквивалентно опции stat программы mysqladmin. В строку включается информация о простое в секундах, запущенных потоках, запросах, перезагрузках и открытых таблицах.
СИНТАКСИС:
MYSQL_RES *mysql_store_result(MYSQL *mysql);
ОПИСАНИЕ:
Передает результат клиенту. Вы должны использовать эту функцию или mysql_use_result() чтобы получить результат с сервера. Вы обязательно должны использовать mysql_store_result() или mysql_use_result() после того, как выполнили успешный запрос.
mysql_store_result() вернет NULL при ошибке или если инструкция не вернула никаких данных. Вы можете обрабатывать ошибки так:
if (!(result=mysql_store_result(&mysql)) &&
mysql_num_fields(&mysql))
fputs(mysql_error(&mysql),stderr);
|
Вызов mysql_free_result() должен быть выполнен, чтобы освободить память.
СИНТАКСИС:
MYSQL_RES *mysql_use_result(MYSQL *mysql);
ОПИСАНИЕ:
То же, что и mysql_store_result(), за исключением того, что результат выдается сервером динамически для каждого вызова mysql_fetch_row(). Эта функция не должна использоваться в интерактивных прикладных программах, так как она связывает сервер. Зато она помогает уменьшить использование памяти на стороне клиента.