PostgreSQL7.0手册-接口-55. pgtcl - TCL 绑定库

第五十五章.　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_READINV_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　事务块中调用．　

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