29.9. 错误处理

本节描速你如何在嵌入的 SQL 程序里处理例外以及警告。有好几种非排它的设施可用。

29.9.1. 设置回调

捕获错误和警告的一个简单的办法是设置一个特定的动作, 当特定情况发生的时候执行这个动作。通常:

EXEC SQL WHENEVER condition action;

condition 可以是下列之一:

SQLERROR

声明的动作将在执行一个 SQL 语句发生错误的时候执行。

SQLWARNING

声明的动作将在执行一个 SQL 语句发生警告的时候执行。

NOT FOUND

声明的动作将在一条 SQL 语句检索了零行或者影响零行的情况下被 执行。(这个条件不是一个错误,但是你可能喜欢单独处理这个情况。)

action 可以是下列之一:

CONTINUE

这个动作的意思是这个条件可以忽略。这是缺省。

GOTO label
GO TO label

跳转到指定的标签(使用一个 C 的goto 语句)。

SQLPRINT

向标准错误打印一条信息。这对简单程序或者原型定义程序很有用。 消息的细节不能配置。

STOP

调用 exit(1),它将终止程序运行。

BREAK

执行 C 语句 break。这个应该只在循环或者 switch 语句中使用。

CALL name (args)
DO name (args)

用指定的参数调用指定的 C 函数。

SQL 标准只提供 CONTINUEGOTO (也是 GO TO)动作。

下面是一个例子,你可能可以用在简单的程序里。它在发生警告的时候打印一个简单的信息,在发生错误的时候退出程序。

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

语句 EXEC SQL WHENEVER 是 SQL 预处理器的一个指示器, 而不是一个 C 语句。它设置的错误或者警告动作适用于下面出现的设置了句柄的所有 SQL 语句, 除非在第一个 EXEC SQL WHENEVER 和导致条件触发的 SQL 语句之间为同一个条件设置了另外一个动作, 而不管 C 程序内部的流程控制是怎样的。所以,下面的两个 C 程序节选都不会有它们期望的效果。

/*
 * 错误
 */
int main(int argc, char *argv[])
{
    ...
    if (verbose) {
        EXEC SQL WHENEVER SQLWARNING SQLPRINT;
    }
    ...
    EXEC SQL SELECT ...;
    ...
}

/*
 * 错误
 */
int main(int argc, char *argv[])
{
    ...
    set_error_handler();
    ...
    EXEC SQL SELECT ...;
    ...
}

static void set_error_handler(void)
{
    EXEC SQL WHENEVER SQLERROR STOP;
}

29.9.2. sqlca

如果需要更强大的错误处理机制,那么嵌入的 SQL 接口提供了一个叫 sqlca 的全局变量,它是一个有着下面定义的结构:

