PostgreSQL7.0手册-接口-52. ecpg - 在 C 里嵌入 SQL

第五十二章.　ecpg　-　在　C　里嵌入　SQL
内容　
为什么要嵌入　SQL？　
概念　
如何使用　ecpg　
局限　
从其他　RDBMS　移植　
安装　
寄语开发者　
这里描写　Postgres　里在　C　软件包里嵌入　SQL．这部分是由　Linus　Tolke　（译注：是不是叫　Linus　的都是计算机天才？）和　Michael　Meskes　写的．　
注意：你可以象　PostgreSQL　其他部分那样拷贝和使用这些内容．
为什么要嵌入　SQL？
嵌入使用　SQL　比其他操作　SQL　查询的方法有一些小小的优势．它关心所有你的C　程序里面变量信息的往返．许多　RDBMS　软件包支持这种嵌入的语言．　
有一个　ANSI　的标准描述嵌入的语言应该怎样工作．ecpg　被设计成尽可能地符合这个标准．因此这就有可能把为其他　RDBMS　软件包书写的嵌入式　SQL　程序移植到　Postgres　上来并因此而推动自由软件的精神的发展．

--------------------------------------------------------------------------------

概念
你在你的　C　程序里面用一些特殊的　SQL　东西来编写程序．对于定义可以在　SQL　语句里面使用的变量，你需要把它们放到一个特殊的定义段里面．你用一些特殊的语法来表达　SQL　查询．　
在编译之前，你用嵌入的　SQLC　预编译器对你的文件进行预处理，由这个预编译器把你使用的　SQL　语句转换成把变量作为参数的函数调用．不管是作为输入到　SQL　语句里面的变量还是将包含返回结果的变量都被传到函数调用里．　

然后你编译你的程序，在链接时，你的程序会与一个包含所用函数的特殊的库链接．这些函数（实际上大多是一个单一的函数）从参数里取得信息，用通常的方法（libpq）执行　SQL　查询并且把结果放回到声明为输出的参数里．　

这样你运行你的程序时当控制到达　SQL　语句时，SQL　语句对数据库进行操作因而你可以对结果进行继续处理．


--------------------------------------------------------------------------------　　
--------------------------------------------------------------------------------

如何使用　ecpg
本节讨论如何使用　ecpg　工具．　
预编译器
预编译器叫　ecpg．在安装过后它存放在　Postgres　bin/　目录下面．
库
ecpg　库叫做　libecpg.a　或　libecpg.so．另外，该库用了　libpq　库与　Postgres　服务器通讯，所以你要将你的程序与这两个库链接：　-lecpg　-lpq．　
库里面有一些方法是"隐藏"的，但是有时候这些方法可能提供非常有用的信息．　

ECPGdebug(int　on,　FILE　*stream)　如果第一个参数不为零则打开调试信息．调试信息记录在　stream.　大多数　SQL　语句把它的参数和结果记录日志．　
最重要的一个　（ECPGdo）（函数）记录它的所有展开的字符串，也就是说，带有插入的所有变量的字符串和从Postgres　服务器来的结果．这个对搜索你的　SQL　语句的错误是非常有用的．　

ECPGstatus()　这个方法/函数在我们与一个数据库联接后返回　TRUE　并且如果没有联接返回　FALSE　．

错误控制
要想检测从　Postgres　服务器来得错误，你要包含如下一行　
　　　　　　exec　sql　include　sqlca;
到你的文件的包含段里．这样做将会定义一个结构和一个象下面一样名为　sqlca　的变量：　
struct　sqlca
{
　char　sqlcaid[8];
　long　sqlabc;
　long　sqlcode;
　struct
　{
　　int　sqlerrml;
　　char　sqlerrmc[70];
　}　sqlerrm;
　char　sqlerrp[8];
　long　sqlerrd[6];
　/*　0:　empty　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　*/
　/*　1:　OID　of　processed　tuple　if　applicable　　　　　　　　　　*/
　/*　2:　number　of　rows　processed　in　an　INSERT,　UPDATE　*/
　/*　　　　or　DELETE　statement　　　　　　　　　　　　　　　　　　　　　　　　　　　*/
　/*　3:　empty　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　*/
　/*　4:　empty　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　*/
　/*　5:　empty　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　*/
　char　sqlwarn[8];
　/*　0:　set　to　'W'　if　at　least　one　other　is　'W'　　　　　　　*/
　/*　1:　if　'W'　at　least　one　character　string　　　　　　　　　　*/
　/*　　　　value　was　truncated　when　it　was　　　　　　　　　　　　　　　*/
　/*　　　　stored　into　a　host　variable.　　　　　　　　　　　　　　　　　　*/
　/*　2:　empty　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　*/
　/*　3:　empty　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　*/
　/*　4:　empty　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　*/
　/*　5:　empty　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　*/
　/*　6:　empty　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　*/
　/*　7:　empty　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　*/
　char　sqlext[8];
}　sqlca;
如果最后一个SQL　语句发生了错误，那么　sqlca.sqlcode　将是非零值．如果　sqlca.sqlcode　小于　0　那么就是发生了某种严重的错误，象数据库定义与查询定义不一致等．如果大于　0　则是通常的错误，象表不包括所要求的行等．　
sqlca.sqlerrm.sqlerrmc　将包含一个字符串描述该错误．该字符串以源文件的行号结尾。　

