Глава 8. Интерфейсы для MySQL

Содержание

8.1. Интерфейс PHP API для MySQL

8.1.1. Общие проблемы MySQL и PHP

8.2. Интерфейс Perl API для MySQL

8.2.1. DBI с помощью DBD::mysql

8.2.2. Интерфейс DBI

8.2.3. Больше информации по DBI/DBD

8.3. Поддержка ODBC в MySQL

8.3.1. Как установить MyODBC

8.3.2. Как заполнять различные поля в Администраторе ODBC

8.3.3. Параметры подключения для MyODBC

8.3.4. Как сообщать о проблемах с MyODBC

8.3.5. Программы, работающие с MyODBC

8.3.6. Как получить значение столбца AUTO_INCREMENT в ODBC

8.3.7. Составление отчетов о проблемах с MyODBC

8.4. Интерфейс C для MySQL

8.4.1. Типы данных C API

8.4.2. Обзор функций интерфейса C

8.4.3. Описание функций интерфейса C

8.4.4. Описания функций C, связанных с потоками

8.4.5. Описания функций C, доступных во встраиваемом сервере

8.4.6. Основные вопросы и проблемы в использовании интерфейса C

8.4.7. Сборка клиентских программ

8.4.8. Как создать клиентскую программу с потоками

8.4.9. libmysqld, встраиваемая библиотека сервера MySQL

8.5. Интерфейсы C++

8.5.1. Интерфейс Borland C++

8.6. Взаимодействие MySQL и Java (JDBC)

8.7. Интерфейсы Python API для MySQL

8.8. Интерфейсы Tcl API для MySQL

8.9. Оболочка Eiffel для MySQL

Эта глава описывает доступные для MySQL интерфейсы, а также разъясняет, где их можно получить и как их использовать. Интерфейс C API охвачен наиболее широко, так как он был разработан командой MySQL и является базой для большинства других интерфейсов.

8.1. Интерфейс PHP API для MySQL

8.1.1. Общие проблемы MySQL и PHP

PHP представляет собой серверный язык программирования скриптов со встраиваемым кодом HTML, который может использоваться для создания динамических веб-страниц. Он содержит поддержку для доступа к нескольким базам данных, включая MySQL. PHP может запускаться как отдельная программа или компилироваться как модуль для использования с веб-сервером Apache.