struct
{
    char sqlcaid[8];
    long sqlabc;
    long sqlcode;
    struct
    {
        int sqlerrml;
        char sqlerrmc[70];
    } 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 标识一种无害的条件,比如最后的查询返回零行。sqlcodesqlstate 是两个不同的错误模式;下面详细介绍。

如果最后一条 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

字段 sqlcaidsqlcabcsqlerrp 和剩下的 sqlerrd 以及 sqlwarn 元素目前没有包含有用的信息。

结构 sqlca 没有在 SQL 标准里定义,但是在好几个其它 SQL 数据库系统里定义了。 定义的核心都类似,但是如果你想写可以移植的应用,那么你应该仔细研究不同的实现。

29.9.3. SQLSTATESQLCODE 之比较

字段 sqlca.sqlstatesqlca.sqlcode 是提供错误代码的两种不同的模式。两种都在 SQL 里声明了,但是 SQLCODE 在 1992 年的标准版本里标注为废弃的,并且在 1999 年版本里被删除了。因此,对于新应用,我们强烈建议使用 SQLSTATE

SQLSTATE 是一个五字符的数组。五个字符包含数值或者大写字母, 代表各种错误或者警告条件的代码。SQLSTATE 有个层次化的模式:头两个字符标识条件的通常表示错误条件的类别, 后三个字符表示在该通用类中的子类。成功的状态是由 00000 标识的。SQLSTATE 代码在大多数地方都是定义在 SQL 标准里的。PostgreSQL 服务器本机支持 SQLSTATE 错误代码;因此在应用里使用这个错误代码模式可以实现非常高的一致性。更多信息请参阅 Appendix A

SQLCODE 是废弃的错误代码模式,是一个简单的整数。 0 标识成功,正数标识带着额外信息的成功,负数表示一个错误。SQL 标准只定义了正数值 +100, 这个表示最后的命令返回零行或者影响了零行,并且没有特定的负数值。 因此,这个模式只能实现很有限的一致性并且并没有一个层次化的代码机制。 历史上,PostgreSQL 的嵌入的 SQL 处理器为自己使用赋予了一些 SQLCODE 的数值,这些都在下面列出,包括他们的数值和符号名。记住这些是不能移植到其它 SQL 实现中去的。 为了简化应用向 SQLSTATE 模式的移植,我们还列出了 SQLSTATE。 不过,这两个模式之间没有一对一或者一对多的映射(包括多对多),所以在任何情况下你都应该参考在 Appendix A 里列出的全局SQLSTATE

这些是已经赋值的 SQLCODE 数值:

-12 (ECPG_OUT_OF_MEMORY)

表明你的虚拟内存已经耗尽(SQLSTATE YE001)

-200 (ECPG_UNSUPPORTED)

表明预处理器生成了一些库不知道的东西。可能你运行的预处理器版本和库版本不同。(SQLSTATE YE002)

-201 (ECPG_TOO_MANY_ARGUMENTS)

这意味着你的命令声明了比命令预期要多的宿主变量(SQLSTATE 07001 或者 07002)

-202 (ECPG_TOO_FEW_ARGUMENTS)

这意味着你的命令声明了比命令预期要少的宿主变量(SQLSTATE 07001 或者 07002)

-203 (ECPG_TOO_MANY_MATCHES)

这意味着查询返回了多行,但是语句只准备存储一行结果(比如,因为声明的变量不是数组)。(SQLSTATE 21000)

-204 (ECPG_INT_FORMAT)

宿主变量是 int 类型,而数据库里的数据是其它类型, 并且包含无法解释成 int 类型的数值。库使用 strtol() 做这种转换。(SQLSTATE 42804)

-205 (ECPG_UINT_FORMAT)

宿主变量是 unsigned int 而数据库里的数据是其它类型, 并且包含无法解释成 unsigned int 类型的数值。 库使用 strtoul() 做这种转换。(SQLSTATE 42804)

-206 (ECPG_FLOAT_FORMAT)

宿主变量是 float 而数据库里的数据是其它类型, 并且包含无法解释成 float 类型的数值。 库使用 strtod() 做这种转换。(SQLSTATE 42804)

-207 (ECPG_CONVERT_BOOL)

这意味着宿主变量是类型为 bool 的而数据库中的数据既不是't' 也不是 'f'。(SQLSTATE 42804)

-208 (ECPG_EMPTY)

发送给 PostgreSQL 服务器的语句是空的。 (这个通常不能在嵌入 SQL 程序里出现,因此它可能是一个内部错误。) (SQLSTATE YE002)

-209 (ECPG_MISSING_INDICATOR)

返回了一个空值,但是没有提供空值指示器变量。(SQLSTATE 22002)

-210 (ECPG_NO_ARRAY)

在一个需要数组的地方使用了一个普通变量。(SQLSTATE 42804)

-211 (ECPG_DATA_NOT_ARRAY)

在一个需要数组的地方数据库返回了一个普通变量。 (SQLSTATE 42804)

-220 (ECPG_NO_CONN)

程序视图访问一个不存在的连接。(SQLSTATE 08003)

-221 (ECPG_NOT_CONN)

程序视图访问一个存在但未打开的连接(这是一个内部错误。)(SQLSTATE YE002)

-230 (ECPG_INVALID_STMT)

你正在尝试使用的语句还没准备好。(SQLSTATE 26000)

-240 (ECPG_UNKNOWN_DESCRIPTOR)

声明的描述符没有找到。你在试图使用的语句没有准备好(SQLSTATE 33000)

-241 (ECPG_INVALID_DESCRIPTOR_INDEX)

声明的描述符索引超出范围。(SQLSTATE 07009)

-242 (ECPG_UNKNOWN_DESCRIPTOR_ITEM)

请求了一个非法的描述符项。(这是一个内部错误。)(SQLSTATE YE002)

-243 (ECPG_VAR_NOT_NUMERIC)

在一个动态语句的执行的过程中,数据库返回了一个数字只,而宿主变量不是数值型(SQLSTATE 07006)。

-244 (ECPG_VAR_NOT_CHAR)

在执行一个动态语句的过程中,数据库返回了一个非数字数值,但是宿主变量是数值型。(SQLSTATE 07006)

-400 (ECPG_PGSQL)

一些 PostgreSQL 服务器导致的错误。 消息包含来自 PostgreSQL 服务器的错误消息。

-401 (ECPG_TRANS)

PostgreSQL 告诉我们不能启动,提交, 或者回滚这个事务。(SQLSTATE 08007)

-402 (ECPG_CONNECT)

与数据库的连接企图没有成功(SQLSTATE 08001)。

100 (ECPG_NOT_FOUND)

这是个无害的条件,表示最后一条命令检索或者处理了零行,或者你在游标的结尾。(SQLSTATE 02000)