PostgreSQL7.0手册-程序员手册 -48. 服务器编程接口

第四十八章．服务器编程接口
内容　
接口函数　
接口支持函数　
存储器管理　
数据改变的可视性　
例子　
服务器编程接口（Server　Programming　Interface）　（SPI）给我们在用户定义的　C　函数里面运行　SQL查询的能力．可用的过程语言（PL）给我们一个实现这些功能的可选的手段．　
实际上，SPI　只是一套用于访问分析器，规划器，优化器和执行器（Parser，Planner，Optimizer　and　Executor）的本机接口函数．SPI　同样做一些存储器管理工作．　

为了避免混淆，我们将使用　函数(function)　来代表　SPI　接口函数，用　过程(procedure)　代表用户用　SPI定义　C　函数．　

SPI　过程总是被一些（上层）执行器和　SPI　管理器用执行器调用来运行你的查询．其他过程可以通过执行器从你的过程里运行查询来调用．　

注意，如果在你的过程里执行查询时，事务退出了，那么控制不会返回到你的过程中．相反，所有工作都将回卷并且服务器将等待客户端的另一个命令．这一点将在以后的版本中修正．　

其他限制是不能执行　BEGIN，END　和　ABORT　（交易控制语句）和游标操作．这些同样在将来的版本中要被修改．　

如果执行成功了，SPI　函数返回一个非负结果（或者通过返回一个整数值或放在　SPI_result　全局变量，象下面描述的那样）．出错时，返回一个负数或　NULL　结果．　

接口函数

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

SPI_connect
名称
SPI_connect　—　把你的过程与　SPI　管理器连接起来．　

语法
int　SPI_connect(void)
输入
无　

输出
int　
　　
返回状态　
SPI_OK_CONNECT　
如果联接成功　
SPI_ERROR_CONNECT　
如果联接失败　

描述SPI_connect　打开一个与　Postgres　后端的联接．如果你需要执行查询你就要调用这个函数．有些使用　SPI　函数的应用可以从非联接的过程调用．　
如果试图对一个已经联接的过程调用　SPI_connect　你可能得到一个　SPI_ERROR_CONNECT　错误信息　－　例如，如果你直接从另一个已联接的过程里调用一个过程．实际上，因为子进程可能使用　SPI，子进程返回后你的父进程将不能继续使用　SPI　（如果子进程调用了　SPI_finish）．这是一个糟糕的方面．

用法
算法
SPI_connect　执行下面操作：　
•　
初始化　SPI　用于查询执行和存储器管理的内部结构．　

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

SPI_finish
名称
SPI_finish　—　把你的过程与　SPI　管理器断开．　

语法
SPI_finish(void)
输入
无　

输出
int　
　　　
　SPI_OK_FINISH　如果正常断开，返回此信息　
SPI_ERROR_UNCONNECTED　如果从一个未联接过程调用，返回此信息　

描述
SPI_finish　关闭一个现有的与　Postgres　后端的联接．你应该在结束通过　SPI　管理器的操作后调用此函数．　
如果　SPI_finish　是在当前没有有效联接的情况下被调用的，你可能会得到一个　SPI_ERROR_UNCONNECTED　的返回．这样做没有什么根本性的错误，这意味着　SPI　管理器不做任何事情．

用法
SPI_finish　必须　作为一个已联接的过程的最后一步被调用，否则你可能得到不可预料的结果！注意：如果你从事务退出（通过　elog（ERROR）），你可以安全的忽略对　SPI_finish　的调用．
算法
SPI_finish　执行下列操作：　
•　
断开你的过程与　SPI　管理器的连接并且释放所有你的过程自　SPI_connect　起通过　palloc　分配的存储器．这些存储器不能再利用！请参考存储器管理．　

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

SPI_exec
名称
SPI_exec　—　创建一个执行规划　（分析器+规划器+优化器）并且执行一个查询．
语法
SPI_exec(query,　tcount)
输入
char　*query　
包含查询规划的字符串　
int　tcount　
返回的最大记录数　

输出
int　
　　　
　SPI_OK_EXEC　如果正确断开，返回此值　
SPI_ERROR_UNCONNECTED　如果从一个未联接的过程调用，返回此值　
SPI_ERROR_ARGUMENT　如果查询是　NULL（空）或　tcount　<　0，返回此值　
SPI_ERROR_UNCONNECTED　如果过程未联接，返回此值．　
SPI_ERROR_COPY　如果　COPY　TO/FROM　stdin（标准输入），返回此值．　
SPI_ERROR_CURSOR　如果　DECLARE/CLOSE　CURSOR，FETCH，返回此值　
SPI_ERROR_TRANSACTION　如果　BEGIN/ABORT/END，返回此值．　
SPI_ERROR_OPUNKNOWN　如果查询类型未知（这种情况不应发生）．　

如果你的查询执行成功，那么将返回下列非负数值之一：　
　　
　　　
　SPI_OK_UTILITY　如果执行了某些应用（例如　CREATE　TABLE　...）　
SPI_OK_SELECT　如果执行了　SELECT　（但不是　SELECT　...　INTO！）　
SPI_OK_SELINTO　如果执行了　SELECT　...　INTO　
SPI_OK_INSERT　如果执行了　INSERT（或　INSERT　...　SELECT）　
SPI_OK_DELETE　如果执行了　DELETE　
SPI_OK_UPDATE　如果执行了　UPDATE　


描述
SPI_exec　创建一个执行规划（分析器+规划器+优化器）并且执行查询以获取　tcount　条记录．
用法
这个（函数）只能从一个以联接的过程中调用．如果　tcount　是零则对查询扫描返回的所有记录都执行查询．使用　tcount　>　0　你可以限制查询执行的记录数．例如，　
SPI_exec　("insert　into　table　select　*　from　table",　5);
将最多允许　5　条记录插入表中．如果你的查询执行成功则返回一个非负数．　
注意：你可能在一个字符串里传递许多查询或一个查询字符串可能被　RULE　（规则）重写．SPI_exec　返回最后一个执行的查询的结果．
最后一个被执行的查询的实际记录数放在全局变量　SPI_processed　里返回（如果不是　SPI_OK_UTILITY）．如果返回了SPI_OK_SELECT　而且　SPI_processed　>　0　那么你可以通过全局指针　SPITupleTable　*SPI_tuptable　来访问这些选择了的记录：同样要注