Дистрибутив и документацию можно найти на веб-сайте PHP (http://www.php.net/).

8.1.1. Общие проблемы MySQL и PHP

• Ошибка: "Максимальное время исполнения превышено" ("Maximum Execution Time Exceeded"). Это ограничение PHP; откройте файл php3.ini и измените максимальное время исполнения с 30 секунд на более высокую величину, такую, какая вам необходима. Есть еще один неплохой способ - удвоить разрешенный объем оперативной памяти с 8 Мб до 16 Мб на скрипт.

• Ошибка: "Неисправимая ошибка: Вызов неподдерживаемой или неопределенной функции mysql_connect() в .." ("Fatal error: Call to unsupported or undefined function mysql_connect() in ..") Это означает, что ваша версия PHP не скомпилирована с поддержкой MySQL. Можно либо скомпилировать динамический модуль MySQL и загрузить его в PHP, либо перекомпилировать PHP со встроенной поддержкой MySQL. Это подробно описывается в руководстве по PHP.

• Ошибка: "неопределенная ссылка на `uncompress' (несжатый) " ("undefined reference to `uncompress'"). Это означает, что данная клиентская библиотека скомпилирована с поддержкой сжатого клиент-серверного протокола. Устранение этой проблемы заключается в добавлении -lz в конце при линковании с -lmysqlclient.

8.2. Интерфейс Perl API для MySQL

8.2.1. DBI с помощью DBD::mysql

8.2.2. Интерфейс DBI

8.2.3. Больше информации по DBI/DBD

Этот раздел снабжает документами для работы с интерфейсом Perl DBI. Более ранний интерфейс назывался mysqlperl. В настоящее время интерфейс DBI/DBD является рекомендуемым интерфейсом Perl, так что mysqlperl здесь не документируется как устаревший.

8.2.1. DBI с помощью DBD::mysql

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

Для более подробной информации об интерфейсе Perl5 DBI, пожалуйста, посетите веб-страницу DBI и прочитайте документацию:

http://dbi.perl.org/ 

Для более подробной информации об объектно ориентированном программировании (OOП), описанном в Perl5, смотрите веб-страницу Perl OOP:

http://language.perl.com/info/documentation.html 

Следует учитывать, что, если вы хотите использовать транзакции с Perl, то необходимо иметь модуль Msql-Mysql-modules версии 1.2216 или новее.

Рекомендуемый модуль для Perl: DBD-mysql-2.1022 или новее.

Инструкции по установке поддержки Perl в MySQL даются в разделе See Раздел 2.7, «Замечания по установке Perl».

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

shell> perldoc DBD/mysql
shell> perldoc mysql

8.2.2. Интерфейс DBI

Унифицированные методы DBI

Методы, определенные только для MySQL

Более детально методы Perl DBI описаны в следующих разделах. Возвращаемые переменные:

• $dbh

  Дескриптор базы данных

• $sth

  Дескриптор выражения

• $rc

  Код возврата (часто статус)

• $rv

  Возвращенное значение (часто количество строк)

Унифицированные методы DBI

• connect($data_source, $username, $password)

  Метод connect используется для подсоединения к источнику данных (СУБД). Строка $data_source должна начинаться с DBI:имя драйвера:. Примеры вызова connect с драйвером DBD::mysql:

  $dbh = DBI->connect("DBI:mysql:$database", $user, $password);
  $dbh = DBI->connect("DBI:mysql:$database:$hostname", $user,
      $password);
  $dbh = DBI->connect("DBI:mysql:$database:$hostname:$port", $user,
      $password);
  

  Если не определены имя пользователя либо пароль, DBI использует значения переменных окружения DBI_USER и DBI_PASS. Если не указано имя хоста, используется значение по умолчанию - localhost. Если не указан номер порта, также используется значение по умолчанию (3306).

  Начиная с Msql-Mysql-modules версии 1.2009, доступны следующие модификаторы $data_source:

  • mysql_read_default_file=file_name

    Читать файл file_name как файл настроек. За более подробной информацией о файлах настройки обращайтесь к разделу See Раздел 4.1.2, «Файлы параметров my.cnf».

  • mysql_read_default_group=group_name

    По умолчанию используется группа [client] файла настроек. Опцией mysql_read_default_group, группа по умолчанию устанавливается в [group_name].

  • mysql_compression=1

    Использовать сжатие при обмене клиента и сервера (MySQL версий 3.22.3 и выше).

  • mysql_socket=/path/to/socket

    Указывает путь к Unix-сокету, который будет использоваться для соединения с сервером. (MySQL версии 3.21.15 и более поздние).

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

  Например, если вы не хотите явно указывать имя пользователя и пароль в программе, использующей DBI, можно внести эту информацию в файл ~/.my.cnf, написав вызов connect. Это делается следующим образом:

  $dbh = DBI -> connect("DBI:mysql:$database",
        ";mysql_read_default_file=$ENV{HOME}/.my.cnf",
          $user, $password);
  

  Данный пример считает настройки из группы [client] файла ~/.my.cnf. Чтобы выполнить те же действия, но с настройками, взятыми из группы [perl], нужно использовать следующую форму записи:

  $dbh = DBI -> connect("DBI:mysql:$database",
        ";mysql_read_default_file=$ENV{HOME}/.my.cnf"
        . ";mysql_read_default_group=perl",
        $user, $password);
  

• disconnect

  Метод disconnect разрывает соединение с базой данных. Это стоит делать перед выходом из программы. Пример:

  $rc = $dbh->disconnect;
  

• prepare($statement)

  Подготавливает SQL-запрос $statement к исполнению сервером. Возвращает дескриптор выражения ($sth), который затем используется для вызова метода execute. Обычно работа с запросами типа SELECT (так же, как и аналогичными, такими как SHOW, DESCRIBE, EXPLAIN) сводится к вызову методов prepare и execute. Пример:

  $sth = $dbh -> prepare($statement)
  or die "Не  могу  подготовить $statement: $dbh -> errstr\n";
  

  Если вы хотите считывать большие результаты вашим клиентом, вы можете указать использование mysql_use_result() в Perl:

  my $sth = $dbh->prepare($statement { "mysql_use_result" => 1});
  

• execute

  Метод execute выполняет приготовленный запрос. Если запрос не SELECT, метод возвращает количество строк, которые были подверглись воздействию запроса. Если таковых нет, execute возвращает "0E0", что Perl интерпретирует как нуль, но воспринимает как значение ``истина'' (true). Если возникает ошибка, execute возвращает undef. Для запросов SELECT метод только инициирует выполнение запроса SQL-сервером и для получения данных необходимо использовать один из методов fetch_*. Пример:

  $rv = $sth -> execute or die "Не могу выполнить: $sth -> errstr";
  

• do($statement)

  Метод do готовит SQL-запрос к выполнению, выполняет его и возвращает количество строк, подвергшихся воздействию. Если нет ни одной такой строки, как результат возвращается значение "0E0", что Perl интерпретирует как нуль, но воспринимает как значение ``истина'' (true).. Этот метод обычно используется для выражений, не являющихся операторами SELECT, которые не могут быть подготовлены заранее (из-за ограничений драйвера) или же выполняются только один раз (операции вставки, удаления и т.д.). Например:

  $rv = $dbh->do($statement)
  or die "Не могу выполнить: $sth -> errstr";
  

  Обычно использование 'do' существенно быстрей (и предпочтительней) для запросов без параметров, чем пара prepare/execute.

• quote($string)

  Метод quote используется для экранирования специальных символов в запросе символами экранирования, а также заключения данных в необходимые внешние символы цитирования (например кавычки). Пример:

  $sql = $dbh->quote($string)
  

• fetchrow_array

  Этот метод выбирает очередную строку данных и возвращает ее как массив значений полей. Пример:

  while(@row = $sth -> fetchrow_array) {
  print qw($row[0]\t$row[1]\t$row[2]\n);
  }
  

• fetchrow_arrayref

  Этот метод выбирает очередную строку данных и возвращает ссылку на массив значений полей. Пример:

  while($row_ref = $sth -> fetchrow_arrayref) {
  print qw($row_ref -> [0]\t$row_ref -> [1]\t$row_ref ->
  [2]\n);
  }
  

• fetchrow_hashref

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

  while($hash_ref = $sth -> fetchrow_hashref) {
  print qw($hash_ref -> {firstname}\t$hash_ref ->
  {lastname}\t$hash_ref ->{title}\n);
  }
  

• fetchall_arrayref

  Этот метод выдает все данные (все строки), получаемые как результат SQL-запроса. Он возвращает ссылку на массив ссылок на массивы отдельных строк. Соответственно, для обращения к этим данным нужно использовать вложенный цикл. Пример:

  my $table = $sth -> fetchall_arrayref
  or die "$sth -> errstr\n";
  my($i, $j);
  for $i ( 0 .. $#{$table}} ) {
  for $j ( 0 .. $#{$table -> [$i]} )  {
  print "$table -> [$i][$j]\t";
  }
  print "\n";
  }
  

• finish

  Указывает, что данные этого дескриптора запроса больше не нужны. После вызова этого метода программа освобождает дескриптор запроса и все системные ресурсы, которые используются для работы с ним. Пример:

  $rc = $sth -> finish;
  

• rows

  Возвращает число измененных/удаленных последней командой (UPDATE, DELETE и т.д.) строк. Это обычно требуется после выполнения метода execute над запросами, не являющимися запросами SELECT. Например:

  $rv = $sth -> rows;
  

• NULLABLE

  Возвращает ссылку на массив значений, которые указывают, может столбец принимать значения NULL или нет. Возможные значения для каждого элемента массива - это 0 или пустая строка, если столбец не может содержать значения NULL, 1 - если может и 2 - если статус столбца относительно значения NULL не определен.

  Например:

  $null_possible = $sth -> {NULLABLE};
  

• NUM_OF_FIELDS

  Значение этого атрибута равно числу полей в результате запроса (SELECT или SHOW FIELDS). Его можно использовать его для проверки, возвращает ли запрос результат вообще: нулевое значение соответствует запросам типа INSERT, DELETE, UPDATE - т.е. всем, кроме SELECT. Например:

  $nr_of_fields = $sth -> {NUM_OF_FIELDS};
  

• data_sources($driver_name)

  Этот метод возвращает массив с именами баз данных, доступных на локальном MySQL-сервере (на localhost). Пример:

  @dbs = DBI->data_sources("mysql");
  

• ChopBlanks

  Этот атрибут определяет, будут ли методы fetchrow_* убирать начальные и оконечные пробелы из результатов. Пример:

  $sth -> {'ChopBlanks'} = 1;
  

• trace($trace_level), trace($trace_level, $trace_filename)

  Метод trace разрешает или запрещает трассировку. Если он вызывается как метод класса DBI, он влияет на разрешение трассировки всех дескрипторов. В случае же обращения к нему как к методу дескриптора запроса либо базы данных он разрешает/запрещает трассировку для этой базы данных или этого запроса (и всех будущих потомков). $trace_level указывает уровень детализации трассировочной информации, так установка $trace_level в 2 включает детализированную трассировку. Установка $trace_level в 0 запрещает трассировку. По умолчанию вывод трассировочной информации осуществляется на стандартное устройство вывода ошибок (stderr). Если указан параметр $trace_filename, его значение используется как имя файла, в который выводится трассировочная информация ВСЕХ дескрипторов, для которых разрешена трассировка. Пример:

  DBI->trace(2);                # трассировка всего
  DBI->trace(2,"/tmp/dbi.out"); # трассировка всего в /tmp/dbi.out
  $dth->trace(2);               # трассировка всех запросов к этой базе
  данных
  $sth->trace(2);               # трассировка этого запроса
  

  Трассировку DBI можно также включить при помощи переменной окружения DBI_TRACE. Присвоение числового значения эквивалентно вызову DBI->trace(значение). Строковое значение (имя файла) эквивалентно вызову DBI->trace(2,значение).

Методы, специфичные для MySQL

Описанные здесь методы специфичны для MySQL и не являются частью стандарта DBI. Сейчас считается, что часть из них использовать не стоит: is_blob, is_key, is_num, is_pri_key, is_not_null, length, max_length и table. Ниже указаны возможные стандартные альтернативы, если они существуют:

• insertid

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

  $new_id = $sth->{insertid};
  

  В качестве альтернативы можно использовать $dbh -> {'mysql_insertid'}.

• is_blob

  Возвращает ссылку на массив булевых значений; для каждого элемента массива значение ``истина'' указывает, что соответствующий столбец имеет тип BLOB. Например:

  $keys = $sth -> {is_blob};
  

• is_key

  Возвращает ссылку на массив булевых значений; для каждого элемента массива значение ``истина'' указывает, что соответствующий столбец является ключом. Пример:

  $keys = $sth -> {is_key};
  

• is_num

  Возвращает ссылку на массив булевых значений; для каждого элемента массива, значение ``истина'' указывает, что соответствующий столбец содержит числовые значения. Например:

  $nums = $sth -> {is_num};
  

• is_pri_key

  Возвращает ссылку на массив булевых значений; для каждого элемента массива, значение ``истина'' указывает, что соответствующий столбец является первичным ключом. Пример:

  $pri_keys = $sth -> {is_pri_key};
  

• is_not_null

  Возвращает ссылку на массив б булевых значений; для каждого элемента массива значение ``ложь'' указывает на то, что столбец может содержать значения NULL. Например:

  $not_nulls = $sth -> {is_not_null};
  

  is_not_null не рекомендуется к применению; предпочтительно использование NULLABLE (описан ранее), поскольку это стандартный для DBI метод.

• length, max_length

  Каждый из этих методов возвращает ссылку на массив размеров столбцов. Массив, соответствующий length, содержит максимальные допустимые размеры каждого столбца (из описания таблицы). Массив max_length содержит максимальные размеры элементов, присутствующих в результирующей таблице. Например:

  $lengths = $sth -> {length};
  $max_lengths = $sth -> {max_length};
  

• NAME

  Возвращает ссылку на массив имен столбцов. Например:

  $names = $sth -> {NAME};
  

• table

  Возвращает ссылку на массив названий таблиц. Например:

  $tables = $sth -> {table};
  

• type

  Возвращает ссылку на массив типов столбцов. Пример:

  $types = $sth -> {type};
  

8.2.3. Больше информации по DBI/DBD

Вы можете использовать команду perldoc для получения больше информации по DBI.

perldoc DBI
perldoc DBI::FAQ
perldoc DBD::mysql

Конечно, вы можете использовать pod2man, pod2html и другие утилиты для трансляции в другие форматы.

Самая свежая информация по DBI живет на веб-сайте DBI: http://dbi.perl.org/.

8.3. Поддержка ODBC в MySQL

8.3.1. Как установить MyODBC

8.3.2. Как заполнять различные поля в Администраторе ODBC

8.3.3. Параметры подключения для MyODBC

8.3.4. Как сообщать о проблемах с MyODBC

8.3.5. Программы, работающие с MyODBC

8.3.6. Как получить значение столбца AUTO_INCREMENT в ODBC

8.3.7. Составление отчетов о проблемах с MyODBC

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

8.3.1. Как установить MyODBC

MyODBC 2.50 представляет собой 32-разрядный драйвер ODBC спецификации уровня 0 (с возможностями уровней 1 и 2) для подсоединения совместимого с ODBC приложения к MySQL. MyODBC работает под Windows 9x/Me/NT/2000/XP и на большинстве платформ Unix.

MyODBC 3.51 это усовершенствованная версия ODBC со спецификационным уровнем 1 (полностью ядро API + уровень возможности 2).

MyODBC является свободно доступным. Самую свежую версию можно найти на http://www.mysql.com/downloads/api-myodbc.html.

Обратите внимание, что версии 2.50.х распространяются под LGPL лицензией, тогда как 3.51.х версии под лицензией GPL.

Если существуют проблемы с MyODBC, а программа также работает и с OLEDB, то следует попробовать работать с драйвером OLEDB.

Обычно установка MyODBC требуется только на компьютерах под Windows. Для Unix необходимость в MyODBC возникает только для программ, подобных ColdFusion, которые работают на Unix-машинах и используют ODBC для подключения к базам данных.

Для установки MyODBC на Unix-машину понадобится также программа управления ODBC. MyODBC, как известно, работает с большинством программ управления ODBC для Unix.

Для того чтобы установить MyODBC на Windows, необходимо загрузить соответствующий файл MyODBC .zip, распаковать его с помощью WinZIP или другой подобной программы и выполнить исполняемый файл SETUP.EXE.

При попытке установить MyODBC под Windows/NT/XP можно получить следующую ошибку:

An error occurred while copying C:\WINDOWS\SYSTEM\MFC30.DLL. Restart
Windows and try installing again (before running any applications which
use  ODBC)

Проблема здесь заключается в том, что некоторая другая программа в это же время использует ODBC и из-за конструктивных особенностей Windows в данном случае может оказаться невозможным установить новый драйвер ODBC с помощью поставляемой Microsoft программы установки. В большинстве случаев можно продолжать установку, просто нажимая Ignore для копирования оставшихся файлов MyODBC, при этом заключительная установка должна работать. Если она не работает, то выход состоит в следующем: перезагрузите систему в безопасном режиме (safe mode) (для перехода в этот режим следует нажать F8 непосредственно перед тем, как компьютер начинает запускать Windows во время перезагрузки), установите MyODBC и перезагрузите Windows в обычном режиме.

• Чтобы установить подсоединение к Unix-компьютеру от Windows-компьютера с помощью приложения ODBC (которое само по себе не поддерживает MySQL), необходимо вначале установить MyODBC на Windows-машине.

• Данный пользователь и Windows-машина должны обладать привилегиями доступа к серверу MySQL на Unix-машине. Это устанавливается с помощью команды GRANT (see Раздел 4.3.1, «Синтаксис команд GRANT и REVOKE»).

• Необходимо создать новую запись DSN ODBC следующим образом:

• Открыть Control Panel (Панель управления) на Windows-компьютере.

• Выполнить двойной щелчок на пиктограмме ODBC Data Sources 32-bit (Источники данных ODBC (32бит)).

• Щелкнуть на закладке User DSN (Пользовательский DSN).

• Щелкнуть на кнопке Add (Добавить).

• Выбрать MySQL в окне Create New Data Source (Создание нового источника данных) и щелкнуть на кнопке Finish (Готово).

• Откроется окно конфигурации драйвера MySQL по умолчанию (see Раздел 8.3.2, «Как заполнять различные поля в Администраторе ODBC»).

• Теперь запустите свое приложение и выберите драйвер ODBC с помощью DSN, заданного вами в Администраторе источников данных ODBC.

Обратите внимание: существуют и другие возможности конфигурации в окне MySQL (трассировка, не подсказывать соединение и так далее), которые вы можете опробовать, если столкнетесь с какими-либо проблемами.

8.3.2. Как заполнять различные поля в Администраторе ODBC

Для Windows 95 существует три возможности задания имени сервера:

• Использовать IP-адрес сервера.

• Добавить файл \windows\lmhosts со следующей информацией:

  ip hostname
  

  Например:

  194.216.84.21 my_hostname
  

• Сконфигурировать ПК для использования DNS.

Пример заполнения при установке ODBC:

Windows DSN name:   test
Description:        This is my test database
MySql Database:     test
Server:             194.216.84.21
User:               monty
Password:           my_password
Port:

Значением поля Windows DSN name может быть любое имя, уникальное для данной установки ODBC.

Не обязательно указывать значения для полей Server, User, Password или Port в окне установки ODBC. Однако если вы это сделали, данные величины в дальнейшем при установке соединения будут использованы как значения по умолчанию. Тогда же можно будет изменить эти значения.

Если номер порта не задан, то используется его значение по умолчанию (3306).

Если задается опция Read options from C:\my.cnf, то группы client и odbc будут читаться из файла C:\my.cnf. Можно применять все опции, используемые в mysql_options() (see Раздел 8.4.3.39, «mysql_options()»).

8.3.3. Параметры подключения для MyODBC

Можно указать следующие параметры для MyODBC в разделе [Servername] файла ODBC.INI или через аргумент InConnectionString при вызове функции SQLDriverConnect().

Аргумент ``option'' используется для указания MyODBC, что данный клиент не на 100% соответствует ODBC. Под Windows обычно устанавливается флаг опций путем переключения различных опций в окне данного соединения, но можно также установить это в аргументе ``option''. Следующие опции перечислены в том же порядке, в котором они перечислены в окне подключения MyODBC:

Если необходимо иметь много опций, следует добавить вышеуказанные флаги! Например, установка опции в 12 (4+8) дает отладку без ограничений пакетов!

По умолчанию MYODBC.DLL компилируется для оптимальной производительности. Если необходимо отладить MyODBC (например, включить трассировку), следует вместо этого использовать MYODBCD.DLL. Для установки этого файла следует скопировать MYODBCD.DLL поверх установленного файла MYODBC.DLL.

8.3.4. Как сообщать о проблемах с MyODBC

Драйвер MyODBC был протестирован с Access, Admndemo.exe, C++-Builder, Borland Builder 4, Centura Team Developer (первоначально Gupta SQL/Windows), ColdFusion (под Solaris и NT с пакетом обновлений svc pack 5), Crystal Reports, DataJunction, Delphi, ERwin, Excel, iHTML, FileMaker Pro, FoxPro, Notes 4.5/4.6, SBSS, Perl DBD-ODBC, Paradox, Powerbuilder, 32-разрядным Powerdesigner, VC++ и Visual Basic.

Если вам известны какие- либо другие приложения, работающие с MyODBC, пожалуйста, пошлите сообщение об этом по адресу <[email protected]>!

При работе с некоторыми программами можно получить ошибку вроде: Another user has modifies the record that you have modified.

В большинстве случаев эту проблему можно устранить одним из следующих способов:

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

• Добавить столбец TIMESTAMP, если он еще не создан.

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

Если перечисленные выше способы не помогают, необходимо сделать трассировочный файл MyODBC и попробовать определить, в чем дело.

8.3.5. Программы, работающие с MyODBC

Большинство программ должно работать с MyODBC, но для каждой из перечисленных ниже мы либо провели тестирование сами, либо получили подтверждение от пользователей, что она действительно работает:

• Программа

  Комментарий

• Access

  Чтобы заставить Access работать:

  • При использовании Access 2000 необходимо установить самую последнюю версию (2.6 или выше) Microsoft MDAC (Microsoft Data Access Components), которую можно найти на http://www.microsoft.com/data/. Это позволит устранить ошибку в Access, которая проявляется в том, что при экспорте данных в MySQL не указываются имена таблиц и столбцов. Еще один способ обойти эту ошибку заключается в модернизации MyODBC до версии 2.50.33 и MySQL до версии 3.23.x - оба апгрейда вместе обеспечивают обход данной ошибки!

    Необходимо также получить и использовать Microsoft Jet 4.0 Service Pack 5 (SP5), который можно найти на http://support.microsoft.com/support/kb/articles/Q 239/1/14.ASP. Это позволит исключить некоторые случаи, когда столбцы в Access отмечаются как #deleted#. Следует учитывать, что при использовании версии MySQL 3.22 необходимо применять патч для MDAC и использовать MyODBC 2.50.32 или 2.50.34 и выше, чтобы обойти эту проблему.

  • Для всех версий Access необходимо включить для MyODBC флаг опции Return matching rows. Для Access 2.0 следует дополнительно включить Simulate ODBC 1.0.

  • Все таблицы, в которых вы хотите иметь возможность обновления, должны содержать столбец типа TIMESTAMP для временных меток. Для максимальной переносимости рекомендуется TIMESTAMP(14) или просто TIMESTAMP вместо других вариантов TIMESTAMP(X).

  • Таблица должна иметь первичный ключ. Если не имеет, то новые или обновленные строки могут выводиться как #DELETED#.

  • Используйте поля с числами с плавающей запятой только двойной точности (типа DOUBLE). Access отказывается работать при сравнении чисел с плавающей запятой одинарной точности. Проявляется это обычно в том, что новые или обновленные строки могут выводиться как #DELETED# или в том, что вы не можете найти или обновить строки.

  • При связывании через MyODBC таблицы, один из столбцов которой имеет тип BIGINT, результат будет выводиться как #DELETED#. Обходное решение заключается в следующем:

    • Добавьте еще один пустой столбец с TIMESTAMP в качестве типа данных, предпочтительно TIMESTAMP(14).

    • Проверьте Change BIGINT columns to INT в диалоговом окне опций подключения в Администраторе источников данных ODBC DSN

    • Удалите данную табличную связь из Access и создайте ее вновь.

    После этого старые записи все равно будут представлены как #DELETED#, а заново добавленные/обновленные записи будут уже выводиться правильно.

  • Если после добавления столбца TIMESTAMP все еще появляется ошибка Another user has changed your data, то, возможно, поможет следующий трюк. Не используйте режим работы ``Таблица''. Вместо этого создайте форму с желаемыми полями и используйте режим работы ``Форма''. Следует установить свойство DefaultValue для столбца TIMESTAMP в NOW(). Возможно, было бы неплохо убрать столбец TIMESTAMP из поля зрения, чтобы не смущать пользователей.

  • В некоторых случаях Access может создавать недопустимые запросы SQL, которые MySQL не может понять. Это можно устранить путем выбора в меню Access опции Query|SQLSpecific|Pass-Through.

  • Access под NT будет сообщать о столбцах BLOB как об объектах OLE. Если вместо этого вы хотите иметь столбцы MEMO, то необходимо изменить тип столбца на TEXT с помощью ALTER TABLE.

  • Access не всегда может правильно обработать столбцы типа DATE. Если с ними возникают проблемы, следует изменить тип этих столбцов на DATETIME.

  • Если Access содержит столбец, определенный как BYTE, то Access будет пытаться экспортировать его как TINYINT вместо TINYINT UNSIGNED. Это будет вызывать проблемы, если величины в данном столбце превышают 127!

• ADO

  При написании программ с привлечением интерфейса ADO API и MyODBC необходимо обратить внимание на некоторые исходные свойства, которые не поддерживаются сервером MySQL. Например, использование свойства CursorLocation как adUseServer будет возвращать для свойства RecordCount результат -1. Чтобы получить правильную величину, необходимо установить данное свойство в adUseClient, как показано в коде VB ниже:

  Dim myconn As New ADODB.Connection
  Dim myrs As New Recordset
  Dim mySQL As String
  Dim myrows As Long
  
  myconn.Open "DSN=MyODBCsample"
  mySQL = "SELECT * from user"
  myrs.Source = mySQL
  Set myrs.ActiveConnection = myconn
  myrs.CursorLocation = adUseClient
  myrs.Open
  myrows = myrs.RecordCount
  
  myrs.Close
  myconn.Close
  

  Еще один обходной путь состоит в том, чтобы для такого запроса использовать команду SELECT COUNT(*), чтобы получить правильное количество строк.

• Активные серверные страницы (ASP)

  Необходимо использовать флаг опции Return matching rows.

• BDE-приложения

  Чтобы заставить их работать, следует установить флаги опций Don't optimize column widths и Return matching rows.

• Borland Builder 4

  При запуске запроса можно использовать свойство Active или метод Open. Следует учитывать, что Active будет начинать работу при автоматической выдаче запроса SELECT * FROM ..., что может оказаться не так уж и хорошо для больших таблиц!

• ColdFusion (Под Unix)

  Приведенные далее сведения взяты из документации по ColdFusion. Для применения драйвера unixODBC с источником данных MyODBC следует использовать следующую информацию. Корпорация Allaire подтвердила, что версия MyODBC 2.50.26 работает с версией MySQL 3.22.27 и ColdFusion для Linux (любая более новая версия также должна работать). Драйвер MyODBC можно загрузить с http://www.mysql.com/downloads/api-myodbc.html

  В версии ColdFusion 4.5.1 можно использовать Администратор источников данных ColdFusion для добавления источника данных MySQL. Однако данный драйвер не включен в версию ColdFusion 4.5.1. Чтобы драйвер MySQL появился в выпадающем списке источников данных ODBC, необходимо создать драйвер MyODBC и скопировать его в каталог /opt/coldfusion/lib/libmyodbc.so. Каталог Contrib содержит программу mydsn-xxx.zip, которая позволяет создавать и удалять файл реестра DSN для драйвера MyODBC для приложений Coldfusion.

• DataJunction

  Необходимо изменить эту программу для вывода VARCHAR вместо ENUM, поскольку экспорт ENUM происходит таким образом, что вызывает неприятности в MySQL.

• Excel

  Работает. Несколько замечаний:

  • Если существуют проблемы с датами, попробуйте выбирать их как строки, используя функцию CONCAT(). Например:

    select CONCAT(rise_time), CONCAT(set_time)
      from sunrise_sunset;
    

    Величины, извлеченные как строки этим способом, должны корректно распознаваться программой Excel97 как значения времени. Назначение функции CONCAT() в этом примере состоит в том, чтобы ``обмануть'' ODBC, заставив интерпретировать столбец как столбец ``строкового типа''. Без функции CONCAT() ODBC будет считать, что это столбец временного типа, и Excel не распознает его. Следует заметить, что это является ошибкой Excel, поскольку он автоматически преобразует строку в значения времени. Это замечательно если источником является текстовый файл, но это глупо, когда источником является подключение ODBC, дающее точные типы данных для каждого столбца.

• Word

  Для извлечения данных из MySQL в документы Word/Excel следует использовать драйвер MyODBC и помощь встроенной программы Microsoft Query. Для создания, например, базы данных db с таблицей, содержащей 2 столбца с текстом, необходимо выполнить следующие действия:

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

  • Создайте файл DSN, используя менеджер ODBC, например, my для созданной выше базы данных db.

  • Откройте приложение Word.

  • Создайте новый пустой документ.

  • Используя панель инструментов вызванной базы данных, нажмите кнопку Insert database.

  • Нажмите кнопку Get Data.

  • В окне Get Data справа нажмите кнопку Ms Query.

  • В окне Ms Query создайте новый источник данных, используя файл DSN my.

  • Выберите новый запрос.

  • Выберите желаемый столбец.

  • Создайте фильтр (при желании).

  • Создайте сортировку (при желании).

  • Выберите Return Data to Microsoft Word.

  • Нажмите кнопку Finish.

  • Нажмите Insert data и выбирайте записи.

  • Нажмите Ok. Вы увидите выбранные строки в своем документе в Word.

• odbcadmin

  Тестовая программа для ODBC.

• Delphi

  Необходимо использовать версию BDE 3.2 или более новую. Установите поле опции Don't optimize column width при подключении к MySQL. Кроме того, ниже приводится потенциально полезный код Delphi, который устанавливает вхождения для драйвера MyODBC как в ODBC, так и в BDE. (Запись в BDE требует наличия редактора псевдонимов BDE Alias Editor, который доступен бесплатно на Delphi Super Page. Спасибо за это Брайену Брантону (Bryan Brunton <[email protected]>)):

  fReg:= TRegistry.Create;
  fReg.OpenKey('\Software\ODBC\ODBC.INI\DocumentsFab', True);
  fReg.WriteString('Database', 'Documents');
  fReg.WriteString('Description', ' ');
  fReg.WriteString('Driver', 'C:\WINNT\System32\myodbc.dll');
  fReg.WriteString('Flag', '1');
  fReg.WriteString('Password', '');
  fReg.WriteString('Port', ' ');
  fReg.WriteString('Server', 'xmark');
  fReg.WriteString('User', 'winuser');
  fReg.OpenKey('\Software\ODBC\ODBC.INI\ODBC Data Sources', True);
  fReg.WriteString('DocumentsFab', 'MySQL');
  fReg.CloseKey;
  fReg.Free;
  
  Memo1.Lines.Add('DATABASE NAME=');
  Memo1.Lines.Add('USER NAME=');
  Memo1.Lines.Add('ODBC DSN=DocumentsFab');
  Memo1.Lines.Add('OPEN MODE=READ/WRITE');
  Memo1.Lines.Add('BATCH COUNT=200');
  Memo1.Lines.Add('LANGDRIVER=');
  Memo1.Lines.Add('MAX ROWS=-1');
  Memo1.Lines.Add('SCHEMA CACHE DIR=');
  Memo1.Lines.Add('SCHEMA CACHE SIZE=8');
  Memo1.Lines.Add('SCHEMA CACHE TIME=-1');
  Memo1.Lines.Add('SQLPASSTHRU MODE=SHARED AUTOCOMMIT');
  Memo1.Lines.Add('SQLQRYMODE=');
  Memo1.Lines.Add('ENABLE SCHEMA CACHE=FALSE');
  Memo1.Lines.Add('ENABLE BCD=FALSE');
  Memo1.Lines.Add('ROWSET SIZE=20');
  Memo1.Lines.Add('BLOBS TO CACHE=64');
  Memo1.Lines.Add('BLOB SIZE=32');
  AliasEditor.Add('DocumentsFab','MySQL',Memo1.Lines);
  

• C++ Builder

  Проведено тестирование с версией BDE 3.0. Единственная обнаруженная проблема состоит в том, что при изменениях схемы таблиц не обновляются поля запросов. Хотя BDE не распознает первичных ключей, а только индекс PRIMARY, тем не менее, это не было проблемой.

• Vision

  Необходимо использовать флаг опции Return matching rows.

• Visual Basic

  Чтобы обеспечить возможность обновить таблицу, для нее необходимо определить первичный ключ. Visual Basic с ADO не обрабатывает больших целых чисел. Это означает, что некоторые запросы вроде SHOW PROCESSLIST не будут работать правильно. Для устранения данной проблемы нужно добавить опцию OPTION=16384 в строке подключения ODBC или установить опцию Change BIGINT columns to INT в окне подключения MyODBC. Можно также установить опцию Return matching rows.

• VisualInterDev

  Если возникает ошибка [Microsoft][ODBC Driver Manager] Driver does not support this parameter, то ее причина может заключаться в том, что результат содержит данные типа BIGINT. Попробуйте установить опцию Change BIGINT columns to INT в окне подключения MyODBC.

• Visual Objects

  Необходимо использовать флаг опции Don't optimize column widths.

8.3.6. Как получить значение столбца AUTO_INCREMENT в ODBC

Существует распространенная проблема, заключающаяся в том, как получить значение автоматически сгенерированного ID из INSERT. С помощью ODBC можно сделать что-то наподобие следующего (предполагается, что auto представляет собой поле AUTO_INCREMENT ):

INSERT INTO foo (auto,text) VALUES(NULL,'text');
SELECT LAST_INSERT_ID();

Или, если вы просто собираетесь вставить данный ID в другую таблицу, то можно сделать так:

INSERT INTO foo (auto,text) VALUES(NULL,'text');
INSERT INTO foo2 (id,text) VALUES(LAST_INSERT_ID(),'text');

See Раздел 8.4.6.3, «Как получить уникальный идентификатор для последней внесенной строки?».

Для некоторых приложений ODBC (по крайней мере, для Delphi и Access), чтобы найти недавно вставленную строку, можно использовать следующий запрос:

SELECT * FROM tbl_name WHERE auto IS NULL;

8.3.7. Составление отчетов о проблемах с MyODBC

Если встречаются трудности с применением MyODBC, то следует начинать с получения системного журнала менеджера ODBC (журнал, получаемый при затребовании записей в Администраторе ODBC) и журнала MyODBC.

Чтобы получить журнал MyODBC, необходимо выполнить следующие действия:

1. Убедитесь, что вы используете myodbcd.dll, а не myodbc.dll. Наиболее простой способ - получить файл myodbcd.dll из дистрибутива MyODBC и скопировать его поверх файла myodbc.dll, который должен находиться в вашем каталоге C:\windows\system32 или C:\winnt\system32. Однако после окончания тестирования целесообразно восстановить старый файл myodbc.dll, поскольку он намного быстрее, чем myodbcd.dll.

2. Включите опцию Trace MyODBC в окне подключения/конфигурации MyODBC. Информация будет записываться в файл C:\myodbc.log. Если опция трассировки не запоминается при возвращении к предыдущему окну, то это означает, что сейчас драйвер myodbcd.dll не используется (см. пункт выше).

3. Запустите свое приложение и попытайтесь получить отказ в работе.

Проверьте трассировочный файл MyODBC, что бы попытаться выяснить, в чем дело. Можно также найти сделанные вами запросы в файле myodbc.log - поищите в нем строку >mysql_real_query.

Попробуйте также выполнить дублирование этих запросов с помощью монитора mysql или admndemo, чтобы определить, где возникает ошибка - в MyODBC или в MySQL.

Если вы обнаружите какую-либо ошибку, то присылайте, пожалуйста, только строки, имеющие отношение к ней (максимум 40 строк), по адресу <[email protected]>. Просьба никогда не присылать полностью весь системный журнал MyODBC или ODBC!

Если у вас нет возможности определить, что именно у вас не так, остается последняя возможность - создать архив (tar или zip), содержащий трассировочный файл MyODBC, системный журнал ODBC и файл README с описанием своей проблемы. Вы можете послать это по адресу ftp://support.mysql.com/pub/mysql/secret/. В MySQL AB только мы будем иметь доступ к присланным вами файлам. Гарантируем, что с ними мы будем обращаться очень осторожно!

Если вы можете создать программу для демонстрации данной проблемы, присылайте, пожалуйста, и ее тоже!

Если эта программа работает с некоторыми другими серверами SQL, следует сделать системный журнал ODBC, где вы делаете в точности то же самое в другом сервере SQL.

Помните, что чем больше информации вы нам предоставите, тем больше вероятность, что мы сможем решить данную проблему!

8.4. Интерфейс C для MySQL

8.4.1. Типы данных C API

8.4.2. Обзор функций интерфейса C

8.4.3. Описание функций интерфейса C

8.4.4. Описания функций C, связанных с потоками

8.4.5. Описания функций C, доступных во встраиваемом сервере

8.4.6. Основные вопросы и проблемы в использовании интерфейса C

8.4.7. Сборка клиентских программ

8.4.8. Как создать клиентскую программу с потоками

8.4.9. libmysqld, встраиваемая библиотека сервера MySQL

Исходный код программного интерфейса (API) C распространяется вместе с MySQL. Он включает в себя библиотеку mysqlclient и обеспечивает возможность доступа к базе данных программам на С.

Многие клиенты исходного дистрибутива MySQL написаны на C. Они являются хорошими примерами для демонстрации использования интерфейса C. Их можно найти их в каталоге clients исходного дистрибутива MySQL.

Большинство других клиентских интерфейсов (за исключением Java) для соединения с сервером MySQL используют библиотеку mysqlclient. Это означает, что, например, можно извлечь определенную выгоду, используя те же переменные окружения, что и в других клиентских программах, поскольку на них есть ссылки из библиотеки (see Раздел 4.8, «Клиентские сценарии и утилиты MySQL», где приведен список этих переменных).

Клиент имеет максимальный размер буфера связи. Начальный размер этого буфера составляет 16 Kб и автоматически увеличивается до максимального значения 16 Mб. Поскольку размеры буфера увеличиваются только при подтверждении запроса на это, то просто увеличение максимального предела по умолчанию само по себе не обеспечит увеличения используемых ресурсов. Проверка этого размера в основном используется для ошибочных запросов и коммуникационных пакетов.

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

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

Программирование с учетом потоков описано в разделе See Раздел 8.4.8, «Как создать клиентскую программу с потоками». При создании автономного приложения, включающего и "сервер", и "клиент" в одной и той же программе (и не взаимодействующего с внешним сервером MySQL), обращайтесь к разделу See Раздел 8.4.9, «libmysqld, встраиваемая библиотека сервера MySQL».

8.4.1. Типы данных C API

• MYSQL

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

• MYSQL_RES

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

• MYSQL_ROW

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

• MYSQL_FIELD

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

• MYSQL_FIELD_OFFSET

  ``Типобезопасное'' представление позиции поля в списке полей MySQL. (используется функцией mysql_field_seek()). Позиции представляют собой номера полей внутри строки, причем нумерация начинается с нуля.

• my_ulonglong

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

  printf (Количество  строк: %lu\n", (unsigned long) mysql_num_rows(result));
  

Структура MYSQL_FIELD содержит следующие перечисленные ниже элементы:

• char * name

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

• char * table

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

• char * def

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

• enum enum_field_types type

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

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

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

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

• unsigned int length

  Размер данного поля в том виде, в каком он указан в определении таблицы.

• unsigned int max_length

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

• unsigned int flags

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

  Значение флага	описание флага
  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 (не рекомендуется)
  SET_FLAG	Поле имеет тип SET (не рекомендуется)
  BLOB_FLAG	Поле имеет тип BLOB или TEXT (не рекомендуется)
  TIMESTAMP_FLAG	Поле имеет тип TIMESTAMP (не рекомендуется)

  Использование флагов BLOB_FLAG, ENUM_FLAG, SET_FLAG и TIMESTAMP_FLAG не рекомендуется, поскольку они указывают скорее тип поля, чем атрибут этого типа. Вместо этого более предпочтительно определять тип поля описанным выше способом field->type в отношении полей FIELD_TYPE_BLOB, FIELD_TYPE_ENUM, FIELD_TYPE_SET или FIELD_TYPE_TIMESTAMP. Следующий пример иллюстрирует типичное использование величины flags:

  if (field->flags & NOT_NULL_FLAG)
     printf("Field can't be null\n");
  

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

  Статус флага	Описание
  IS_NOT_NULL(flags)	Возвращает TRUE, если данное поле определено как NOT NULL
  IS_PRI_KEY(flags)	Возвращает TRUE, если данное поле является первичным ключом
  IS_BLOB(flags)	Возвращает TRUE, если данное поле имеет тип BLOB или TEXT (не рекомендуется; более предпочтительно field->type)

• unsigned int decimals

  Возвращает число десятичных знаков для числовых полей.

8.4.2. Обзор функций интерфейса C

В приведенной ниже таблице перечислены доступные в интерфейсе C функции. Более детально они описаны в следующем разделе (see Раздел 8.4.3, «Описание функций интерфейса C»).

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

8.4.3. Описание функций интерфейса C

8.4.3.1. mysql_affected_rows()

8.4.3.2. mysql_change_user()

8.4.3.3. mysql_character_set_name()

8.4.3.4. mysql_close()

8.4.3.5. mysql_connect()

8.4.3.6. mysql_create_db()

8.4.3.7. mysql_data_seek()

8.4.3.8. mysql_debug()

8.4.3.9. mysql_drop_db()

8.4.3.10. mysql_dump_debug_info()

8.4.3.11. mysql_eof()

8.4.3.12. mysql_errno()

8.4.3.13. mysql_error()

8.4.3.14. mysql_escape_string()

8.4.3.15. mysql_fetch_field()

8.4.3.16. mysql_fetch_field_direct()

8.4.3.17. mysql_fetch_fields()

8.4.3.18. mysql_fetch_lengths()

8.4.3.19. mysql_fetch_row()

8.4.3.20. mysql_field_count()

8.4.3.21. mysql_field_seek()

8.4.3.22. mysql_field_tell()

8.4.3.23. mysql_free_result()

8.4.3.24. mysql_get_client_info()

8.4.3.25. mysql_get_server_version()

8.4.3.26. mysql_get_host_info()

8.4.3.27. mysql_get_proto_info()

8.4.3.28. mysql_get_server_info()

8.4.3.29. mysql_info()

8.4.3.30. mysql_init()

8.4.3.31. mysql_insert_id()

8.4.3.32. mysql_kill()

8.4.3.33. mysql_list_dbs()

8.4.3.34. mysql_list_fields()

8.4.3.35. mysql_list_processes()

8.4.3.36. mysql_list_tables()

8.4.3.37. mysql_num_fields()

8.4.3.38. mysql_num_rows()

8.4.3.39. mysql_options()

8.4.3.40. mysql_ping()

8.4.3.41. mysql_query()

8.4.3.42. mysql_real_connect()

8.4.3.43. mysql_real_escape_string()

8.4.3.44. mysql_real_query()

8.4.3.45. mysql_reload()

8.4.3.46. mysql_row_seek()

8.4.3.47. mysql_row_tell()

8.4.3.48. mysql_select_db()

8.4.3.49. mysql_shutdown()

8.4.3.50. mysql_stat()

8.4.3.51. mysql_store_result()

8.4.3.52. mysql_thread_id()

8.4.3.53. mysql_use_result()

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

Функции, возвращающие величину, обычно возвращают указатель или целое число. Если не указано иначе, то функции, возвращающие указатель, возвращают величину не-NULL при успешном выполнении или величину NULL, указывающую на ошибку, а функции, возвращающие целое число, возвращают нуль при успешном выполнении или ненулевую величину при возникновении ошибки. Следует учитывать, что термин ``ненулевая величина'' означает именно это. Если в описании функции не сказано иначе, то не следует пробовать интерпретировать эту величину иначе, чем нуль:

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

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

8.4.3.1. mysql_affected_rows()

my_ulonglong mysql_affected_rows(MYSQL *mysql)

Описание

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

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

Целое число больше нуля равно количеству строк, подвергшихся воздействию или извлеченных. Нуль указывает, что ни одна из записей не была обновлена для команды UPDATE, ни одна из строк не совпала с утверждением WHERE в данном запросе или что ни один запрос еще не был выполнен. Значение -1 показывает, что данный запрос возвратил ошибку или что для запроса SELECT функция mysql_affected_rows() была вызвана прежде вызова функции mysql_store_result().

Ошибки

Нет.

Пример

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

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

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

8.4.3.2. mysql_change_user()

my_bool mysql_change_user(MYSQL *mysql, const char *user, const char *password, const char *db)

Описание

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

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

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

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

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

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

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

Ошибки

Те же, что и для 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

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

Пример

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

8.4.3.3. mysql_character_set_name()

const char *mysql_character_set_name(MYSQL *mysql)

Описание

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

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

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

Ошибки

Нет.

8.4.3.4. mysql_close()

void mysql_close(MYSQL *mysql)

Описание

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

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

Нет.

Ошибки

Нет.

8.4.3.5. mysql_connect()

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

Описание

Данная функция не рекомендуется. Вместо нее предпочтительно использовать функцию mysql_real_connect().

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

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

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

Те же, что и для mysql_real_connect().

Ошибки

Те же, что и для mysql_real_connect().

8.4.3.6. mysql_create_db()

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

Описание

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

Данная функция не рекомендуется. Вместо нее предпочтительно использовать функцию mysql_query() для выполнения SQL-команды CREATE DATABASE.

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

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

Ошибки

• CR_COMMANDS_OUT_OF_SYNC

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

• CR_SERVER_GONE_ERROR

  Сервер MySQL неожиданно завершил работу.

• CR_SERVER_LOST

  Соединение с сервером прервалось в процессе данного запроса.

• CR_UNKNOWN_ERROR

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

Пример

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

8.4.3.7. mysql_data_seek()

void mysql_data_seek(MYSQL_RES *result, my_ulonglong offset)

Описание

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