↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。

受支持版本: 当前版本 (18) / 17 / 16 / 15 / 14
测试与开发版本: 19 / devel
不受支持的版本: 13 / 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1
历史版本PostgreSQL 7.1 已于 2006 年 4 月结束社区维护,本页译文保留供仍在使用旧版本的读者参考。新系统请看当前版本。

6.6. 给开发者 #

本节面向想要开发 ecpg 接口的人。它 描述各部分如何工作。这里的定位是让本节 包含给想深入了解的人的内容,而 如何使用一节应该足以回答所有 常规问题。 所以,在研究 ecpg 的内部 之前先读这一节。如果你 对它究竟如何工作不感兴趣,请跳过本节。

6.6.1. 待办列表

这个版本的预处理器有一些缺陷:

Library functions

to_date 等不存在。不过 Postgres 自身有一些不错的转换例程。所以你 大概不会想念它们。

结构与联合

结构和联合必须在 declare 区中定义。

缺失的语句

下列语句迄今尚未实现:

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'。

6.6.2. The Preprocessor

写入输出的前四行是 ecpg 固定添加的内容: 其中两行是注释,另外两行是与库接口所必需的 包含行。

随后预处理器只单遍工作,边读输入文件 边写输出。通常它只是 把所有内容原样回显到输出而不再细看。

遇到 EXEC SQL 语句时它会介入, 并根据语句的种类改写它们。 EXEC SQL 语句可以是下列这些:

Declare sections

声明节以

exec sql begin declare section;
         

开始,以

exec sql end declare section;
         

结束。节中只允许变量声明。在这个 节中声明的每个变量还会连同其相应的类型 一起按名字登记到一个变量列表中。

特别是结构或联合的定义也必须 列在 declare 区内。否则 ecpg 无法 处理这些类型,因为它根本不知道定义。

声明也会被回显到文件中,使该变量 同时成为一个普通的 C 变量。

特殊类型 VARCHAR 和 VARCHAR2 会为每个 变量转换成一个命名的结构。像这样的声明:

VARCHAR var[180];
         

is converted into

struct varchar_var { int len; char arr[180]; } var;
         
包含语句

include 语句的形式是:

exec sql include filename;
         

注意这不同于

#include <filename.h>
         

相反,指定的文件由 ecpg 自身解析。因此指定文件的内容会被包含进生成的 C 代码中。这样你就能够在 include 文件中指定 EXEC SQL 命令。

连接语句

connect 语句的形式是:

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。它们各自可以是常量文本、 字符变量或字符串。

断开语句

disconnect 语句的形式是:

exec sql disconnect [connection target];
         

它关闭到指定数据库的连接。

connection target 可以用下列 方式指定:

connection name
default
current
all
打开游标语句

open cursor 语句的形式是:

exec sql open cursor;
         

它被忽略,不复制到输出中。

提交语句

commit 语句的形式是

exec sql commit;
         

在输出中被翻译为

ECPGcommit(__LINE__);
         
回滚语句

rollback 语句的形式是

exec sql rollback;
         

and is translated on the output to

ECPGrollback(__LINE__);
         
其他语句

其他 SQL 语句是其他以 exec sql 开始、以 ; 结束的 语句。中间的一切 都被当作 SQL 语句并解析变量替换。

当符号以冒号 (:)开头时发生变量替换。此时会在先前 于声明节中声明的变量里查找具有该名字的变量,并且 根据该变量用于输入还是输出,把指向 变量的指针写入输出以允许函数 访问。

对于作为 SQL 请求一部分的每个变量, 函数会另外得到十个参数:

类型(以特殊符号表示)。
指向值的指针或指向指针的指针。
变量为 char 或 varchar 时的大小。
数组中的元素个数(用于数组抓取)。
到数组中下一个元素的偏移量(用于数组抓取)
指示符变量的类型(以特殊符号表示)。
指向指示符变量值的指针或指向指示符变量指针的指针。
0。
指示符数组中的元素个数(用于数组抓取)。
到指示符数组中下一个元素的偏移量(用于数组抓取)

6.6.3. 一个完整的例子

下面是一个完整的例子,描述预处理器对文件 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 <ecpgtype.h>;
#include <ecpglib.h>;

/* 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"

     

(本手册中的缩进是为了可读性而加的, 并不是预处理器能做的。)

6.6.4. 库

库中最重要的函数是 ECPGdo 函数。它接受数量可变的参数。但愿我们不会碰到 对 vararg 函数可接受的变量数量有 限制的机器。这很容易累积到 50 个左右的 参数。

参数有:

一个行号

这是原语句的行号,只用于错误消息。

一个字符串

这是要发出的 SQL 请求。该请求被输入 变量修改,即那些编译时未知但要输入 请求的变量。在变量应出现的 位置,字符串中包含 ";"。

输入变量

如关于预处理器的 一节所述,每个输入变量 得到十个参数。

ECPGt_EOIT

一个枚举,表示不再有输入变量。

输出变量

如关于预处理器的 一节所述,每个输入变量 得到十个参数。 These variables are filled by the function.

ECPGt_EORT

一个枚举,表示不再有变量。

所有 SQL 语句都在一个事务中执行, 除非你发出提交事务。为了让这种自动事务运转起来, 第一条语句或提交/回滚之后的第一条 语句总是会开始一个事务。要在默认情况下禁用这个特性, 请在命令行使用 -t 选项。

待完成:描述其他条目的条目。

提交更正

译文有误、术语不当或页面显示问题,请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。