可能发生的错误列表：　
　　
-12,　Out　of　memory　in　line　%d.　
通常不出现这个错误。这是你的虚拟内存耗尽的标志。　
-200,　Unsupported　type　%s　on　line　%d.　
通常不出现这个错误．这表明预编译器生成了一些库（函数）不认得的东西．可能你运行的预编译器和当前库不兼容．　
-201,　Too　many　arguments　line　%d.　
这意味着　Postgres　返回了比我们的匹配变量更多的参数．可能你漏了几个INTO　:var1,:var2-列表里的宿主变量．　
-202,　Too　few　arguments　line　%d.　
这意味着　Postgres　返回了比我们的对应宿主变量要少的参数．可能你多输入了几个INTO　:var1,:var2-列表里的宿主变量．　
-203,　Too　many　matches　line　%d.　
这意味着查询返回了多个行，但你声明的变量不是数组．你执行的　SELECT　可能不是唯一的．　
-204,　Not　correctly　formatted　int　type:　%s　line　%d.　
这意味着宿主变量是一个　int　类型并且　Postgres　数据库里的字段是另一种类型，包含着一个不能转换成一个　int　类型的数值．库（函数）使用　strtol　做此类转换．　
-205,　Not　correctly　formatted　unsigned　type:　%s　line　%d.　
这意味着宿主变量是一个　unsigned　int（无符号整数）类型而Postgres　数据库里的字段是另外一种类型并且包含一个不能转换成unsigned　int　的数值．库（函数）使用　strtoul　做这类转换．　
-206,　Not　correctly　formatted　floating　point　type:　%s　line　%d.　
这意味着宿主变量是一个　float　（浮点）类型而　Postgres　数据库里的字段是另外一种类型并且包含一个不能转换成float　的数值．库（函数）使用　strtod　做这类转换．　
-207,　Unable　to　convert　%s　to　bool　on　line　%d.　
这意味着宿主变量是一个　bool　（布尔）类型，而　Postgres　数据库里的字段值既不是　't'　也不是　'f'。　
-208,　Empty　query　line　%d.　
Postgres　返回　PGRES_EMPTY_QUERY，可能的原因是该查询实际上是空的。　
-220,　No　such　connection　%s　in　line　%d.　
程序试图访问一个不存在的联接。　
-221,　Not　connected　in　line　%d.　
程序试图访问一个存在的，但是没有打开的联接。　
-230,　Invalid　statement　name　%s　in　line　%d.　
你试图使用的语句还没准备好。　
-400,　Postgres　error:　%s　line　%d.　
某种　Postgres　错误。该消息包含来自　Postgres　后端的信息。　
-401,　Error　in　transaction　processing　line　%d.　
Postgres　给我们的信号，表明我们无法开始，提交或者回卷该事务。　
-402,　connect:　could　not　open　database　%s.　
与数据库的联接无法工作。　
100,　Data　not　found　line　%d.　
这是一个"正常的"错误，告诉你你正在查询的东西找不到或者我们已经越过了游标的范围。　

--------------------------------------------------------------------------------
--------------------------------------------------------------------------------

局限
一些永远不会包括进来的东西以及用这个概念为什么或什么东西是没法做到的．　
　　
Oracle　的单任务能力　（single　tasking　possibility）　
　　
　　

Oracle　在　AIX　3　上的版本　7.0　利用了　OS　支持的在共享内存段上的锁技术并且允许应用设计者用一种所谓的单任务方式链接一个应用．这时的体系结构就不是每个应用进程对应一个客户端进程，而是数据库部分和应用部分都在同一个进程上跑．在　oracle　的后期版本上这个特性不再被支持．　

这需要对Postgres　的访问模式进行完全重新设计而且这些努力与获得的性能提高不相称．


--------------------------------------------------------------------------------
--------------------------------------------------------------------------------

