附录 B：ODBC 状态转换表
本附录中的表显示了 ODBC 函数如何导致环境、连接、语句和描述符状态的转换。 环境、连接、语句或描述符的状态通常决定何时可以调用使用相应类型的句柄的函数 (环境、连接、语句或描述符) 。 环境、连接、语句和描述符状态大致重叠，如下图所示。 例如，连接状态 C5 和 C6 的完全重叠以及语句状态 S1 到 S12 的完全重叠依赖于数据源， 因为事务从不同数据源的不同时间开始，而描述符状态 D1i (隐式分配的描述符) 取决于与描述符关联的语句的状态，而状态 D1e (显式分配的描述符) 独立于任何语句的状态。 有关每种状态的说明，请参阅本附录后面的 环境转换、 连接转换、 语句转换和 描述符转换。
环境和连接状态重叠，如下所示：
连接和语句状态重叠，如下所示：
语句和描述符状态重叠，如下所示：
连接和描述符状态重叠，如下所示：
转换表中的每个条目可以是以下值之一：
-- -执行函数后状态保持不变。
E
n 、 C_n_、 S_n_ 或 D_n_ - 环境、连接、语句或描述符状态将移动到指定状态。
(IH) - 传递给函数的句柄无效。 如果句柄是空句柄或错误类型的有效句柄（例如，需要语句句柄时传递了连接句柄），则该函数将返回SQL_INVALID_HANDLE;否则，该行为是未定义的，可能是致命的。 仅当它是在指定状态下调用函数的唯一可能结果时，才会显示此错误。 此错误不会更改状态，并且始终由驱动程序管理器检测到，如括号所示。
NS - 下一个状态。 语句转换与语句未经历异步状态时相同。 例如，假设创建结果集的语句从状态 S1 进入状态 S11，因为 SQLExecDirect 返回SQL_STILL_EXECUTING。 状态 S11 中的 NS 表示法意味着语句的转换与创建结果集的状态 S1 中的语句的转换相同。 如果 SQLExecDirect 返回错误，则语句保持状态 S1;如果成功，则语句将移动到状态 S5;如果需要数据，则语句将移动到状态 S8;如果仍在执行，则保持 S11 状态。
XXXXX 或 (XXXXX) - 与转换表相关的 SQLSTATE;驱动程序管理器检测到的 SQLSTATEs 括在括号中。 函数返回SQL_ERROR和指定的 SQLSTATE，但状态不会更改。 例如，如果在 SQLPrepare 之前调用 SQLExecute，它将返回 SQLSTATE HY010 (函数序列错误) 。
注意
这些表不显示与不更改状态的转换表无关的错误。 例如，当在环境状态 E1 中调用 SQLAllocHandle 并返回 SQLSTATE HY001 (内存分配错误) 时，环境仍处于状态 E1;这不会显示在 SQLAllocHandle 的环境转换表中。
如果环境、连接、语句或描述符可以移动到多个状态，则会显示每个可能的状态，并用一个或多个脚注解释每次转换发生的条件。 以下脚注可能会出现在任何表中。
| 脚注 | 含义 |
|---|---|
| b | 之前或之后。 光标位于结果集开始之前或结果集末尾之后。 |
| c | 当前函数。 当前函数正在异步执行。 |
| d | 需要数据。 函数返回SQL_NEED_DATA。 |
| e | 错误。 函数返回SQL_ERROR。 |
| i | 行无效。 游标位于结果集中的某一行上，该行已被删除，或者该行的操作中出错。 如果存在行状态数组，则行状态数组中的值SQL_ROW_DELETED或SQL_ROW_ERROR。 (SQL_ATTR_ROW_STATUS_PTR 语句 attribute 指向行状态数组。) |
| nf | 未找到。 函数返回SQL_NO_DATA。 当 SQLExecDirect、 SQLExecute 或 SQLParamData 在执行搜索的更新或删除语句后返回SQL_NO_DATA时，这不适用。 |
| np | 未准备好。 语句未准备好。 |
| nr | 没有结果。 语句不会或未创建结果集。 |
| o | 其他函数。 另一个函数正在异步执行。 |
| p | 准备。 声明已准备好。 |
| r | 结果。 语句将或确实创建一个可能为空 (结果集) 。 |
| s | 成功。 函数返回SQL_SUCCESS_WITH_INFO或SQL_SUCCESS。 |
| v | 有效行。 游标位于结果集中的某一行上，并且该行已成功插入、成功更新，或者该行的其他操作已成功完成。 如果存在行状态数组，则行状态数组中的值SQL_ROW_ADDED、SQL_ROW_SUCCESS或SQL_ROW_UPDATED。 (SQL_ATTR_ROW_STATUS_PTR 语句 attribute 指向行状态数组。) |
| x | 正在执行。 函数返回SQL_STILL_EXECUTING。 |
SQLFreeHandle
在此示例中， SQLFreeHandle 的环境状态转换表中当 HandleType SQL_HANDLE_ENV的行如下所示。
| E0 未分配 |
E1 已分配 |
E2 连接 |
|---|---|---|
| (IH) | E0 | (HY010) |
如果在将 HandleType 设置为 SQL_HANDLE_ENV 的环境状态 E0 中调用 SQLFreeHandle，驱动程序管理器将返回SQL_INVALID_HANDLE。 如果在 HandleType 设置为 SQL_HANDLE_ENV 的情况下在状态 E1 中调用它，则如果函数成功，环境将移动到状态 E0，如果函数失败，则环境将保持为状态 E1。 如果在 将 HandleType 设置为 SQL_HANDLE_ENV 的情况下在状态 E2 中调用它，驱动程序管理器始终返回 SQL_ERROR，SQLSTATE HY010 (函数序列错误) 且环境仍处于状态 E2。
若要了解状态转换表，需要了解它们引用的环境、连接、语句或描述符) (项。 假设函数接受类型为 X 的项的句柄。该函数的 X 状态转换表描述了调用函数（具有 X 类型项的句柄）如何影响该项。 例如， SQLDisconnect 接受连接句柄。 SQLDisconnect 的连接状态转换表描述了 SQLDisconnect 如何影响调用它的连接状态。
假设函数接受类型为 Y 的项的句柄，其中 Y 不等于 X。该函数的 X 状态转换表描述了调用与类型为 Y 的项关联的 X 类型的句柄的函数如何影响类型为 Y 的项。例如， SQLDisconnect 的语句状态转换表描述了使用与语句关联的连接的句柄调用 SQLDisconnect 如何影响语句的状态。
本附录包含以下主题。