PostgreSQL7.0手册-用户手册-11. PL/Tcl - TCL 过程语言
减小字体
增大字体和 NOIND，与用于 C 函数的 elog() 一样．
quote string
复制所有出现的单引号和反斜杠字符．当赋予 spi_exec 或 spi_prepare （不用于 spi_execp 使用的数组）的查询字符串里使用了变量时就要使用这个命令．想象下面的查询字符串
"SELECT '$val' AS ret"
如果 Tcl 变量 val 实际包含 "doesn't"．这样会导致最终的查询字符串结果
"SELECT 'doesn't' AS ret"
这个字符串在 spi_exec 或 spi_prepare 里将导致一个分析错误．它将包括
"SELECT 'doesn''t' AS ret"
并且不得不写成
"SELECT '[ quote $val ]' AS ret"
spi_exec ?-count n? ?-array name? query ?loop-body?
调用 分析器/规划器（调度器）/优化器/执行器运行查询．可选的 -count 值告诉 spi_exec 该查询可以处理的最大行数．
如果查询是一个 SELECT 语句并且给出了可选的循环体（一个 Tcl 命令的语句体，象一个 foreach 命令），它就会计算每个选择的行并且如期望的那样继续/中断。选择的字段的值被放到命名为列名称的变量里面去了．所以一个
spi_exec "SELECT count(*) AS cnt FROM pg_proc"
将把变量 $cnt 置为 pg_proc 系统表里的行数．如果给出了可选的 -array ，列/字段的值将保存在相关的名为 'name' 的数组里，而不是分离的变量．
spi_exec -array C "SELECT * FROM pg_class" {
elog DEBUG "have table $C(relname)"
}
将为 pg_class 的每一行打印一个 DEBUG 日志信息．spi_exec 返回的值是查询涉及到的保存在全局变量 SPI_processed 里的行数．
spi_prepare query typelist
为后面执行准备并且保存一个查询规划．这里与 C 级别的 SPI_prepare 有一些小区别，就是该规划将自动拷贝到顶级存储器环境．因此，目前没有办法准备一个规划而不存储它．
如果查询引用了参数，类型名必须做为 Tcl 数组给出．从 spi_prepare 返回的值是一个查询 ID，该 ID 将被后继的 spi_execp 调用使用．参阅 spi_execp 中的例子．
spi_exec ?-count n? ?-arrayname? ?-nulls.string? query ?value-list? ?loop-body?
代入参数执行一个来自 spi_prepare 的规划．可选的 -count 数值告诉 spi_execp 可以被该查询处理的最大行数．
可选用于 -nulls 的值是一个空格字符串，并且 'n' 字符告诉 spi_execp 哪一个数值是 NULL．如果给出该值，它必须包含数值个数的确切长度．
queryid 是 spi_prepare 调用返回的 ID．（译注：query？）
如果有一个类型列表给予了 spi_prepare，必须在查询后面给 spi_execp 一个相同长度的 Tcl 数值列表（数组）．如果 spi_prepare 里的类型表是空的，此参数必须忽略．
如果查询是一个 SELECT 语句，有与 spi_exec 里描述的循环体和用于所选的字段的变量有一样的现象．
这里是一个使用准备好了的规划的 PL/Tcl 函数例子：
CREATE FUNCTION t1_count(int4, int4) RETURNS int4 AS '
if {![ info exists GD(plan) ]} {
# prepare the saved plan on the first call
set GD(plan) [ spi_prepare \\
"SELECT count(*) AS cnt FROM t1 WHERE num >= \\$1 AND num <= \\$2" \\
int4 ]
}
spi_execp -count 1 $GD(plan) [ list $1 $2 ]
return $cnt
' LANGUAGE 'pltcl';
注意创建函数时每个 Tcl 会看到的反斜杠必须写双份，因为在 CREATE FUNCTION 时主分析器也处理反斜杠．在给予 spi_prepare 的查询字符串里面应该是真正的标识参数位置的美圆符号，而不应让第一次函数调用给出的值把 $1 给替换掉．
模块和未知的命令
PL/Tcl 对常用的东西有一个特殊的支持．它识别两个魔数表，pltcl_modules 和 pltcl_modfuncs．如果它们存在，模块 'unknown' 在创建以后马上装载入解释器．当调用一个未知的 Tcl 过程时，未知的 proc 马上检查该过程是否在其中一个模块中定义了．如果的确定义了，该模块按要求装载进来．要打开这个特性，PL/Tcl 调用管理器必须带着 -DPLTCL_UNKNOWN_SUPPORT 设置编译．
在 PL/Tcl 源文件的模块子目录里有一些维护这些表的脚本，包括在最初必须安装的未知模块的源文件．
--------------------------------------------------------------------------------
quote string
复制所有出现的单引号和反斜杠字符．当赋予 spi_exec 或 spi_prepare （不用于 spi_execp 使用的数组）的查询字符串里使用了变量时就要使用这个命令．想象下面的查询字符串
"SELECT '$val' AS ret"
如果 Tcl 变量 val 实际包含 "doesn't"．这样会导致最终的查询字符串结果
"SELECT 'doesn't' AS ret"
这个字符串在 spi_exec 或 spi_prepare 里将导致一个分析错误．它将包括
"SELECT 'doesn''t' AS ret"
并且不得不写成
"SELECT '[ quote $val ]' AS ret"
spi_exec ?-count n? ?-array name? query ?loop-body?
调用 分析器/规划器（调度器）/优化器/执行器运行查询．可选的 -count 值告诉 spi_exec 该查询可以处理的最大行数．
如果查询是一个 SELECT 语句并且给出了可选的循环体（一个 Tcl 命令的语句体，象一个 foreach 命令），它就会计算每个选择的行并且如期望的那样继续/中断。选择的字段的值被放到命名为列名称的变量里面去了．所以一个
spi_exec "SELECT count(*) AS cnt FROM pg_proc"
将把变量 $cnt 置为 pg_proc 系统表里的行数．如果给出了可选的 -array ，列/字段的值将保存在相关的名为 'name' 的数组里，而不是分离的变量．
spi_exec -array C "SELECT * FROM pg_class" {
elog DEBUG "have table $C(relname)"
}
将为 pg_class 的每一行打印一个 DEBUG 日志信息．spi_exec 返回的值是查询涉及到的保存在全局变量 SPI_processed 里的行数．
spi_prepare query typelist
为后面执行准备并且保存一个查询规划．这里与 C 级别的 SPI_prepare 有一些小区别，就是该规划将自动拷贝到顶级存储器环境．因此，目前没有办法准备一个规划而不存储它．
如果查询引用了参数，类型名必须做为 Tcl 数组给出．从 spi_prepare 返回的值是一个查询 ID，该 ID 将被后继的 spi_execp 调用使用．参阅 spi_execp 中的例子．
spi_exec ?-count n? ?-arrayname? ?-nulls.string? query ?value-list? ?loop-body?
代入参数执行一个来自 spi_prepare 的规划．可选的 -count 数值告诉 spi_execp 可以被该查询处理的最大行数．
可选用于 -nulls 的值是一个空格字符串，并且 'n' 字符告诉 spi_execp 哪一个数值是 NULL．如果给出该值，它必须包含数值个数的确切长度．
queryid 是 spi_prepare 调用返回的 ID．（译注：query？）
如果有一个类型列表给予了 spi_prepare，必须在查询后面给 spi_execp 一个相同长度的 Tcl 数值列表（数组）．如果 spi_prepare 里的类型表是空的，此参数必须忽略．
如果查询是一个 SELECT 语句，有与 spi_exec 里描述的循环体和用于所选的字段的变量有一样的现象．
这里是一个使用准备好了的规划的 PL/Tcl 函数例子：
CREATE FUNCTION t1_count(int4, int4) RETURNS int4 AS '
if {![ info exists GD(plan) ]} {
# prepare the saved plan on the first call
set GD(plan) [ spi_prepare \\
"SELECT count(*) AS cnt FROM t1 WHERE num >= \\$1 AND num <= \\$2" \\
int4 ]
}
spi_execp -count 1 $GD(plan) [ list $1 $2 ]
return $cnt
' LANGUAGE 'pltcl';
注意创建函数时每个 Tcl 会看到的反斜杠必须写双份，因为在 CREATE FUNCTION 时主分析器也处理反斜杠．在给予 spi_prepare 的查询字符串里面应该是真正的标识参数位置的美圆符号，而不应让第一次函数调用给出的值把 $1 给替换掉．
模块和未知的命令
PL/Tcl 对常用的东西有一个特殊的支持．它识别两个魔数表，pltcl_modules 和 pltcl_modfuncs．如果它们存在，模块 'unknown' 在创建以后马上装载入解释器．当调用一个未知的 Tcl 过程时，未知的 proc 马上检查该过程是否在其中一个模块中定义了．如果的确定义了，该模块按要求装载进来．要打开这个特性，PL/Tcl 调用管理器必须带着 -DPLTCL_UNKNOWN_SUPPORT 设置编译．
在 PL/Tcl 源文件的模块子目录里有一些维护这些表的脚本，包括在最初必须安装的未知模块的源文件．
--------------------------------------------------------------------------------