从其他　RDBMS　软件包移植
ecpg　的设计遵循　SQL　标准。所以从一个标准的　RDBMS　移植（应用）应该不是问题。糟糕的是现实世界里并没有所谓的标准的　RDBMS。所以　ecpg　同样试图去理解那些与标准不冲突的语法扩展。　
下面的列表显示了所有以知的不兼容的地方。如果你发现一个没有列出来的不兼容点，请告之　Michael　Meskes。不过要注意的是，我们只是列出那些其他　RDBMS　的预编译器和　ecpg　不兼容的东西，而没有列出ecpg　里有而其他　RDBMS　没有的特性。　

FETCH　命令的语法　
标准的　FETCH　命令的语法是：　
　　
　　

FETCH　[direction]　[amount]　INFROM　cursor　name.　

不过，ORACLE　并不使用关键字　IN　和/或　FROM。我们没有办法增加这个特性，因为那样会导致分析冲突。


--------------------------------------------------------------------------------
--------------------------------------------------------------------------------

安装
自版本　0.5　起　ecpg　就和　Postgres　一起发布．所以缺省安装时你就可以得到编译好并且安装好了的预编译器,　库和头文件．

--------------------------------------------------------------------------------　　
--------------------------------------------------------------------------------

寄语开发者
本节是写给那些希望开发　ecpg　接口的人的．这里描述了这些接口是怎样工作的．本节的目的是给那些想认识一些内部机制的人提供一些信息，而"如何使用"那一章应该描述了所有通常的问题．所以，在深入　ecpg　内部之前请先读一下本节．如果你对　ecpg　如何工作不感兴趣，请略过本节．　
ToDo　列表
这个版本的预编译器有一些缺陷：　
　　
库函数　
to_date　等不存在。不过　Postgres　本身有一些很好的转换过程。所以你可能不会想要这些（函数）。　
　　
结构和联合　
结构和联合必须在定义段里定义。　
缺失的语句　
下面的语句到目前为止还没有实现：　
exec　sql　allocate　
exec　sql　deallocate　
SQLSTATE　
　
信息　'no　data　found'　
一个　exec　sql　insert　select　from　语句的　"no　data"　错误信息应该是　100。　
sqlwarn[6]　
如果一个　SET　DESCRIPTOR　语句里声明的　PRECISION　或　SCALE　值被忽略，sqlwarn[6]　应该是　'W'．　
　
预编译器
首先写到输出的四行是　ecpg　的一贯做法．这些是两行注释和两行用于库接口必须的包含行．　
然后预编译器对文件处理一遍，一边读输入文件，一边输出到输出文件．通常它只是把不加分析的把所有东西输出到输出文件里去．　

当处理到　EXEC　SQL　语句时，预编译器对之进行处理并根据语句做相应的改变．EXEC　SQL　语句可以是下列之一：　

定义段　
　　
　　

定义段以　

exec　sql　begin　declare　section;
开头，以　
exec　sql　end　declare　section;
结束．在定义段里只允许变量定义．这个段里定义的每个变量同时也放到一个以变量名和对应类型为索引的变量列表里头．　
特别是结构（struct）或者联合（union）的定义同样必须在定义段里面列出。否则ecpg　就不能处理这些类型，因为它不知道定义（是什么）。　

定义同时也输出到文件里把这些变量作为通常的　C-变量．　

特殊的类型　VARCHAR　和　VARCHAR2　的每个变量都被转换成一个命名结构．一个下面这样的定义：　
　　

VARCHAR　var[180];
被转换成　
struct　varchar_var　{　int　len;　char　arr[180];　}　var;
包含语句　
　　
　　

一个包含语句看起来象：　

exec　sql　include　filename;
注意这个与下面这行　
#include　
是不一样的。被包含的文件由　ecpg　本身分析。因此声明的头文件被包括在生成的　C　代码里。这样你也能够在一个头文件里声明　EXEC　SQL　语句。　
联接语句　
　　
　　

一个联接语句看起来象：　

exec　sql　connect　to　connection　target;
它创建与指定数据库的联接。　
connection　target　（联接目标）可以用下面的方法声明：　
　　

dbname[@server][:port][as　connection　name][user　user　name]　
tcp:postgresql://server[:port][/dbname][as　connection　name][user　user　name]　
unix:postgresql://server[:port][/dbname][as　connection　name][user　user　name]　
character　variable[as　connection　name][user　user　name]　
character　string[as　connection　name][user]　
default　
user　
　
也有不同的方法声明用户名：　
userid　
userid/password　
userid　identified　by　password　
userid　using　password　
　
最后的　userid　和　password。每个都可以是一个文本常量，一个字符变量或者一个字符串。　
　　
断开语句　
　　
　　
　　
　　
　　
　　
　　
　　

