2. Лекция: Функции ODBC API
Рассматривается функциональная модель ODBC API, описывается применение дескрипторов окружения, соединения и оператора.


Основные функции ODBC
Как уже отмечалось в предыдущей лекции, все функции ODBC API условно можно разделить на четыре группы:
- основные функции ODBC, обеспечивающие взаимодействие с источником данных;
- функции установки (setup DLL);
- функции инсталляции (installer DLL) ODBC и источников данных;
- функции преобразования данных (translation DLL), вызываемые при передаче данных от драйвера к источнику данных или обратно.
В следующей таблице представлен список основных функций ODBC API и их уровень соответствия стандартам (в столбце "Соответствие" показано соответствие стандартам и указана версия ODBC, начиная с которой данная функция доступна):
Функция | Соответствие | Описание |
---|---|---|
Соединение с источником данных | ||
SQLAllocHandle | ISO 92 ODBC 3.0 | Получает идентификатор (дескриптор) среды, соединения или оператора, или дескриптор приложения |
SQLConnect | ISO 92 ODBC 1.0 | Соединение с источником данных по DSN, имени и паролю пользователя |
SQLDriverConnect | ODBC ODBC 1.0 | Соединение с источником данных по указанной строке соединения или при помощи отображаемого диалога для интерактивного ввода параметров соединения |
SQLBrowseConnect | ODBC ODBC 1.0 | Последовательно запрашивает атрибуты соединения и устанавливает допустимые значения атрибута. После спецификации значения для каждого требуемого атрибута соединения функция выполняет соединение с источником данных |
Получение информации о драйверах и об источниках данных | ||
SQLDataSources | ISO 92 ODBC1.0 | Возвращает список доступных источников данных |
SQLDrivers | ODBC ODBC2.0 | Возвращает список установленных драйверов и их атрибуты |
SQLGetInfo | ISO 92 ODBC1.0 | Возвращает информацию об указанных драйвере и источнике данных |
SQLGetFunctions | ISO 92 ODBC1.0 | Возвращает функции, которые поддерживаются используемым драйвером |
SQLGetTypeInfo | ISO 92 ODBC1.0 | Возвращает информацию о поддерживаемых типах данных |
Изменение атрибутов драйверов и получение информации об атрибутах драйверов | ||
SQLSetConnectAttr | ISO 92 ODBC3.0 | Устанавливает атрибуты соединения |
SQLGetConnectAttr | ISO 92 ODBC3.0 | Возвращает значение атрибута соединения |
SQLSetEnvAttr | ISO 92 ODBC3.0 | Устанавливает атрибуты среды |
SQLGetEnvAttr | ISO 92 ODBC3.0 | Возвращает значение атрибута среды |
SQLSetStmtAttr | ISO 92 ODBC3.0 | Устанавливает атрибуты оператора |
SQLGetStmtAttr | ISO 92 ODBC3.0 | Возвращает значение атрибута оператора |
Изменение полей дескриптора и получение информации о полях дескриптора | ||
SQLGetDescField | ISO 92 ODBC3.0 | Возвращает значение дескриптора для одного поля |
SQLGetDescRec | ISO 92 ODBC3.0 | Возвращает значения дескриптора для нескольких полей |
SQLSetDescField | ISO 92 ODBC3.0 | Устанавливает значение дескриптора для одного поля |
SQLSetDescRec | ISO 92 ODBC3.0 | Устанавливает значение дескриптора для нескольких полей |
Подготовка SQL-запросов | ||
SQLPrepare | ISO 92 ODBC1.0 | Компилирует SQL-оператор для последующего выполнения |
SQLBindParameter | ODBC ODBC2.0 | Связывает буфер с параметрами, используемыми в SQL-операторе |
SQLGetCursorName | ISO 92 ODBC1.0 | Возвращает имя курсора, которое ассоциировано с дескриптором оператора |
SQLSetCursorName | ISO 92 ODBC1.0 | Определяет имя курсора |
SQLSetScrollOptions | ODBC1.0 | Устанавливает опции, которые управляют поведением курсора. В версиях ODBC 2.x и 3.x эта функция заменена функцией SQLSetStmtAttr |
Выполнение запросов | ||
SQLExecute | ISO 92 ODBC1.0 | Выполняет откомпилированный SQL-оператор |
SQLExecDirect | ISO 92 ODBC1.0 | Выполняет SQL-оператор |
SQLNativeSql | ODBC ODBC1.0 | Возвращает текст SQL-оператора, преобразованного конкретным драйвером, но не выполняет его |
SQLDescribeParam | ODBC ODBC1.0 | Возвращает описание параметров, используемых в откомпилированном SQL-операторе |
SQLNumParams | ISO 92 ODBC1.0 | Возвращает число параметров в откомпилированном SQL-операторе |
SQLParamData | ISO 92 ODBC1.0 | Используется совместно с функцией SQLPutData для передачи во время выполнения значений параметров |
SQLPutData | ISO 92 ODBC1.0 | Передает часть или все значения параметров |
Извлечение результатов и информации о них | ||
SQLRowCount | ISO 92 ODBC1.0 | Возвращает число строк, на которые воздействовал SQL-оператор insert, update или delete |
SQLNumResultCols | ISO 92 ODBC1.0 | Возвращает число столбцов в результирующем наборе |
SQLDescribeCol | ISO 92 ODBC1.0 | Описывает столбец результирующего набора, возвращая имя поля, его тип, размер и т.п |
SQLColAttribute | ISO 92 ODBC3.0 | Возвращает информацию о столбце результирующего набора. В отличие от функции SQLColAttribute, позволяет получить более обширную информацию о столбце, включая информацию, определяемую конкретным драйвером |
SQLBindCol | ISO 92 ODBC1.0 | Выполняет связывание буфера приложения-клиента со столбцами результирующего набора |
SQLFetch | ISO 92 ODBC1.0 | Извлекает данные одной следующей строки из результирующего набора, возвращая данные для всех связанных столбцов |
SQLFetchScroll | ISO 92 ODBC3.0 | Извлекает данные одной или нескольких строк из результирующего набора, возвращая данные для всех связанных столбцов. Функция позволяет явно указать, какую строку следует извлечь. Данная функция заменила функцию SQLExtendedFetch из ODBC 2.x |
SQLGetData | ISO 92 ODBC1.0 | Извлекает из результирующего набора значение одного столбца одной текущей строки. Для использования этой функции не требуется предварительное связывание столбцов |
SQLSetPos | ODBC ODBC1.0 | Позиционирует курсор в извлеченном блоке данных и позволяет приложению-клиенту: обновлять данные в строке, модифицировать или удалять данные в результирующем наборе |
SQLBulkOperations | ODBC ODBC3.0 | Выполняет несколько вставок или несколько помеченных операций, включая изменение, удаление и выборку по установленному маркеру |
SQLMoreResults | ODBC ODBC1.0 | Определяет, есть ли еще следующий результирующий набор, и при его наличии выполняет переход на него |
SQLGetDiagField | ISO 92 ODBC3.0 | Возвращает значение поля записи из структуры диагностической информации, ассоциированной с конкретным дескриптором (среды, соединения, оператора) |
SQLGetDiagRec | ISO 92 ODBC3.0 | Возвращает значения нескольких предопределенных полей записи из структуры диагностической информации, ассоциированной с конкретным дескриптором (среды, соединения, оператора) |
Функции каталога | ||
SQLColumnPrivileges | ODBC ODBC1.0 | Возвращает список полей и имеющиеся привилегии для одной или нескольких таблиц |
SQLColumns | X/Open ODBC1.0 | Возвращает список имен полей в указанной таблице |
SQLForeignKeys | ODBC ODBC1.0 | Возвращает список полей, которые составляют внешние ключи таблицы, если они созданы |
SQLPrimaryKeys | ODBC ODBC1.0 | Возвращает список полей, которые составляют первичный ключ таблицы |
SQLProcedureColumns | ODBC ODBC1.0 | Возвращает в виде результирующего набора список входных и выходных параметров указанной процедуры |
SQLProcedures | ODBCODBC1.0 | Возвращает список хранимых процедур для подключенного источника данных |
SQLSpecialColumns | X/Open ODBC1.0 | Получает информацию об оптимальном наборе полей, уникально идентифицирующих строку в указанной таблице, или имя поля, которое автоматически обновляется при изменении какого-либо поля в строке |
SQLStatistics | ISO 92 ODBC1.0 | Возвращает информацию о таблице и список индексов, ассоциированных с ней |
SQLTablePrivileges | ODBC ODBC1.0 | Возвращает в виде результирующего набора список таблиц и привилегии, назначенные для каждой таблицы |
SQLTables | X/Open ODBC1.0 | Возвращает в виде результирующего набора список таблиц, хранимых в указанном источнике данных |
Освобождение оператора | ||
SQLFreeStmt | ISO 92 ODBC1.0 | Завершает обработку оператора, удаляет результирующий набор и освобождает все ресурсы, ассоциированные с данным дескриптором оператора |
SQLCloseCursor | ISO 92 ODBC3.0 | Закрывает курсор, открытый с данным дескриптором оператора, и удаляет результирующий набор |
SQLCancel | ISO 92 ODBC1.0 | Завершает выполнение SQL-оператора, прекращая асинхронное выполнение функции, выполнение функции, требующей данные, или функции, выполняемой в другом потоке. В отличие от версии 2.x, данная функция не может выполнить освобождение дескриптора оператора, и требуется явный вызов функции SQLFreeStmt |
SQLEndTran | ISO 92 ODBC3.0 | Выполняет завершение или откат транзакции |
Освобождение соединения | ||
SQLDisconnect | ISO 92 ODBC1.0 | Закрывает соединение с источником данных |
SQLFreeHandle | ISO 92 ODBC3.0 | Освобождает ресурсы, ассоциированные с указанным дескриптором (среды, соединения, оператора, приложения) |
Функции установки
Группа функций установки (setup DLL) объединяет функции, предназначенные для конфигурирования драйверов и источников данных. В следующей таблице приведены функции, относящиеся к данной группе.
Функция | Описание |
---|---|
ConfigDriver | Выполняет установку или удаление драйвера |
ConfigDSN | Выполняет добавление, изменение или удаление источника данных |
ConfigTranslator | Возвращает используемые по умолчанию опции преобразования |
Функции инсталляции
Группа функций инсталляции (installer DLL) объединяет функции, предназначенные для установки ODBC и конфигурирования источников данных. В следующей таблице приведены функции, относящиеся к данной группе.
Функция | Описание |
---|---|
Установка ODBC | |
SQLConfigDriver | Загружает setup DLL для конкретного драйвера |
SQLGetInstalledDrivers | Возвращает список установленных драйверов |
SQLInstallDriverEx | Добавляет в реестр данные о драйвере |
SQLInstallDriverManager | Возвращает каталог, назначенный для менеджера драйверов |
SQLInstallerError | Возвращает информацию об ошибке выполнения функции инсталляции |
SQLInstallTranslatorEx | Добавляет в реестр данные о трансляторе |
SQLRemoveDriver | Удаляет из реестра данные о драйвере |
SQLRemoveDriverManager | Изменяет или удаляет данные о базовых компонентах ODBC из реестра |
SQLRemoveTranslator | Удаляет из реестра данные о трансляторе |
Конфигурирование источников данных | |
SQLConfigDataSource | Вызывает setup DLL для конкретного драйвера |
SQLCreateDataSource | Отображает диалог для добавления источника данных |
SQLGetConfigMode | Запрашивает режим конфигурации, позволяющий определить, где в реестре Windows искать секцию ODBC.INI. Если функция возвращает значение параметра равным ODBC_USER_DSN, то DSN является пользовательским и вход ODBC.INI находится в разделе HKEY_CURRENT_USER (Software|ODBC), а если функция возвращает значение параметра равным ODBC_SYSTEM_DSN или ODBC_BOTH_DSN, то вход ODBC.INI находится в разделе HKEY_LOCAL_MACHINE |
SQLGetPrivateProfileString | Записывает значение в реестр |
SQLGetTranslator | Показывает диалог для выбора транслятора |
SQLManageDataSources | Отображает диалог для конфигурирования драйверов и источников данных |
SQLReadFileDSN | Читает информацию о DSN из файла |
SQLRemoveDefaultDataSource | Удаляет источник данных по умолчанию |
SQLRemoveDSNFromIni | Удаляет источник данных |
SQLSetConfigMode | Устанавливает режим конфигурации, указывающий, где в реестре будет использоваться вход ODBC.INI |
SQLValidDSN | Проверяет правильность имени источника данных |
SQLWriteDSNToIni | Добавляет источник данных |
SQLWriteFileDSN | Записывает информацию о DSN в файл |
SQLWritePrivateProfileString | Запрашивает значение из реестра Windows |
Соответствие версий ODBC API
Если приложение использует функции ODBC 2.x с менеджером драйверов ODBC 3.x, то менеджер драйверов подменяет вызываемую функцию и передает драйверу ODBC 3.x вызов функции в соответствии со следующей таблицей.
Функции ODBC 2.x | Функции ODBC 3.x |
---|---|
SQLAllocConnect | SQLAllocHandle |
SQLAllocEnv | SQLAllocHandle |
SQLAllocStmt | SQLAllocHandle |
SQLBindParam (для стандарта X/Open и ISO) | SQLBindParameter |
SQLColAttributes | SQLColAttribute |
SQLError | SQLGetDiagRec |
SQLFreeConnect | SQLFreeHandle |
SQLFreeEnv | SQLFreeHandle |
SQLFreeStmt | SQLFreeHandle |
SQLGetConnectOption | SQLGetConnectAttr |
SQLGetStmtOption | SQLGetStmtAttr |
SQLParamOptions | SQLSetStmtAttr |
SQLSetConnectOption | SQLSetConnectAttr |
SQLSetParam [функция ODBC 1.0] | SQLBindParameter |
SQLSetScrollOption | SQLSetStmtAttr |
SQLSetStmtOption | SQLSetStmtAttr |
SQLTransact | SQLEndTran |
Дескрипторы
Создание дескрипторов
Перед использованием функций 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 и не требуют регистрации версии приложения).
