PostgreSQL7.0手册-用户手册-20. 应用 - ecpg

ecpg
名称
ecpg　—　嵌入的　SQL　C　预处理器　

语法
ecpg　[　-v　]　[　-t　]　[　-I　include-path　]　[　-o　outfile　]　　file1　[　file2　]　[　...　]
输入
ecpg　接受下面命令行参数：　
-v　
打印版本信息．　
-t　
关闭自动事务模式．　
-I　path　
声明一个附加的包含路径．缺省是　.，　/usr/local/include，Postgres　包含路径是在编译时定义的（缺省：/usr/local/pgsql/lib）和　/usr/include．　
-o　
声明　ecpg　应该把它的所有输出写到输出文件里．如果没有给出这个选项，则写到　name.c，假设输入文件是　name.pgc．如果输入文件有预期的　.pgc　后缀，那么输出文件将在输入文件后附加　.pgc　（？不是吧？）．　
file　
要处理的文件．　
输出
ecpg将创建一个文件或者写到标准输出（stdout）．　
return　value　
　　
　　
　　
　　

成功完成后，ecpg　给　shell　返回一个　0，如果出错返回　-1．

描述
ecpg　是一个嵌入的用于Postgres　和　C　语言的　SQL　预编译器．她使得用嵌入的　SQL　代码书写　C　程序成为可能．　
Linus　Tolke　（又叫　Linus　：）是　ecpg　最初的作者（直到版本　0.2）．Michael　Meskes　是目前的　ecpg　的维护人员和作者．Thomas　Good　是　ecpg　手册页最新版本的作者，这个手册页也是这份文档的基础．

用法
为编译预编译
一个嵌入的　SQL　源文件在编译前必须做预处理：　
ecpg　[　-d　]　[　-o　file　]　file.pgc
这里选项　-d　标志打开调试．.pgc　是标识　ecpg　源程序的任意标识．　
你可能需要把预处理输出重定向到一个文件里．

编译和链接
假设　Postgres　二进制在　/usr/local/pgsql，你将需要象下面这样编译和链接你的预处理过的源文件：　
gcc　-g　-I　/usr/local/pgsql/include　[　-o　file　]　file.c　-L　/usr/local/pgsql/lib　-lecpg　-lpq
语法
库
预处理器将包含两个目录到源文件里：　
#include　
#include　
变量定义
在　ecpg　源程序里的变量定义必须前导：　
EXEC　SQL　BEGIN　DECLARE　SECTION;
类似的，变量定义段必须以下面语句结束：　
EXEC　SQL　END　DECLARE　SECTION;
注意：在　2.1.0　以前，每个变量都必须在一个独立的行里．到了　2.1.0，可以在一行里定义多个变量：　
char　　foo(16),　bar(16);
错误控制
SQL　交互部分定义如下：　
EXEC　SQL　INCLUDE　sqlca;
注意：sqlca　是小写．尽管可以使用　SQL　传统，也就是说，利用大写字符来区分嵌入的　SQL　和　C　语句，而　sqlca　（它包含　sqlca.h　头文件）必须小写．这是因为　EXEC　SQL　前缀表明这个　INCLUDE　将被　ecpg　分析．ecpg　区分大小写地检查头文件（SQLCA.h　将不会被找到．）考虑大小写后，EXEC　SQL　INCLUDE　还可以包含其他头文件．
sqlprint　命令和　EXEC　SQL　WHENEVER　语句一起使用用以打开整个程序的错误控制：　
EXEC　SQL　WHENEVER　sqlerror　sqlprint;
和　
EXEC　SQL　WHENEVER　not　found　sqlprint;
注意：这些并不是　EXEC　SQL　WHENEVER　语句全部用法的例子．其用法的更多的例子可以在　SQL　手册里找到（例如,　`The　LAN　TIMES　Guide　to　SQL'　by　Groff　and　Weinberg）．
于数据库服务器联接
一种联接使用下面语句：　
EXEC　SQL　CONNECT　dbname;
这里数据库名称没有用引号引起．在　2.1.0　以前，数据库的名称要求被单引号引起．　
在联接语句里声明服务器名和端口名也同样可以．语法时：　

dbname[@server][:port]
或者　
:postgresql://server[:port][/dbname][?options]
查询
通常，其他应用，如　psql　，可以接受的话SQL　查询都可以嵌入到你的　C　代码里．下面是几个如何做的例子．　
创建表：　

EXEC　SQL　CREATE　TABLE　foo　(number　int4,　ascii　char(16));
EXEC　SQL　CREATE　UNIQUE　index　num1　on　foo(number);
EXEC　SQL　COMMIT;
插入：　
EXEC　SQL　INSERT　INTO　foo　(number,　ascii)　VALUES　(9999,　'doodad');
EXEC　SQL　COMMIT;
删除：　
EXEC　SQL　DELETE　FROM　foo　WHERE　number　=　9999;
EXEC　SQL　COMMIT;
单字段选择：　
EXEC　SQL　SELECT　foo　INTO　:FooBar　FROM　table1　WHERE　ascii　=　'doodad';
使用游标选择：　
EXEC　SQL　DECLARE　foo_bar　CURSOR　FOR
　　　　SELECT　number,　ascii　FROM　foo
　　　　ORDER　BY　ascii;
EXEC　SQL　FETCH　foo_bar　INTO　:FooBar,　DooDad;
...
EXEC　SQL　CLOSE　foo_bar;
EXEC　SQL　COMMIT;
更新：　
EXEC　SQL　UPDATE　foo
　　　　SET　ascii　=　'foobar'
　　　　WHERE　number　=　9999;
EXEC　SQL　COMMIT;
注意
没有　EXEC　SQL　PREPARE　语句．　
所有结构定义必须列在定义节里面．　

参阅源文件里的　TODO　文件获取更多缺失特性的描述．