一个断开语句看起来象：　

exec　sql　disconnect　[connection　target];
它关闭与指定数据库的联接。　
connection　target　可以用下面方法声明：　

connection　name　
default　
current　
all　
　
打开游标语句　
　　
　　
　　
　　
　　
　　
　　
　　

一个打开游标语句看起来象：　

exec　sql　open　cursor;
它被忽略因而不拷贝到输出文件．　
提交语句　
　　
　　
　　
　　
　　
　　

一个提交语句看起来象　

exec　sql　commit;
它被转换成输出　
ECPGcommit(__LINE__);
回卷语句　
　　
　　
　　
　　
　　
　　

一个回卷语句看起来象　

exec　sql　rollback;
它被转换成如下输出　
ECPGrollback(__LINE__);
其他语句　
　　
其他　SQL　语句是其他以　exec　sql　开头并且以　;　结尾的语句．所有两者之间的东西都被认为是一个　SQL　语句并做变量替换分析．　
　　
　　
　　
　　
　　
　　

当一个符号以冒号（:）开头时，就会发生变量替换．然后就会到前面定义段里（生成）的变量列表里找出该名称的变量，然后根据该变量是用于输入还是输出，把指向该变量的指针写到输出里供函数访问使用．　

对　SQL　请求里的每个变量，函数都得到另外十个参数：　
　　　
　作为特殊符号的类型。　
指向数值或指针的指针。　
如果变量是　varchar　或者　char，变量的尺寸。　
数组里的元素个数（对数组抓取）。　
数组里下一个元素的偏移量（对数组抓取）　
做为特殊符号的标识器变量的类型。　
一个指向标识器变量值或者标识器变量指针的指针。　
0.　
标识器数组里的元素个数（对数组抓取）。　
标识器数组里下一个元素的偏移量（对数组抓取）。　


一个完整的例子
下面是一个完整的描述预编译器对文件　foo.pgc　的输出的例子：　
exec　sql　begin　declare　section;
int　index;
int　result;
exec　sql　end　declare　section;
...
exec　sql　select　res　into　:result　from　mytable　where　index　=　:index;
被解释成：　
/*　Processed　by　ecpg　(2.6.0)　*/
/*　These　two　include　files　are　added　by　the　preprocessor　*/
#include　;
#include　;

/*　exec　sql　begin　declare　section　*/

#line　1　"foo.pgc"

　int　index;
　int　result;
/*　exec　sql　end　declare　section　*/
...
ECPGdo(__LINE__,　NULL,　"select　　res　　from　mytable　where　index　=　?　　　　　",
　　　　　　　　ECPGt_int,&(index),1L,1L,sizeof(int),
　　　　　　　　ECPGt_NO_INDICATOR,　NULL　,　0L,　0L,　0L,　ECPGt_EOIT,
　　　　　　　　ECPGt_int,&(result),1L,1L,sizeof(int),
　　　　　　　　ECPGt_NO_INDICATOR,　NULL　,　0L,　0L,　0L,　ECPGt_EORT);
#line　147　"foo.pgc"


（本手册里的缩进是为可读性追加的，可不是预编译器能干的事．）　
库
在库里面最重要的函数是　ECPGdo　函数．它有可变的参数．希望我们不会碰到那些对变参数个数的函数的参数个数有限制的机器．这些参数个数很容易多达　50　个．　
这些参数是：　
　　
一个行号　
这是一个只用于错误信息里的表明原始出错行的行号．　
一个字符串　
这是声明的　SQL　请求。这个请求将用输入变量修改，也就是说用那些编译时未知但要输入到请求里的变量修改．这里变量应该包含　“;”　放到字符串里．　
输入变量　
象预编译器节里描述的那样，每个输入变量换成十个参数．　
ECPGt_EOIT　
一个　enum　（枚举）表明输入变量（列表）的结尾．　
输出变量　
象预编译器节里描述的那样，每个输入变量换成十个参数．这些变量将由函数填充．　
ECPGt_EORT　
一个　enum　（枚举）表明变量（列表）的结尾．　
所有　SQL　语句都在一次事务中执行，除非你进行了一次事务提交（commit）．要获取这样的自动事务，第一个语句和/或事务提交或回卷后的第一个（语句）总是打开一个事务．要关闭这个缺省的特性，可以在命令行上使用　'-t'　选项。　
待续：描述其他入口的位置．


-------------------------------------------------------------------------------