Прежде чем прикладная программа сможет вызвать какую-либо из функций ODBC, она обязана выполнить инициализацию ODBC и установить окружение. ODBC использует окружение для отслеживания соединений с базой данных, установленного прикладной программой. В рамках одного окружения можно установить произвольное число соединений. Назначение окружения производится функцией ODBC SQLAllocEnv() и имеет следующий синтаксис
RETCODE SQLAllocEnv(phenv)
Таблица 4 Параметр для SQLAllocEnv
| Тип | Аргумент | Использование | Описание |
| HENV* | phenv | Выход (аналог параметра out для PL/SQL ORACLE) | Указатель области хранения в памяти идентификатора окружения |
Описание параметра SQLAllocEnv приведено в таблице 4. Освобождение идентификатора окружения происходит при вызове функции 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. Параметры её представлены в таблице 5:
Таблица 5 Параметры SQLAllocConnect
| Тип | Аргумент | Использование | Описание |
| HENV | henv | Вход | Идентификатор окружения прикладной программы |
| HDBC* | phdbc | Выход | Указатель области хранения памяти для идентификатора соединения |
Менеджер драйверов распределяет память для соединения и возвращает идентификатор через phdbc. Парная для SQLAllocConnect функция SQLFreeConnect() освобождает идентификатор доступа и возвращает все назначенные SQLAllocConnect ресурсы (освобождает всю связанную с ним память):
RETCODE SQLFreeConnect(hdbc)
Здесь параметр hdbc – входной параметр представляющий освобождаемое соединение. Освобождение идентификатора соединения производится после разрыва соединения с источником данных ODBC на этапе завершения, когда необходимо освободить все ресурсы занятые прикладной программой. В случае необходимости соединения с очередным источником данных, назначенный ранее идентификатор можно использовать без каких-либо ограничений, однако после освобождения, идентификатор становится недействительным и не пригоден для соединения. В этом случае требуется выполнить его повторное назначение.
На базовом уровне API поддерживается лишь одна функция соединения, хотя на расширенных уровнях их достаточно много. В данном пособии ограничимся рассмотрением функции SQLConnect() базового уровня.
SQLConnect() загружает драйвер и устанавливает соединение с источником данных. Идентификатор соединения ссылается на местоположение области хранения всей информации о соединении, включая его статус, состояние транзакции и информацию об ошибке. Синтаксис данной функции следующий:
RETCODE SQLConnect (hdbc, szDSN, sbDSN, szUID, sbUID, szAuthStr,
cbAuthStr)
Таблица 6 Параметры SQLConnect
| Тип | Аргумент | Использование | Описание |
| HDBC | hdbc | Вход | Идентификатор соединения |
| UCHAR* | szDSN | Вход | Имя источника данных |
| SWORD | sbDSN | Вход | Длина szDSN. Может быть SQL_NTS в случае если строка имеет нулевое окончание. |
| UCHAR* | szUID | Вход | Имя пользователя |
| SWORD | sbUID | Вход | Длина szUID или SQL_NTS |
| UCHAR* | szAuthStr | Вход | Строка авторизации |
| SWORD | cbAuthStr | Вход | Длина строки авторизации или SQL_NTS |
Значение SQL_NTS (null terminated string) удобно использовать в случае задания строковых литералов либо указателей на таковые в качестве имен источника данных, пользователя и пароля. В синтаксисе языка С строкой-константой с автоматически выставляемым нулевым окончанием является, как известно последовательность символов взятая в парные двойные кавычки. Если источник данных не требует имени пользователя, то в функцию должны быть переданы либо нулевое значение, либо пустая строка (строка, состоящая лишь из нуль - терминатора), в качестве же размера указывается либо нулевое значение, либо SQL_NTS соответственно. То же самое касается и строки авторизации.
Так для того, чтобы установить соединение с источником данных, требующим имя пользователя и пароль, вызов SQLConnect может быть следующим:
RETCODE rc;
//…промежуточные операторы
rc=SQLConnect (hdbc, “RESTAURANTS”, SQL_NTS, “OWNER”,
SQL_NTS, “ICE-CREAM”, SQL_NTS).
Разрыв соединения с источником данных выполняет вызов SQLDisconnect():
RETCODE SQLDisconnect(hdbc)
Здесь hdbc – входной параметр функции, представляющий идентификатор доступа для отсоединения.
Выполнение операторов
В данном разделе рассмотрим два набора функций: функции управления каталогом и выполнения SQL – операторов. Функции управления каталогом возвращают информацию из системного каталога источника данных: имена таблиц, столбцов, табличную статистику и т. д. Функции выполнения операторов включают в себя функции непосредственного и подготовленного выполнения и связывания параметров.
Любая функция, которая имеет отношение к обработке или передаче SQL – оператора, требует в качестве параметра идентификатор оператора. Идентификатор оператора аналогичен идентификатору окружения или соединения за исключением того, что он ссылается на SQL – оператор. Идентификатор соединения может быть связан с несколькими идентификаторами операторов, но каждый идентификатор оператора связан только со своим идентификатором соединения. Назначение идентификатора оператора производится вызовом SQLAllocStmt(), которая выделяет область хранения в памяти для идентификатора оператора и связывает его с соединением, которое определяется собственным идентификатором.
Синтаксис для SQLAllocStmt() имеет вид:
RETCODE SQLAllocStmt(hdbc, phstmt)
Таблица 7 Описание параметров SQLAllocStmt()
| Тип | Аргумент | Использование | Описание |
| HDBC | hdbc | Вход | Идентификатор соединения |
| HSTMT* | phstmt | Выход | Указатель области хранения в памяти для идентификатора оператора |
Парная для SQLAllocStmt() функция SQLFreeStmt() выполняет следующие действия:
● Останавливает любые SQL – операторы, которые в данный момент обрабатываются и связаны с заданным идентификатором оператора,
● Закрывают любые открытые курсоры, которые имеют отношение к определенному идентификатору оператора,
● Отбрасывает ожидаемые результаты,
●Дополнительно, освобождает все ресурсы, связанные с определенным идентификатором оператора.
Синтаксис SQLFreeStmt() имеет следующий вид:
RETCODE SQLFreeStmt (hstmt, fOption)
Таблица 8 Функция SQLFreeStmt
| Тип | Аргумент | Использование | Описание |
| HSTMT | hstmt | Вход | Идентификатор оператора |
| UWORD | fOption | Вход | Одна из следующих опций: ●SQL_CLOSE, ●SQL_DROP ●SQL_UNBIND ●SQL_RESET_PARAMS |
Опция SQL_CLOSE отбрасывает неизвлечённые результаты и закрывает любые связанные с ними курсоры. Эта опция не влияет на соответствующие параметры, подготовленные операторы или соответствующие столбцы результата.
SQL_DROP освобождает все ресурсы, связанные с идентификатором, закрывает курсор, если он открыт и отбрасывает все ожидаемые строки результирующего множества. Эта опция завершает все обращения к hstmt, так как после успешного вызова SQLFreeStmt с этим параметром, идентификатор становится недействительным.
SQL_UNBIND освобождает (“отвязывает”) все буферы столбцов, связанные со столбцами результирующего множества запроса посредством SQLBindCol(). Описание данной функции приведено в разделе 2.5 данного методического пособия.
SQL_RESET_PARAMS освобождает все буферы параметров с фактическими значениями, связанные с маркерами параметров строки запроса. Связывание формальных параметров запроса (маркеров) с буферами фактических значений производится функцией SQLBindParametr(), описание которой приводится ниже в данном разделе.