Прежде чем прикладная программа сможет вызвать какую-либо из функций ODBC, она обязана выполнить инициализацию ODBC и установить окружение. ODBC использует окружение для отслеживания соединений с базой данных, установленного прикладной программой. В рамках одного окружения можно установить произвольное число соединений. Назначение окружения производится функцией ODBC SQLAllocEnv() и имеет следующий синтаксис: RETCODE SQLAllocEnv (phenv)
Таблица 19 Параметр для SQLAllocEnv
Тип
Аргумент
Использование
Описание
HENV*
phenv
Выход (аналог параметра out для PL/SQL ORACLE)
Указатель области хранения в памяти идентификатора окружения
Описание параметра SQLAllocEnv приведено в таблице 19. Освобождение идентификатора окружения происходит при вызове функции SQLFreeEnv(). Вызов данной функции производится в программе последним. Описание её в ODBC имеет следующий вид:
RETCODE SQLFreeEnv(phenv)
Здесь параметр PHENV имеет тот же смысл, что и в функции назначения окружения, однако в данном случае – это не “назначаемый”, а “освобождаемый” идентификатор и в отличие от SQLAllocEnv является входным (аналог in в PL/SQL).
Так же, как окружение прикладной программы представляется с помощью идентификатора окружения, идентификатор соединения представляет соединение между источником данных и прикладной программой. В отличие от окружения, идентификатор которого в программе один, идентификаторов соединения может назначаться несколько, для каждого источника данных, с которым прикладная программа предполагает соединиться. Назначение идентификаторов соединения производится посредством SQLAllocConnect(). Синтаксис её следующий:
RETCODE SQLAllocConnect(henv, phdbc)
При вызове функция может возвращать: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE. Параметры её представлены в таблице 20:
Таблица 20 Параметры SQLAllocConnect
Тип
Аргумент
Использование
Описание
HENV
henv
Вход
Идентификатор окружения прикладной программы
HDBC*
phdbc
Выход
Указатель области хранения памяти для идентификатора соединения
Менеджер драйверов распределяет память для соединения и возвращает идентификатор через PHDBC. Парная для SQLAllocConnect функция SQLFreeConnect() освобождает идентификатор доступа и возвращает все назначенные SQLAllocConnect ресурсы (освобождает всю связанную с ним память):
RETCODE SQLFreeConnect(hdbc)
Здесь параметр HDBC – входной параметр представляющий освобождаемое соединение. Освобождение идентификатора соединения производится после разрыва соединения с источником данных ODBC на этапе завершения, когда необходимо освободить все ресурсы занятые прикладной программой. В случае необходимости соединения с очередным источником данных, назначенный ранее идентификатор можно использовать без каких-либо ограничений, однако после освобождения, идентификатор становится недействительным и не пригоден для соединения. В этом случае требуется выполнить его повторное назначение.
На базовом уровне API поддерживается лишь одна функция соединения, хотя на расширенных уровнях их достаточно много. В данном пособии ограничимся рассмотрением функции SQLConnect() базового уровня.
SQLConnect() загружает драйвер и устанавливает соединение с источником данных. Идентификатор соединения ссылается на местоположение области хранения всей информации о соединении, включая его статус, состояние транзакции и информацию об ошибке. Синтаксис данной функции следующий:
Длина szDSN. Может быть SQL_NTS в случае если строка имеет нулевое окончание.
UCHAR*
szUID
Вход
Имя пользователя
SWORD
sbUID
Вход
Длина szUID или SQL_NTS
UCHAR*
szAuthStr
Вход
Строка авторизации
SWORD
cbAuthStr
Вход
Длина строки авторизации или SQL_NTS
Значение SQL_NTS (null terminated string) удобно использовать в случае задания строковых литералов либо указателей на таковые в качестве имен источника данных, пользователя и пароля. В синтаксисе языка С строкой-константой с автоматически выставляемым нулевым окончанием является, как известно последовательность символов взятая в парные двойные кавычки. Если источник данных не требует имени пользователя, то в функцию должны быть переданы либо нулевое значение, либо пустая строка (строка, состоящая лишь из нуль-терминатора), в качестве же размера указывается либо нулевое значение, либо SQL_NTS соответственно. То же самое касается и строки авторизации.
Так для того, чтобы установить соединение с источником данных, требующим имя пользователя и пароль, вызов SQLConnect может быть следующим:
