52.3. 如何使用 ecpg
本节介绍如何使用 ecpg 工具。
52.3.1. 预处理器
预处理器叫做 ecpg。安装后它位于
Postgres 的 bin/ 目录中。
52.3.2. 库
ecpg 库叫做
libecpg.a 或
libecpg.so。此外，该库用 libpq 库与
Postgres 服务器通信，因此你必须用
-lecpg -lpq 链接你的程序。
库中有一些"隐藏的"方法，但它们有时可能非常有用。
ECPGdebug(int在第一个参数非零时打开调试日志。调试日志输出到on, FILE *stream)stream。大多数 SQL 语句会记录其参数和结果。其中最重要的一个是
ECPGdo，除EXEC SQL COMMIT、EXEC SQL ROLLBACK、EXEC SQL CONNECT之外的所有 SQL 语句都会调用它，它会同时记录展开后的字符串（即插入了所有输入变量的字符串）以及 Postgres 服务器返回的结果。在排查 SQL 语句中的错误时这会非常有用。ECPGstatus()这个方法在已连接到数据库时返回 TRUE，否则返回 FALSE。
52.3.3. 错误处理
为了能够检测来自 Postgres 服务器的错误，你可以在文件的 include 区中包含像下面这样的一行
exec sql include sqlca;
这会定义一个结构以及一个名为 sqlca 的变量，如下：
struct sqlca {
int sqlcode;
struct {
int sqlerrml;
char sqlerrmc[1000];
} sqlerrm;
} sqlca;
如果上一条 SQL 语句发生了错误，则 sqlca.sqlcode
将非零。如果 sqlca.sqlcode 小于 0，这是某种严重的错误，例如数据库定义与所给的查询不匹配。如果大于 0，则是普通错误，例如表中没有所请求的行。
sqlca.sqlerrm.sqlerrmc 将包含一个描述错误的字符串。该字符串以 “line 23.” 结尾，其中的行号是源文件中的行号（实际上是预处理器生成的文件中的行号，但我希望能把它修正为输入文件中的行号。）
可能发生的错误列表：
- -1, Unsupported type %s on line %d.
通常不发生。这表示预处理器生成了库不认识的内容。也许你运行的预处理器和库的版本不兼容。
- -1, Too many arguments line %d.
预处理器搞砸了，生成了一些不正确的代码。
- -1, Too few arguments line %d.
预处理器搞砸了，生成了一些不正确的代码。
- -1, Error starting transaction line %d.
Postgres 向我们表示无法打开连接。
- -1, Postgres error: %s line %d.
某种 Postgres 错误。消息中包含来自 Postgres 后端的错误消息。
- 1, Data not found line %d.
这是一个"正常"错误，告诉你所查询的内容找不到，或者我们已经遍历完了游标。
- -1, To many matches line %d.
这表示查询返回了多行。你执行的
SELECT很可能不唯一。- -1, Not correctly formatted int type: %s line %d.
这表示宿主变量的类型是
int，而 Postgres 数据库中的字段是另一种类型，包含不能被解释为int的值。库用strtol做这个转换。- -1, Not correctly formatted unsigned type: %s line %d.
这表示宿主变量的类型是
unsigned int，而 Postgres 数据库中的字段是另一种类型，包含不能被解释为unsigned int的值。库用strtoul做这个转换。- -1, Not correctly formatted floating point type: %s line %d.
这表示宿主变量的类型是
float，而 Postgres 数据库中的字段是另一种类型，包含不能被解释为float的值。库用strtod做这个转换。- -1, Too few arguments line %d.
这表示 Postgres 返回的记录比我们拥有的匹配变量多。也许你在
INTO :var1,:var2列表中漏掉了几个宿主变量。- -1, Too many arguments line %d.
这表示 Postgres 返回的记录比我们拥有的宿主变量少。也许你在
INTO :var1,:var2列表中放了太多宿主变量。- -1, Empty query line %d.
Postgres 返回了 PGRES_EMPTY_QUERY。
- -1, Error: %s line %d.
这表示 Postgres 返回了 PGRES_NONFATAL_ERROR、PGRES_FATAL_ERROR 或 PGRES_BAD_RESPONSE 错误之一。是哪一种以及原因会在消息中说明。
- -1, Postgres error line %d.
Postgres 返回了库不知道如何处理的内容。这很可能是因为 Postgres 的版本与 ecpg 库的版本不匹配。
- -1, Error committing line %d.
COMMIT期间出错。EXEC SQL COMMIT被翻译为 Postgres 中的一个end操作，而那正是无法执行的操作。- -1, Error rolling back line %d.
ROLLBACK期间出错。EXEC SQL ROLLBACK被翻译为 Postgres 中的一个abort操作，而那正是无法执行的操作。- -1, ECPGconnect: could not open database %s.
连接数据库失败。