33.8. 错误处理

33.8.1. 设置回调

当产生特定条件时，捕获错误和警告的一个简单方法是设置一个要执行的具体操作。通常：

EXEC SQL WHENEVER condition action;

condition 可以是下列之一：

action 可以是下列之一：

SQL标准仅仅提供 CONTINUE 和 GOTO (和 GO TO ）操作。 下面是一个你可能想在简单程序中使用的例子。当发生警告以及发生错误终止程序时， 它输出一个简单消息：

EXEC SQL WHENEVER SQLWARNING SQLPRINT;
EXEC SQL WHENEVER SQLERROR STOP;

语句 EXEC SQL WHENEVER 是SQL预处理器的指令。 而不是C语句。 错误或者警告操作设置处理器出现的地方中适用的所有嵌入SQL语句。 除非在第一个 EXEC SQL WHENEVER 和产生条件的SQL语句之间 为同一条件设置不同的操作，不管C程序中的控制流。 所以下面两个C程序片段都不会产生期望效果： * WRONG int main(int argc, char *argv[]) if (verbose) { EXEC SQL WHENEVER SQLWARNING SQLPRINT; EXEC SQL SELECT ...; * WRONG int main(int argc, char *argv[]) set_error_handler(); EXEC SQL SELECT ...; static void set_error_handler(void) EXEC SQL WHENEVER SQLERROR STOP;

33.8.2. sqlca

为了更强大的错误处理， 嵌入SQL接口提供了使用下列结构的名字 sqlca （SQL通信区） 的全局变量。

struct
    char sqlcaid[8];
    long sqlabc;
    long sqlcode;
    struct
        int sqlerrml;
        char sqlerrmc[SQLERRMC_LEN];
    } sqlerrm;
    char sqlerrp[8];
    long sqlerrd[6];
    char sqlwarn[8];
    char sqlstate[5];
} sqlca;

（在一个多线程程序中，每一个线程自动获取 sqlca 的拷贝。该工作类似于标准C全局变量 errno 的处理。）

sqlca 涵盖警告和错误。如果在语句执行期间发生 多个警告和错误，那么 sqlca 将只包含最后一个信息。

如果在最后 SQL 语句没有发生错误，则 sqlca.sqlcode 为0， sqlca.sqlstate 是 "00000" 。如果发生了警告或者错误，那么 sqlca.sqlcode 是负数并且 sqlca.sqlstate 不同于 "00000" 。正数 sqlca.sqlcode 表示无害条件，比如最后查询返回零行。 sqlcode 和 sqlstate 是两个 不同的错误编码方案；详情如下。

如果最后一个SQL语句成功了，那么 sqlca.sqlerrd[1] 包含处理行的OID，如果适用，则 sqlca.sqlerrd[2] 包含处理或返回行的行数，如果适用该命令。

在错误或警告的情况下， sqlca.sqlerrm.sqlerrmc 将包含描述错误的字符串。字段 sqlca.sqlerrm.sqlerrml 包含存储在 sqlca.sqlerrm.sqlerrmc （ strlen() 的结果，C程序员不感兴趣）中的错误消息。 注意一些消息太长而不适合固定大小的 sqlerrmc 数组； 它们将被截断。

在一个警告的情况下， sqlca.sqlwarn[2] 设置为 W 。（在所有其他情况下，它被设置为不同于 W 的东西。）如果 sqlca.sqlwarn[1] 被设置为 W ，那么一个值被存储在宿主变量的时候，截断它。 如果任何其他元素设置为显示一个警告，则 sqlca.sqlwarn[0] 设置为 W 。

字段 sqlcaid , sqlcabc , sqlerrp ，以及 sqlerrd 和 sqlwarn 的剩余元素 目前没有任何有用信息。

在SQL标准中没有定义结构 sqlca ， 但是在其他几个SQL数据库系统中实现了。定义核心是相似的，但是如果你想要 编写可移植应用程序，那么你应该仔细调查不同的实现。 这是一个结合 WHENEVER 和 sqlca 的使用的例子， 当发生错误时，输出 sqlca 的内容。 在安装更多 "user-friendly" 错误处理程序之前， 这可能用于调试或者原型应用。

EXEC SQL WHENEVER SQLERROR CALL print_sqlca();
print_sqlca()
    fprintf(stderr, "==== sqlca ====\n");
    fprintf(stderr, "sqlcode: %ld\n", sqlca.sqlcode);
    fprintf(stderr, "sqlerrm.sqlerrml: %d\n", sqlca.sqlerrm.sqlerrml);
    fprintf(stderr, "sqlerrm.sqlerrmc: %s\n", sqlca.sqlerrm.sqlerrmc);
    fprintf(stderr, "sqlerrd: %ld %ld %ld %ld %ld %ld\n", sqlca.sqlerrd[0],sqlca.sqlerrd[1],sqlca.sqlerrd[2],
                                                          sqlca.sqlerrd[3],sqlca.sqlerrd[4],sqlca.sqlerrd[5]);
    fprintf(stderr, "sqlwarn: %d %d %d %d %d %d %d %d\n", sqlca.sqlwarn[0], sqlca.sqlwarn[1], sqlca.sqlwarn[2],
                                                          sqlca.sqlwarn[3], sqlca.sqlwarn[4], sqlca.sqlwarn[5],
                                                          sqlca.sqlwarn[6], sqlca.sqlwarn[7]);
    fprintf(stderr, "sqlstate: %5s\n", sqlca.sqlstate);
    fprintf(stderr, "===============\n");
结果可能如下所示（这里错误归因于表名字拼写错误）：
==== sqlca ====
sqlcode: -400
sqlerrm.sqlerrml: 49
sqlerrm.sqlerrmc: relation "pg_databasep" does not exist on line 38
sqlerrd: 0 0 0 0 0 0
sqlwarn: 0 0 0 0 0 0 0 0
sqlstate: 42P01
===============

   

33.8.3. SQLSTATE vs. SQLCODE

字段 sqlca.sqlstate 和 sqlca.sqlcode 是提供错误码的两个不同模式。 两者来自SQL标准，但是 SQLCODE 在标准SQL-92 版本中已经过时，并且在后期版本中已经废除。因此， 强烈建议新应用使用 SQLSTATE 。

SQLSTATE 是五字符数组。 五字符包含数字或者表示不同错误和警告条件代码的大写字母。 SQLSTATE 有一个分层模式： 前两个字符表示条件的一般类，最后三个字符表示一般条件的子类。 通过代码 00000 表示成功状态。 SQLSTATE 代码是SQL标准中定义最多部分。 PostgreSQL 服务器本地支持 SQLSTATE 错误代码；因此通过在所有应用程序中 使用该错误代码方案实现高度一致性。 更多信息参阅 附录 A 。

SQLCODE ，已废弃的错误编码方案，是一个简单的integer。 0值表示成功，正值表示附带额外信息的成功，负值表示错误。 SQL标准仅仅定义正值+100，这表示返回最后命令或者影响零行，并且 没有明确负值。因此，该方案实现差的移植性，而且没有分层编码安排。 从历史角度， PostgreSQL 嵌入的SQL预处理器 为它的使用分配了一些指定 SQLCODE 。 使用数值和符号名称将它列在下面。记住这些是不能移植到其他SQL实现的。 为了简化应用程序移植到 SQLSTATE 方案，相应的 SQLSTATE 也被列出来。然而， 在两个方案（实际上是多对多）之间没有一对一或者一对多映射， 因此在每种情况下你应该咨询列在 附录 A 中的全球 SQLSTATE 。

这些是已分配的 SQLCODE 值：