2. Лекция: Функции ODBC API

Основные функции ODBC

Как уже отмечалось в предыдущей лекции, все функции ODBC API условно можно разделить на четыре группы:

• основные функции ODBC, обеспечивающие взаимодействие с источником данных;
• функции установки (setup DLL);
• функции инсталляции (installer DLL) ODBC и источников данных;
• функции преобразования данных (translation DLL), вызываемые при передаче данных от драйвера к источнику данных или обратно.

В следующей таблице представлен список основных функций ODBC API и их уровень соответствия стандартам (в столбце "Соответствие" показано соответствие стандартам и указана версия ODBC, начиная с которой данная функция доступна):

Функции установки

Группа функций установки (setup DLL) объединяет функции, предназначенные для конфигурирования драйверов и источников данных. В следующей таблице приведены функции, относящиеся к данной группе.

Функции инсталляции

Группа функций инсталляции (installer DLL) объединяет функции, предназначенные для установки ODBC и конфигурирования источников данных. В следующей таблице приведены функции, относящиеся к данной группе.

Соответствие версий ODBC API

Если приложение использует функции ODBC 2.x с менеджером драйверов ODBC 3.x, то менеджер драйверов подменяет вызываемую функцию и передает драйверу ODBC 3.x вызов функции в соответствии со следующей таблицей.

Дескрипторы

Создание дескрипторов

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

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

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

Создание дескриптора окружения выполняется функцией SQLAllocHandle, а освобождение - функцией SQLFreeHandle.

Функция SQLAllocHandle введена в версии ODBC 3.x вместо существовавших в версии ODBC 2.0 функций SQLAllocConnect, SQLAllocEnv и SQLAllocStmt. Для того чтобы приложение, использующее функцию SQLAllocHandle, могло работать через драйверы ODBC 2.x, менеджер драйверов версии 3.x заменяет вызовы функций третьей версии на их аналоги второй версии и передает такой "откорректированный" вызов ODBC-драйверу.

Для подключения к базе данных следует создать дескриптор (идентификатор) соединения. Для одного дескриптора окружения может быть создано несколько дескрипторов соединения.

Для выполнения SQL-оператора создается дескриптор (идентификатор) оператора.

Для одного дескриптора соединения может быть создано несколько дескрипторов оператора.

По спецификации ODBC для каждого приложения драйверы могут поддерживать неограниченное число дескрипторов каждого типа. Однако конкретный драйвер может накладывать некоторые ограничения на количество дескрипторов.

Функция, используемая для создания дескриптора окружения, соединения, оператора или приложения, имеет следующее формальное описание:

SQLRETURN SQLAllocHandle(
     SQLSMALLINT     HandleType,
     SQLHANDLE     InputHandle,
     SQLHANDLE *     OutputHandlePtr);

Параметр HandleType ([Input]) указывает одной из следующих констант тип создаваемого дескриптора:

SQL_HANDLE_ENV
SQL_HANDLE_DBC
SQL_HANDLE_STMT
SQL_HANDLE_DESC

Параметр InputHandle ([Input]) определяет контекст, в который добавляется создаваемый дескриптор. Если тип дескриптора SQL_HANDLE_ENV, то параметр InputHandle указывается константой SQL_NULL_HANDLE. При создании дескриптора среды параметр InputHandle задает дескриптор окружения, а для создания дескриптора оператора (SQL_HANDLE_STMT) и дескриптора приложения (SQL_HANDLE_DESC) - дескриптор соединения.

Идентификаторы, определяющие тип дескриптора и сам дескриптор, описаны в заголовочных файлах sql.h и sqltypes.h следующим образом:

/* sql.h */
#if (ODBCVER >= 0x0300)
#define SQL_HANDLE_ENV             1
#define SQL_HANDLE_DBC             2
#define SQL_HANDLE_STMT            3
#define SQL_HANDLE_DESC            4
#endif
/* sqltypes.h */
#if (ODBCVER >= 0x0300)
#if defined(WIN32) || defined(_WIN64)
typedef void*	SQLHANDLE;
#else
typedef SQLINTEGER              SQLHANDLE;
#endif	/* defined(WIN32) || defined(_WIN64) */
typedef SQLHANDLE               SQLHENV;
typedef SQLHANDLE               SQLHDBC;
typedef SQLHANDLE               SQLHSTMT;
typedef SQLHANDLE               SQLHDESC;
#else //ODBCVER < 0x0300
#if defined(WIN32) || defined(_WIN64)
typedef void*				SQLHENV;
typedef void*				SQLHDBC;
typedef void*				SQLHSTMT;
#elsetypedef SQLINTEGER              SQLHENV;
typedef SQLINTEGER              SQLHDBC;
typedef SQLINTEGER              SQLHSTMT;
#endif  /* defined(WIN32) || defined(_WIN64) */
#endif /* ODBCVER >= 0x0300 */

Параметр OutputHandlePtr ([Output]) - это указатель на буфер, в который помещается создаваемая для дескриптора структура данных.

Функция SQLAllocHandle может возвращать следующие значения:

• SQL_SUCCESS - значение, определяемое ODBC API для указания успешного завершения функции;
• SQL_SUCCESS_WITH_INFO - значение, определяемое ODBC API для указания того, что функция выполнена успешно, но с уведомительным сообщением;
• SQL_INVALID_HANDLE - значение, определяемое ODBC API для указания, что задан неверный дескриптор;
• SQL_ERROR - значение, определяемое ODBC API для указания, что при выполнении функции произошла ошибка.

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

Если при выполнении функции произошла ошибка (код возврата SQL_ERROR) или функция выполнена, но с уведомительным сообщением (код возврата SQL_SUCCESS_WITH_INFO), то значение SQLSTATE можно получить при вызове функции SQLGetDiagRec.

После создания дескриптора окружения следует установить атрибут SQL_ATTR_ODBC_VERSION. В противном случае при попытке создать дескриптор соединения произойдет ошибка.

Для приложений "согласованного стандарта" во время компиляции функция SQLAllocHandle заменяется на SQLAllocHandleStd. Основное отличие последней состоит в том, что при вызове этой функции с значением параметра HandleType, равным SQL_HANDLE_ENV, происходит установка атрибута окружения SQL_ATTR_ODBC_VERSION, равным SQL_OV_ODBC3 (так как приложения "согласованного стандарта" всегда являются приложениями ODBC 3.x и не требуют регистрации версии приложения).