Приложение Б. Таблицы перехода состояния ODBC
В таблицах этого приложения показано, как функции ODBC вызывают переходы среды, соединения, инструкции и дескриптора. Состояние среды, соединения, оператора или дескриптора обычно определяет, когда функции, использующие соответствующий тип дескриптора (среда, соединение, оператор или дескриптор). Состояние среды, соединения, оператора и дескриптора перекрывается примерно так, как показано на следующих рисунках. Например, точное перекрытие состояний подключения C5 и C6 и операторов S1–S12 зависит от источника данных, так как транзакции начинаются в разное время в разных источниках данных, а состояние дескриптора D1i (неявно выделенного дескриптора) зависит от состояния оператора, с которым связан дескриптор, а состояние D1e (явно выделенный дескриптор) не зависит от состояния любого оператора. Описание каждого состояния см. в разделе "Переходы среды", "Переходы подключений", "Переходы операторов" и "Дескрипторные переходы" далее в этом приложении.
Состояния среды и подключения перекрываются следующим образом:
Соединение и оператор перекрываются следующим образом:
Оператор и дескриптор состояния перекрываются следующим образом:
Состояния подключения и дескриптора перекрываются следующим образом:
Каждая запись в таблице перехода может быть одним из следующих значений:
-- -Состояние не изменяется после выполнения функции.
E
n, C_n_, S_n_ или D_n_ — среда, соединение, оператор или дескриптор перемещается в указанное состояние.
(IH) — Недопустимый дескриптор был передан функции. Если дескриптор был пустым или был допустимым дескриптором неправильного типа, например, дескриптор соединения был передан при необходимости дескриптора инструкции — функция возвращает SQL_INVALID_HANDLE; в противном случае поведение не определено и, вероятно, неустранимо. Эта ошибка отображается только в том случае, если это единственный возможный результат вызова функции в указанном состоянии. Эта ошибка не изменяет состояние и всегда обнаруживается диспетчером драйверов, как указано в скобках.
NS — следующее состояние. Переход инструкции совпадает с тем, что если оператор не прошел через асинхронные состояния. Например, предположим, что инструкция, создающая результирующий набор, вводит состояние S11 из состояния S1, так как SQLExecDirect вернул SQL_STILL_EXECUTING. Нотация NS в состоянии S11 означает, что переходы для инструкции совпадают с инструкциями в состоянии S1, создающей результирующий набор. Если SQLExecDirect возвращает ошибку, инструкция остается в состоянии S1; если она выполнена успешно, оператор перемещается в состояние S5; если он нуждается в данных, оператор перемещается в состояние S8, а если он по-прежнему выполняется, он остается в состоянии S11.
XXXXX или (XXXXX) — SQLSTATE, связанный с таблицей перехода; SQLSTATEs, обнаруженные диспетчером драйверов, заключены в скобки. Функция возвращает SQL_ERROR и указанную среду SQLSTATE, но состояние не изменяется. Например, если SQLExecute вызывается перед SQLPrepare, он возвращает SQLSTATE HY010 (ошибка последовательности функций).
Заметка
В таблицах не отображаются ошибки, не связанные с таблицами перехода, которые не изменяют состояние. Например, когда SQLAllocHandle вызывается в состоянии среды E1 и возвращает SQLSTATE HY001 (ошибка выделения памяти), среда остается в состоянии E1; это не отображается в таблице перехода среды для SQLAllocHandle.
Если среда, соединение, оператор или дескриптор могут перемещаться в несколько состояний, отображается каждое возможное состояние, а одно или несколько сносок объясняют условия, при которых происходит каждый переход. Следующие сноски могут отображаться в любой таблице.
| Сноски | Значение |
|---|---|
| б | До или после. Курсор был размещен до начала результирующий набор или после окончания результирующий набор. |
| в | Текущая функция. Текущая функция выполняется асинхронно. |
| дн. | Требуются данные. Функция вернула SQL_NEED_DATA. |
| Д. | Ошибка. Функция возвращает SQL_ERROR. |
| i | Недопустимая строка. Курсор был размещен на строке в результирующем наборе, а строка была удалена или произошла ошибка в операции с строкой. Если массив состояния строки существовал, значение в массиве состояния строки для строки было SQL_ROW_DELETED или SQL_ROW_ERROR. (Массив состояния строки указывает на атрибут оператора SQL_ATTR_ROW_STATUS_PTR.) |
| nf | Не найдено. Функция вернула SQL_NO_DATA. Это не применяется, если SQLExecDirect, SQLExecute или SQLParamData возвращает SQL_NO_DATA после выполнения инструкции поиска по обновлению или удалению. |
| np | Не подготовлен. Заявление не было подготовлено. |
| nr | Нет результатов. Оператор не создаст результирующий набор. |
| o | Другая функция. Другая функция выполняется асинхронно. |
| п | Подготовлены. Заявление было подготовлено. |
| r | Результаты . Оператор будет или сделал создание результирующий набор (возможно, пустой). |
| s | Успешно. Функция возвращает SQL_SUCCESS_WITH_INFO или SQL_SUCCESS. |
| v | Допустимая строка. Курсор был размещен на строке в результирующем наборе, и строка была успешно вставлена, успешно обновлена или другая операция в строке успешно завершена. Если массив состояния строки существовал, значение в массиве состояния строки для строки было SQL_ROW_ADDED, SQL_ROW_SUCCESS или SQL_ROW_UPDATED. (Массив состояния строки указывает на атрибут оператора SQL_ATTR_ROW_STATUS_PTR.) |
| x | Выполняющиеся. Функция возвращает SQL_STILL_EXECUTING. |
SQLFreeHandle
В этом примере строка в таблице перехода состояния среды для SQLFreeHandleпри SQL_HANDLE_ENV HandleType выглядит следующим образом.
| E0 Не выделено |
E1 Распределено |
E2 Connection |
|---|---|---|
| (IH) | E0 | (HY010) |
Если SQLFreeHandle вызывается в состоянии среды E0 с параметром HandleType с значением SQL_HANDLE_ENV, диспетчер драйверов возвращает SQL_INVALID_HANDLE. Если он вызывается в состоянии E1 с параметром HandleType с значением SQL_HANDLE_ENV, среда перемещается в состояние E0, если функция завершается успешно и остается в состоянии E1, если функция завершается ошибкой. Если он вызывается в состоянии E2 с параметром HandleType для SQL_HANDLE_ENV, диспетчер драйверов всегда возвращает SQL_ERROR и SQLSTATE HY010 (ошибка последовательности функций), а среда остается в состоянии E2.
Чтобы понять таблицы перехода состояния, необходимо понять, какой элемент (среда, соединение, оператор или дескриптор) они ссылаются. Предположим, что функция принимает дескриптор элемента типа X. Таблица перехода состояния X для этой функции описывает, как вызывает функцию с дескриптором элемента типа X, влияет на этот элемент. Например, SQLDisconnect принимает дескриптор подключения. Таблица перехода состояния подключения для SQLDisconnect описывает, как SQLDisconnect влияет на состояние подключения, для которого он вызывается.
Предположим, что функция принимает дескриптор типа Y, где Y не равен X. Таблица перехода состояния X для этой функции описывает вызов функции с дескриптором типа X, связанным с элементом типа Y, влияет на элемент типа Y. Например, таблица перехода состояния инструкции для SQLDisconnect описывает, как SQLDisconnect влияет на состояние инструкции при вызове с дескриптором соединения, с которым связана инструкция.
Это приложение содержит следующие разделы.