Функції ODBC API

Основні функції ODBC

Як уже зазначалося в попередній лекції, всі функції API ODBC умовно можна розділити на чотири групи:

• основні функції 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 для кожної програми драйвери можуть підтримувати необмежену кількість дескрипторів кожного типу. Однак, конкретний драйвер може накладати деякі обмеження на кількість дескрипторів.

Функція, яка використовується для створення дескриптора оточення, з'єднання, оператора або програми,має такий формальний опис:

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

Параметр InputHandle ([Input]) визначає контекст, до якого додається створюваний дескриптор. Якщо тип дескриптора SQL_HANDLE_ENV, то параметр InputHandle вказується константою SQL_NULL_HANDLE. При створенні дескриптора середовища параметр InputHandle задає дескриптор оточення, а створення дескриптора оператора ( SQL_HANDLE_STMT ) і дескриптора програми ( SQL_HANDLE_DESC ) - дескриптор з'єднання.

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

Параметр 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 3x). .

---