PostgreSQL7.0手册-接口-55. pgtcl - TCL 绑定库
2019-09-08 23:34:12
供稿：网友
第五十五章. pgtcl - TCL 绑定库
内容
命令
例子
pgtcl 命令参考信息
pgtcl 是一个用于前端和 Postgres 后端交互的 tcl 包．它把大多数 libpq 库的函数/功能做成可用于 tcl 脚本．
这个包最初是 Jolly Chen 写的．
命令
表 55-1. pgtcl 命令
命令 描述
pg_connect 打开一个与后端服务器的联接
pg_disconnect 关闭一个联接
pg_conndefaults 获取联接选项和其他缺省值
pg_exec 向后端发送一个查询
pg_result 操作查询的结果
pg_select 在一个 SELECT 语句的结果上循环(处理)
pg_listen 建立一个用于 NOTIFY 消息的回叫
pg_lo_creat 创建一个大对象
pg_lo_open 打开一个大对象
pg_lo_close 关闭一个大对象
pg_lo_read 读取一个大对象
pg_lo_write 写一个大对象
pg_lo_lseek 在一个大对象里搜索一个位置
pg_lo_tell 返回一个大对象的当前搜索位置
pg_lo_unlink 删除一个大对象
pg_lo_import 把一个 Unix 输入到一个大对象里
pg_lo_export 把一个大对象输出到一个 Unix 文件里
这些命令在后续的页面里将继续深入描述．
pg_lo* 过程都是与 Postgres 大对象特性交互的接口．这些函数是仿照标准 Unix 文件系统接口的做法设计的．pg_lo* 过程应该用于一个 BEGIN/END 事务块里头，因为 pg_lo_open 返回的文件描述符只是在当前事务中有效．pg_lo_import 和 pg_lo_export 必须在一个 BEGIN/END 事务块里面使用．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
例子
这是一个如何使用这些过程的一个小例子：
# getDBs :
# get the names of all the databases at a given host and port number
# with the defaults being the localhost and port 5432
# return them in alphabetical order
proc getDBs { {host "localhost"} {port "5432"} } {
# datnames is the list to be result
set conn [pg_connect template1 -host $host -port $port]
set res [pg_exec $conn "SELECT datname FROM pg_database ORDER BY datname"]
set ntups [pg_result $res -numTuples]
for {set i 0} {$i < $ntups} {incr i} {
lappend datnames [pg_result $res -getTuple $i]
}
pg_result $res -clear
pg_disconnect $conn
return $datnames
}
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pgtcl 命令参考信息
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_connect
名称
pg_connect ― 打开一个到后端服务器的联接
语法
pg_connect -conninfo connectOptions
pg_connect dbName [-host hostName]
[-port portNumber] [-tty pqtty]
[-options optionalBackendArgs]
输入 (新风格)
connectOptions
一个联接选项字符串，每个（选项）都以形式 keyword = value 书写．
输入 (旧风格)
dbName
声明一个有效数据库名．
[-host hostName]
声明数据库 dbName 所在后端服务器的名称．
[-port portNumber]
声明数据库 dbName 所在后端服务器的 IP 端口号．
[-tty pqtty]
声明后端来的调试输出的可选文件或者控制台（tty）．
[-options optionalBackendArgs]
声明数据库 dbName 所在后端服务器的选项．
输出
dbHandle
成功时，返回一个数据库联接的句柄．句柄以前缀 "pgsql" 开头．
描述
pg_connect 打开一个与 Postgres 后端的联接．
两种语法都可用．旧风格里面每个可能的选项都在 pg_connect 语句里用一个选项开关分隔．在新风格里，可以用一个选项字符串包含多个选项值．参阅 pg_conndefaults 获取关于新风格的可用的选项信息．
用法
XXX thomas 1997-12-24
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_disconnect
名称
pg_disconnect ― 关闭一个与后端服务器的联接
语法
pg_disconnect dbHandle
Inputs
dbHandle
声明一个有效的数据库句柄．
输出
无
描述
pg_disconnect 关闭一个与后端 Postgres 服务器的联接．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_conndefaults
名称
pg_conndefaults ― 获取关于缺省联接参数的信息
语法
pg_conndefaults
输入
无．
输出
option list
结果是一个描述可能的联接选项和它们的当前值的列表．列表中每个元素是一个下面格式的子列表：
{optname label dispchar dispsize value}
这里 optname 可以用为 pg_connect -conninfo 里的选项．
描述
pg_conndefaults 返回关于联接的在 pg_connect -conninfo 里可用的联接选项的信息和当前每个选项的缺省值．
用法
pg_conndefaults
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_exec
名称
pg_exec ― 向后端发送一个查询字串
语法
pg_exec dbHandle queryString
输入
dbHandle
声明一个有效的数据库句柄．
queryString
声明一个有效的 SQL 查询．
输出
resultHandle
如果 Pgtcl 不能获得后端返回，将返回一个 Tcl 错误．否则，一个查询对象将被创建并且返回一个该对象的句柄．这个句柄可以传递给 pg_result 获取查询的结果．
描述
pg_exec 向 Postgres 后端提交一个查询并且返回一个结果．查询结果句柄以联接句柄开头并且增加了一个句号和一个结果数量．
注意没有 Tcl 错误生成并不意味着查询成功！一个后端返回的错误信息将被当作带有失败状态的查询结果进行处理，而不是在 pg_exec 里生成一个 Tcl 错误．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_result
名称
pg_result ― 获取查询结果的信息
语法
pg_result resultHandle resultOption
输入
resultHandle
查询结果的句柄．
resultOption
声明几个可能选项之一．
选项
-status
结果的状态．
-error
如果状态标识错误时是错误信息；否则是一个空字符串．
-conn
生成结果的联接．
-oid
如果命令是一个 INSERT，这里是插入的记录的 OID；否则是一个空字符串．
-numTuples
查询返回的记录个数．
-numAttrs
每条记录的字段数目．
-list VarName
把结果赋与一个列表．
-assign arrayName
把结果赋予一个数组，使用预定的形式（tupno，attributeName）．
-assignbyidx arrayName ?appendstr?
把结果赋予一个数组，用第一个字段的值和其余字段的名称为键字．如果给出了 appendstr 那么附加到每个键字上．简而言之，除了第一个字段外每个记录都存放到数组里，使用预定的形式（firstFieldValue，fieldNameAppendStr）．
-getTuple tupleNumber
返回列表里指定的记录的各个域．记录数从零开始．
-tupleArray tupleNumber arrayName
以字段名为索引向数组 arrayName 里存储记录字段，记录数从零开始．
-attributes
返回一个记录字段的名称的列表．
-lAttributes
返回一个子列表的列表，{name ftype fsize} 用于每条记录字段．
-clear
清理查询对象结果．
输出
由选定的选项决定的结果，如上所述．
描述
pg_result 返回前面的一个 pg_exec 创建的查询结果的信息．
你可以保留查询结果任意长的时间，但是在你对其处理完毕之后，一定要通过执行 pg_result -clear 来释放它们．否则，你就有一处内存泄露，而且 Pgtcl 最终将开始抱怨你创建了太多的查询结果对象．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_select
名称
pg_select ― 逐一处理一个 SELECT 语句的结果
语法
pg_select dbHandle queryString
arrayVar queryProcedure
输入
dbHandle
声明一个有效的数据库句柄．
queryString
声明一个有效的 SQL 选择查询．
arrayVar
用于存放返回记录的数组变量．
queryProcedure
在每个找到的记录上运行的过程．
输出
resultHandle
返回的结果要么是一个错误信息要么是一个查询结果的句柄．
描述
pg_select 向 Postgres 后端提交一个 SELECT 查询，并且对结果里的每个记录执行一个给定的代码段．queryString 必须是一个 SELECT 语句．任何其它东西都返回一个错误．arrayVar 变量是一个在循环中使用的数组名．对每个记录，arrayVar 都被填充为记录的字段值，使用字段名作为数组的索引．然后执行 queryProcedure ．
用法
如果表 "table" 有字段 "control" 和 "name" （以及可能还有其他字段）下面的东西就能工作：
pg_select $pgconn "SELECT * from table" array {
puts [format "%5d %s" array(control) array(name)]
}
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_listen
名称
pg_listen ― 设置或者改变一个侦听异步 NOTIFY 消息的回调（函数）
语法
pg_listen dbHandle notifyName callbackCommand
输入
dbHandle
声明一个有效的数据库句柄．
notifyName
声明启停侦听（动作）的通知条件名称．
callbackCommand
如果存在且非空，提供一个在匹配的通知到达时执行的命令字符串．
输出
无
描述
pg_listen 创建，修改或取消一个对来自 Postgres 后端的异步 NOTIFY 消息请求的侦听．带有 callbackCommand 参数时，建立请求或者已经存在的命令字串被代替．不带 callbackCommand 参数时，取消前面一个请求．
在一个 pg_listen 请求建立起来后，当一个与给定名称匹配的 NOTIFY 消息从后端到达后就执行声明的命令字串．当任何Postgres 客户应用发送一个引用该名称的 NOTIFY 消息后都会发生这个过程．（注意这个名字可以是，但又不必须是一个数据库里现存的关系．）命令行字串是从 Tcl 空闲循环运行的．那也是用 Tk 写的应用的正常的空闲状态．在非 Tk 的 Tcl 脚本里，你可以执行 update 或 vwait 来导致进入空闲循环．
你在使用 pg_listen 时不应该直接调用 SQL 语句 LISTEN 或 UNLISTEN．Pgtcl 替你使用那些语句．但是如果你想自己发送一个 NOTIFY 消息，用 pg_exec 调用 SQL NOTIFY 语句．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_creat
名称
pg_lo_creat ― 创建一个大对象
语法
pg_lo_creat conn mode
输入
conn
声明一个有效的数据库联接．
mode
声明大对象的访问模式
输出
objOid
创建的大对象的 oid （对象标识）．
描述
pg_lo_creat 创建一个倒转大对象（Inversion Large Object ）
用法
模式可以是任意 INV_READ，INV_WRITE，和 INV_ARCHIVE 的或（OR）．或（OR）运算的分隔符是 "|"．
[pg_lo_creat $conn "INV_READ|INV_WRITE"]
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_open
名称
pg_lo_open ― 打开一个大对象
语法
pg_lo_open conn objOid mode
输入
conn
声明一个有效的数据库联接．
objOid
声明一个有效的大对象 oid （对象标识）．
mode
声明大对象的访问模式
输出
fd
一个可以用于后面 pg_lo* 过程的文件描述符．
描述
pg_lo_open 打开一个转置大对象（Inversion Large Object）．
用法
模式可以是 "r"，"w"，或 "rw"．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_close
名称
pg_lo_close ― 关闭一个大对象
语法
pg_lo_close conn fd
输入
conn
声明一个有效的数据库联接．
fd
一个可以用于后面 pg_lo* 过程的文件描述符．
输出
无
描述
pg_lo_close 关闭一个倒转大对象．
用法
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_read
名称
pg_lo_read ― 读取一个大对象
语法
pg_lo_read conn fd bufVar len
输入
conn
声明一个有效的数据库联接．
fd
从 pg_lo_open 来的大对象的文件描述符．
bufVar
声明一个有效的缓冲区变量用以包含大对象数据段．
len
声明大对象数据段允许的最大尺寸．
输出
无
描述
pg_lo_read 从一个大对象读取最多 len 字节到名为 bufVar 的变量中．
用法
bufVar 必须是一个有效的变量名．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_write
名称
pg_lo_write ― 写入一个大对象
语法
pg_lo_write conn fd buf len
输入
conn
声明一个有效的数据库联接．
fd
从 pg_lo_open 来的大对象的文件描述符．
buf
声明一个有效的字符串变量用于写入大对象．
len
声明要写入的字符串的最大尺寸．
输出
无
描述
pg_lo_write 从一个变量 buf 向一个大对象写入至多 len 字节．
用法
buf 必须是实际要写的字符串，而不是一个变量名．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_lseek
名称
pg_lo_lseek ― 在一个大对象里定位到某个位置
语法
pg_lo_lseek conn fd offset whence
输入
conn
声明一个有效的数据库联接．
fd
从 pg_lo_open 来的大对象的文件描述符．
offset
声明一个以零为基的字节数偏移量．
whence
起点（whence）可以是 "SEEK_CUR"，"SEEK_END"，或 "SEEK_SET"
输出
无
描述
pg_lo_lseek 把当前（文件）指针放到大对象开始偏移 offset 字节处．
用法
whence （起点）可以是 "SEEK_CUR"，"SEEK_END"，或 "SEEK_SET"．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_tell
名称
pg_lo_tell ― 返回一个大对象的当前（文件）指针位置
语法
pg_lo_tell conn fd
输入
conn
声明一个有效的数据库联接．
fd
从 pg_lo_open 来的大对象的文件描述符．
输出
offset
一个零为基的字节数偏移量，可以用于 pg_lo_lseek 输入．
描述
pg_lo_tell 返回以字节计的当前指针相对大对象起点的偏移 offset ．
用法
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_unlink
名称
pg_lo_unlink ― 删除一个大对象
语法
pg_lo_unlink conn lobjId
输入
conn
声明一个有效的数据库联接．
lobjId
大对象的标识．XXX 是否与其他调用里的 objOid （对象标识）一样呢？？ - thomas 1998-01-11
输出
无
描述
pg_lo_unlink 删除声明的大对象．
用法
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_import
名称
pg_lo_import ― 从一个 Unix 文件输入一个大对象
语法
pg_lo_import conn filename
输入
conn
声明一个有效的数据库联接．
filename
Unix 文件名．
输出
无 XXX 这里是否返回一个 lobjId？ 是否与其他调用里的 objOid （对象标识）一样呢？ thomas - 1998-01-11
描述
pg_lo_import 读取声明的文件并且把其内容放到一个大对象中．
用法
pg_lo_import 必须在一对 BEGIN/END 事务块中调用．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_export
名称
pg_lo_export ― 把一个大对象输出到一个 Unix 文件中去．
语法
pg_lo_export conn lobjId filename
输入
conn
声明一个有效的数据库联接．
lobjId
大对象标识．XXX 是否与其他调用里的 objOid（对象标识）一样呢？？ thomas - 1998-01-11
filename
Unix 文件名．
输出
无 XXX 这里是否返回一个 lobjId？是否与其他调用里的 objOid （对象标识）一样呢？thomas - 1998-01-11
描述
pg_lo_export 把声明的大对象写入到一个 Unix 文件中去．
用法
pg_lo_export 必须在一对 BEGIN/END 事务块中调用．
--------------------------------------------------------------------------------
