учебники, программирование, основы, введение в,

 

Функции 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 и не требуют регистрации версии приложения).

 

 
На главную | Содержание | < Назад....Вперёд >
С вопросами и предложениями можно обращаться по nicivas@bk.ru. 2013 г.Яндекс.Метрика