SQLSTATEs

SQLSTATE 提供与警告或错误的原因有关的详细信息。 本手册中的 SQLSTATE 基于 ISO/IEF CLI 规范中找到的 SQLSTATE，但以 IM 开头的 SQLSTATE 特定于 ODBC。

与返回代码不同，本手册中的 SQLSTATE 是指南，不要求驱动程序返回这些内容。 因此，尽管驱动程序应为其能够检测的任何错误或警告返回正确的 SQLSTATE，但应用程序不必始终考虑这种情况。 这种情况的原因有两个：

• 不完整性 虽然此手册列出了大量错误和警告以及这些错误和警告的可能原因，但并不完整，而且可能永远无法完整；驱动程序的实现变化太多。 任何给定的驱动程序都可能不返回此手册中列出的 SQLSTATE，却可能会返回此手册中未列出的 SQLSTATE。

• 复杂性 某些数据库引擎（尤其是关系数据库引擎）返回数千个错误和警告。 此类引擎的驱动程序不太可能将所有错误和警告都映射到 SQLSTATE，这是因为所涉及的工作量、映射的不精确性、结果代码的大小以及结果代码的低值，通常会返回运行时不应遇到的编程错误。 因此，驱动程序应合理地映射尽可能多的错误和警告，并确保映射应用程序逻辑可能基于的错误和警告，例如 SQLSTATE 01004（数据被截断）。

由于 SQLSTATE 未可靠返回，因此大多数应用程序只是将其与关联的诊断消息显示给用户，诊断消息通常针对发生的特定错误或警告以及本机错误代码进行定制。 这样做很少会丢失功能，因为应用程序无论如何都不会基于大多数 SQLSTATE 确定编程逻辑。 例如，假设 SQLExecDirect 返回 SQLSTATE 42000（语法错误或访问冲突）。 如果导致此错误的 SQL 语句由应用程序硬编码或生成，则这是编程错误，需要修复代码。 如果 SQL 语句是用户输入的，则这是用户错误，应用程序已通过将问题通知用户完成所有操作。

当应用程序基于 SQLSTATE 确定编程逻辑时，应为不返回 SQLSTATE 或返回其他 SQLSTATE 做好准备。 确切地说，可靠地返回哪些 SQLSTATE 只能基于大量驱动程序的经验。 但是，一般准则是，驱动程序或驱动程序管理器而不是数据源中所发生错误的 SQLSTATE 更有可能可靠地返回。 例如，大多数驱动程序可能返回 SQLSTATE HYC00（未实现可选功能），而少数驱动程序可能会返回 SQLSTATE 42021（列已存在）。

以下 SQLSTATE 表示运行时错误或警告，是编程逻辑的良好基础。 但是，不能保证所有驱动程序都返回这些内容。

• 01004（数据已截断）

• 01S02（选项值已更改）

• HY008（操作已取消）

• HYC00（未实现可选功能）

• HYT00（超时已过期）

SQLSTATE HYC00（未实现可选功能）尤其重要，因为这是应用程序确定驱动程序是否支持特定语句或连接属性的唯一方式。

有关 SQLSTATE 的完整列表以及哪些函数返回这些语句，请参阅附录 A：ODBC 错误代码。 有关每个函数可能返回特定 SQLSTATE 的条件的详细说明，请参阅该函数。