pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。
本节描述如何在嵌入式 SQL 程序中处理异常情况和警告。为此有几种可以同时使用的机制。
捕获错误和警告的一种简单方法是指定一个动作,在特定条件发生时执行。一般形式如下:
EXEC SQL WHENEVERconditionaction;
condition可以是以下值之一:
SQLERROR只要在 SQL 语句执行期间发生一个错误就调用指定的动作。
SQLWARNING只要在 SQL 语句执行期间发生一个警告就调用指定的动作。
NOT FOUND只要一个 SQL 语句检索或者影响零行就调用指定的动作(这种情况不是一个错误,但是你可能需要特别地处理它)。
action可以是以下值之一:
CONTINUE这实际上表示该情况被忽略。这是默认值。
GOTO labelGO TO label跳到指定的标签(使用一个 C goto语句)。
SQLPRINT把一个消息打印到标准错误。对于简单程序或原型开发中这很有用。消息的细节无法配置。
STOP调用exit(1)终止程序。
DO BREAK执行 C 语句break。只应被用在循环或switch语句中。
CALL name (args)DO name (args)使用指定参数调用指定的 C 函数。
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 程序片段都不会产生预期效果:
/*
* 错误
*/
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;
}
为了支持更强大的错误处理,嵌入式 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、sqlabc、sqlerrp,以及sqlerrd和sqlwarn的其余元素,目前不包含有用信息。
SQL 标准中没有定义sqlca结构体,但是在一些其他的 SQL 数据库系统中都有实现。在核心上这些定义都相似,但是如果你想要编写可移植的应用,那么你应该仔细研究不同的实现。
SQLSTATE 与 SQLCODE字段sqlca.sqlstate和sqlca.sqlcode采用两种不同的错误编码方案。两者都源自 SQL 标准,但SQLCODE在 SQL-92 标准中已被标记为弃用,并在后续版本中被删除。因此,强烈建议新应用使用SQLSTATE。
SQLSTATE是一个包含五个字符的数组。这五个字符由数字或大写字母组成,表示各种错误和警告条件的代码。SQLSTATE采用分层编码方案:前两个字符表示条件所属的大类,后三个字符表示该大类中的子类。代码00000表示成功状态。大部分SQLSTATE代码由 SQL 标准定义。PostgreSQL服务器原生支持SQLSTATE错误码,因此在所有应用中统一使用这种错误编码方案,可以实现较高的一致性。更多信息见附录 A。
已弃用的错误编码方案SQLCODE使用一个简单的整数。0 表示成功,正值表示成功并有附加信息,负值表示错误。SQL 标准只定义了正值 +100,表示上一个命令返回或影响了零行,没有定义具体的负值。因此,这种方案的可移植性较差,也不采用分层编码。历史上,PostgreSQL的嵌入式 SQL 处理器为自身使用分配了一些特定的SQLCODE值,下文列出了它们的数值和符号名称。注意,这些值不能移植到其他 SQL 实现。为了便于将应用迁移到SQLSTATE方案,还列出了对应的SQLSTATE。不过,两种方案之间不存在一对一或一对多的映射关系(实际上是多对多),因此每次都应查阅附录 A中的完整SQLSTATE列表。
These are the assigned SQLCODE values:
ECPG_OUT_OF_MEMORY)表示你的虚拟内存已被耗尽。(SQLSTATE YE001)
ECPG_UNSUPPORTED)表示预处理器生成了该库无法识别的内容。可能是所用的预处理器与库的版本不兼容(SQLSTATE YE002)。
ECPG_TOO_MANY_ARGUMENTS)这表示命令指定了超过该命令预期数量的主变量(SQLSTATE 07001 或 07002)。
ECPG_TOO_FEW_ARGUMENTS)这表示命令指定的主变量数量低于该命令的预期(SQLSTATE 07001 或 07002)。
ECPG_TOO_MANY_MATCHES)这意味着一个查询已经返回了多个行,但是该语句只准备存储一个结果行(例如,因为指定的变量不是数组)(SQLSTATE 21000)。
ECPG_INT_FORMAT)主变量是类型int而数据库中的数据是一种不同的类型并且含有一个不能被解释为int的值。该库使用strtol()进行这种转换(SQLSTATE 42804)。
ECPG_UINT_FORMAT)主变量是类型unsigned int而数据库中的数据是一种不同的类型并且含有一个不能被解释为unsigned int的值。该库使用strtoul()进行这种转换(SQLSTATE 42804)。
ECPG_FLOAT_FORMAT)主变量是类型float而数据库中的数据是另一种类型并且含有一个不能被解释为float的值。该库使用strtod()进行这种转换(SQLSTATE 42804)。
ECPG_CONVERT_BOOL)这表示主变量是类型bool而数据库中的数据既不是't'也不是'f'(SQLSTATE 42804)。
ECPG_EMPTY)发送给PostgreSQL服务器的语句是空的(通常在一个嵌入式 SQL 程序中不会发生,因此它可能指向一个内部错误)(SQLSTATE YE002)。
ECPG_MISSING_INDICATOR)返回了一个空值,但未提供空值指示符变量(SQLSTATE 22002)。
ECPG_NO_ARRAY)在要求一个数组的地方使用了一个普通变量(SQLSTATE 42804)。
ECPG_DATA_NOT_ARRAY)在一个要求数组值的地方数据库返回了一个普通变量(SQLSTATE 42804)。
ECPG_NO_CONN)程序尝试访问一个不存在的连接(SQLSTATE 08003)。
ECPG_NOT_CONN)程序尝试访问一个存在的连接但是它没有打开(这是一个内部错误)(SQLSTATE YE002)。
ECPG_INVALID_STMT)尝试使用的语句尚未预备(SQLSTATE 26000)。
ECPG_UNKNOWN_DESCRIPTOR)未找到指定的描述符。尝试使用的语句尚未预备(SQLSTATE 33000)。
ECPG_INVALID_DESCRIPTOR_INDEX)指定的描述符超出范围(SQLSTATE 07009)。
ECPG_UNKNOWN_DESCRIPTOR_ITEM)请求了一个无效的描述符条目(这是一个内部错误)(SQLSTATE YE002)。
ECPG_VAR_NOT_NUMERIC)执行动态语句时,数据库返回了数值,而主变量不是数值类型(SQLSTATE 07006)。
ECPG_VAR_NOT_CHAR)执行动态语句时,数据库返回了非数值的值,而主变量是数值类型(SQLSTATE 07006)。
ECPG_PGSQL)PostgreSQL服务器导致了某个错误。该消息包含来自PostgreSQL服务器的错误消息。
ECPG_TRANS)PostgreSQL服务器通知我们不能启动、提交或回滚事务(SQLSTATE 08007)。
ECPG_CONNECT)到数据库的连接尝试没有成功(SQLSTATE 08001)。
ECPG_NOT_FOUND)这是一种无害情况,它表示上一个命令检索或者处理了零行,或者你到达了游标的末尾(SQLSTATE 02000)。
译文有误、术语不当或页面显示问题,请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。