Создание дескрипторов
Перед использованием функций 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 и не требуют регистрации версии приложения).
