Открытый интерфейс доступа к базам данных - ODBC

Создание источника данных с использованием ODBC API

DLL-библиотека ODBCCP32.DLL предоставляет функции ODBC API ConfigDSN и SQLConfigDataSource, позволяющие выполнять регистрацию новых источников данных или удалять информацию об источниках данных из реестра Windows (и из файла ODBC.ini).

Функция ConfigDSN позволяет добавлять, изменять или удалять источники данных и имеет следующее формальное описание:

BOOL ConfigDSN(
     HWND     hwndParent,
     WORD     fRequest,
     LPCSTR     lpszDriver,
     LPCSTR     lpszAttributes);

Для использования в среде Visual Studio функций ConfigDSN и SQLConfigDataSource следует подключить заголовочный файл odbcinst.h.

Параметр hwndParent определяет дескриптор окна или NULL. Если дескриптор не указан, то при выполнении данной функции окно с предложением уточнить параметры не отображается. Параметр fRequest указывает тип запроса, который задается одной из следующих констант:

• ODBC_ADD_DSN - добавление нового источника данных;
• ODBC_CONFIG_DSN - изменение существующего источника данных;
• ODBC_REMOVE_DSN - удаление существующего источника данных.

Параметр lpszDriver содержит описание драйвера, а параметр lpszAttributes - список атрибутов в форме "ключевое слово=значение" (например: DSN=MyDB\0UID=U1\0PWD=P1\0DATABASE=DB1\0\0). Список атрибутов завершается двумя null-байтами.

При успешном завершении функция возвращает значение TRUE, в противном случае вызовом функции SQLInstallerError можно получить один из следующих кодов ошибки:

• ODBC_ERROR_INVALID_HWND - ошибка в указании дескриптора окна;
• ODBC_ERROR_INVALID_KEYWORD_VALUE - параметр lpszAttributes содержит ошибки;
• ODBC_ERROR_INVALID_NAME - параметр lpszDriver не найден в системе;
• ODBC_ERROR_INVALID_REQUEST_TYPE - параметр fRequest содержит недопустимое значение;
• ODBC_ERROR_REQUEST_FAILED - нельзя выполнить действие, указанное параметром fRequest ;
• ODBC_ERROR_DRIVER_SPECIFIC - ошибка конкретного драйвера.

Для записи информации об источнике данных в секцию [ODBC Data Sources] секции ODBC.INI реестра Windows функция ConfigDSN вызывает функцию SQLWriteDSNToIni, а для удаления - функцию SQLRemoveDSNFromIni.

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

BOOL SQLConfigDataSource(
     HWND      hwndParent,
     WORD     fRequest,
     LPCSTR      lpszDriver,
     LPCSTR      lpszAttributes);

Параметры функции SQLConfigDataSource аналогичны параметрам функции ConfigDSN, при этом параметр fRequest может принимать следующие значения:

• ODBC_ADD_DSN - добавление нового пользовательского DSN;
• ODBC_CONFIG_DSN - изменение существующего пользовательского DSN;
• ODBC_REMOVE_DSN - удаление существующего пользовательского DSN;
• ODBC_ADD_SYS_DSN - добавление нового системного DSN;
• ODBC_CONFIG_SYS_DSN - изменение существующего системного DSN;
• ODBC_REMOVE_SYS_DSN - удаление существующего системного DSN.

Функция ConfigDSN относится к группе функций установки DLL (setup DLL), а функция SQLConfigDataSource - к группе функций инсталляции DLL (Installer DLL).

При выполнении функция SQLConfigDataSource использует значение параметра lpszDriver для получения из системной информации полного пути к Setup DLL конкретного драйвера, загружает эту DLL и вызывает функцию ConfigDSN, передавая ей свой список параметров (значение параметра fRequest преобразуется к значению, принимаемому функцией ConfigDSN ). Перед вызовом ConfigDSN, в зависимости от типа обрабатываемого DSN, устанавливается режим USERDSN_ONLY (пользовательский DSN) или SYSTEMDSN_ONLY (системный DSN), а перед завершением выполнения функция SQLConfigDataSource возвращает режим BOTHDSN.

Коды возврата

Все функции ODBC API возвращают значения, называемые кодами возврата. Код возврата определяет, была ли функция выполнена успешно, или характеризует тип произошедшей ошибки.

В заголовочном файле sql.h определены следующие коды возврата:

#define SQL_SUCCESS            0

#define SQL_SUCCESS_WITH_INFO  1

#if (ODBCVER >= 0x0300)
#define SQL_NO_DATA           100
#endif

#define SQL_ERROR            (-1)

#define SQL_INVALID_HANDLE   (-2)

#define SQL_STILL_EXECUTING    2

#define SQL_NEED_DATA         99

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

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

typedef signed short            RETCODE;