PostgreSQL7.0手冊-接口-55. pgtcl - TCL 綁定庫
2019-09-08 23:34:12
供稿：網(wǎng)友
第五十五章. pgtcl - TCL 綁定庫
內(nèi)容
命令
例子
pgtcl 命令參考信息
pgtcl 是一個(gè)用于前端和 Postgres 后端交互的 tcl 包．它把大多數(shù) libpq 庫的函數(shù)/功能做成可用于 tcl 腳本．
這個(gè)包最初是 Jolly Chen 寫的．
命令
表 55-1. pgtcl 命令
命令 描述
pg_connect 打開一個(gè)與后端服務(wù)器的聯(lián)接
pg_disconnect 關(guān)閉一個(gè)聯(lián)接
pg_conndefaults 獲取聯(lián)接選項(xiàng)和其他缺省值
pg_exec 向后端發(fā)送一個(gè)查詢
pg_result 操作查詢的結(jié)果
pg_select 在一個(gè) SELECT 語句的結(jié)果上循環(huán)(處理)
pg_listen 建立一個(gè)用于 NOTIFY 消息的回叫
pg_lo_creat 創(chuàng)建一個(gè)大對(duì)象
pg_lo_open 打開一個(gè)大對(duì)象
pg_lo_close 關(guān)閉一個(gè)大對(duì)象
pg_lo_read 讀取一個(gè)大對(duì)象
pg_lo_write 寫一個(gè)大對(duì)象
pg_lo_lseek 在一個(gè)大對(duì)象里搜索一個(gè)位置
pg_lo_tell 返回一個(gè)大對(duì)象的當(dāng)前搜索位置
pg_lo_unlink 刪除一個(gè)大對(duì)象
pg_lo_import 把一個(gè) Unix 輸入到一個(gè)大對(duì)象里
pg_lo_export 把一個(gè)大對(duì)象輸出到一個(gè) Unix 文件里
這些命令在后續(xù)的頁面里將繼續(xù)深入描述．
pg_lo* 過程都是與 Postgres 大對(duì)象特性交互的接口．這些函數(shù)是仿照標(biāo)準(zhǔn) Unix 文件系統(tǒng)接口的做法設(shè)計(jì)的．pg_lo* 過程應(yīng)該用于一個(gè) BEGIN/END 事務(wù)塊里頭，因?yàn)椤g_lo_open 返回的文件描述符只是在當(dāng)前事務(wù)中有效．pg_lo_import 和 pg_lo_export 必須在一個(gè) BEGIN/END 事務(wù)塊里面使用．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
例子
這是一個(gè)如何使用這些過程的一個(gè)小例子：
# 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 ― 打開一個(gè)到后端服務(wù)器的聯(lián)接
語法
pg_connect -conninfo connectOptions
pg_connect dbName [-host hostName]
[-port portNumber] [-tty pqtty]
[-options optionalBackendArgs]
輸入 (新風(fēng)格)
connectOptions
一個(gè)聯(lián)接選項(xiàng)字符串，每個(gè)（選項(xiàng)）都以形式 keyword = value 書寫．
輸入 (舊風(fēng)格)
dbName
聲明一個(gè)有效數(shù)據(jù)庫名．
[-host hostName]
聲明數(shù)據(jù)庫 dbName 所在后端服務(wù)器的名稱．
[-port portNumber]
聲明數(shù)據(jù)庫 dbName 所在后端服務(wù)器的 IP 端口號(hào)．
[-tty pqtty]
聲明后端來的調(diào)試輸出的可選文件或者控制臺(tái)（tty）．
[-options optionalBackendArgs]
聲明數(shù)據(jù)庫 dbName 所在后端服務(wù)器的選項(xiàng)．
輸出
dbHandle
成功時(shí)，返回一個(gè)數(shù)據(jù)庫聯(lián)接的句柄．句柄以前綴 "pgsql" 開頭．
描述
pg_connect 打開一個(gè)與 Postgres 后端的聯(lián)接．
兩種語法都可用．舊風(fēng)格里面每個(gè)可能的選項(xiàng)都在 pg_connect 語句里用一個(gè)選項(xiàng)開關(guān)分隔．在新風(fēng)格里，可以用一個(gè)選項(xiàng)字符串包含多個(gè)選項(xiàng)值．參閱 pg_conndefaults 獲取關(guān)于新風(fēng)格的可用的選項(xiàng)信息．
用法
XXX thomas 1997-12-24
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_disconnect
名稱
pg_disconnect ― 關(guān)閉一個(gè)與后端服務(wù)器的聯(lián)接
語法
pg_disconnect dbHandle
Inputs
dbHandle
聲明一個(gè)有效的數(shù)據(jù)庫句柄．
輸出
無
描述
pg_disconnect 關(guān)閉一個(gè)與后端 Postgres 服務(wù)器的聯(lián)接．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_conndefaults
名稱
pg_conndefaults ― 獲取關(guān)于缺省聯(lián)接參數(shù)的信息
語法
pg_conndefaults
輸入
無．
輸出
option list
結(jié)果是一個(gè)描述可能的聯(lián)接選項(xiàng)和它們的當(dāng)前值的列表．列表中每個(gè)元素是一個(gè)下面格式的子列表：
{optname label dispchar dispsize value}
這里 optname 可以用為 pg_connect -conninfo 里的選項(xiàng)．
描述
pg_conndefaults 返回關(guān)于聯(lián)接的在 pg_connect -conninfo 里可用的聯(lián)接選項(xiàng)的信息和當(dāng)前每個(gè)選項(xiàng)的缺省值．
用法
pg_conndefaults
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_exec
名稱
pg_exec ― 向后端發(fā)送一個(gè)查詢字串
語法
pg_exec dbHandle queryString
輸入
dbHandle
聲明一個(gè)有效的數(shù)據(jù)庫句柄．
queryString
聲明一個(gè)有效的 SQL 查詢．
輸出
resultHandle
如果 Pgtcl 不能獲得后端返回，將返回一個(gè) Tcl 錯(cuò)誤．否則，一個(gè)查詢對(duì)象將被創(chuàng)建并且返回一個(gè)該對(duì)象的句柄．這個(gè)句柄可以傳遞給 pg_result 獲取查詢的結(jié)果．
描述
pg_exec 向 Postgres 后端提交一個(gè)查詢并且返回一個(gè)結(jié)果．查詢結(jié)果句柄以聯(lián)接句柄開頭并且增加了一個(gè)句號(hào)和一個(gè)結(jié)果數(shù)量．
注意沒有 Tcl 錯(cuò)誤生成并不意味著查詢成功！一個(gè)后端返回的錯(cuò)誤信息將被當(dāng)作帶有失敗狀態(tài)的查詢結(jié)果進(jìn)行處理，而不是在 pg_exec 里生成一個(gè) Tcl 錯(cuò)誤．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_result
名稱
pg_result ― 獲取查詢結(jié)果的信息
語法
pg_result resultHandle resultOption
輸入
resultHandle
查詢結(jié)果的句柄．
resultOption
聲明幾個(gè)可能選項(xiàng)之一．
選項(xiàng)
-status
結(jié)果的狀態(tài)．
-error
如果狀態(tài)標(biāo)識(shí)錯(cuò)誤時(shí)是錯(cuò)誤信息；否則是一個(gè)空字符串．
-conn
生成結(jié)果的聯(lián)接．
-oid
如果命令是一個(gè) INSERT，這里是插入的記錄的 OID；否則是一個(gè)空字符串．
-numTuples
查詢返回的記錄個(gè)數(shù)．
-numAttrs
每條記錄的字段數(shù)目．
-list VarName
把結(jié)果賦與一個(gè)列表．
-assign arrayName
把結(jié)果賦予一個(gè)數(shù)組，使用預(yù)定的形式（tupno，attributeName）．
-assignbyidx arrayName ?appendstr?
把結(jié)果賦予一個(gè)數(shù)組，用第一個(gè)字段的值和其余字段的名稱為鍵字．如果給出了 appendstr 那么附加到每個(gè)鍵字上．簡而言之，除了第一個(gè)字段外每個(gè)記錄都存放到數(shù)組里，使用預(yù)定的形式（firstFieldValue，fieldNameAppendStr）．
-getTuple tupleNumber
返回列表里指定的記錄的各個(gè)域．記錄數(shù)從零開始．
-tupleArray tupleNumber arrayName
以字段名為索引向數(shù)組 arrayName 里存儲(chǔ)記錄字段，記錄數(shù)從零開始．
-attributes
返回一個(gè)記錄字段的名稱的列表．
-lAttributes
返回一個(gè)子列表的列表，{name ftype fsize} 用于每條記錄字段．
-clear
清理查詢對(duì)象結(jié)果．
輸出
由選定的選項(xiàng)決定的結(jié)果，如上所述．
描述
pg_result 返回前面的一個(gè) pg_exec 創(chuàng)建的查詢結(jié)果的信息．
你可以保留查詢結(jié)果任意長的時(shí)間，但是在你對(duì)其處理完畢之后，一定要通過執(zhí)行 pg_result -clear 來釋放它們．否則，你就有一處內(nèi)存泄露，而且 Pgtcl 最終將開始抱怨你創(chuàng)建了太多的查詢結(jié)果對(duì)象．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_select
名稱
pg_select ― 逐一處理一個(gè) SELECT 語句的結(jié)果
語法
pg_select dbHandle queryString
arrayVar queryProcedure
輸入
dbHandle
聲明一個(gè)有效的數(shù)據(jù)庫句柄．
queryString
聲明一個(gè)有效的 SQL 選擇查詢．
arrayVar
用于存放返回記錄的數(shù)組變量．
queryProcedure
在每個(gè)找到的記錄上運(yùn)行的過程．
輸出
resultHandle
返回的結(jié)果要么是一個(gè)錯(cuò)誤信息要么是一個(gè)查詢結(jié)果的句柄．
描述
pg_select 向 Postgres 后端提交一個(gè) SELECT 查詢，并且對(duì)結(jié)果里的每個(gè)記錄執(zhí)行一個(gè)給定的代碼段．queryString 必須是一個(gè) SELECT 語句．任何其它東西都返回一個(gè)錯(cuò)誤．a(chǎn)rrayVar 變量是一個(gè)在循環(huán)中使用的數(shù)組名．對(duì)每個(gè)記錄，arrayVar 都被填充為記錄的字段值，使用字段名作為數(shù)組的索引．然后執(zhí)行 queryProcedure ．
用法
如果表 "table" 有字段 "control" 和 "name" （以及可能還有其他字段）下面的東西就能工作：
pg_select $pgconn "SELECT * from table" array {
puts [format "%5d %s" array(control) array(name)]
}
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_listen
名稱
pg_listen ― 設(shè)置或者改變一個(gè)偵聽異步 NOTIFY 消息的回調(diào)（函數(shù)）
語法
pg_listen dbHandle notifyName callbackCommand
輸入
dbHandle
聲明一個(gè)有效的數(shù)據(jù)庫句柄．
notifyName
聲明啟停偵聽（動(dòng)作）的通知條件名稱．
callbackCommand
如果存在且非空，提供一個(gè)在匹配的通知到達(dá)時(shí)執(zhí)行的命令字符串．
輸出
無
描述
pg_listen 創(chuàng)建，修改或取消一個(gè)對(duì)來自 Postgres 后端的異步 NOTIFY 消息請求的偵聽．帶有 callbackCommand 參數(shù)時(shí)，建立請求或者已經(jīng)存在的命令字串被代替．不帶 callbackCommand 參數(shù)時(shí)，取消前面一個(gè)請求．
在一個(gè) pg_listen 請求建立起來后，當(dāng)一個(gè)與給定名稱匹配的 NOTIFY 消息從后端到達(dá)后就執(zhí)行聲明的命令字串．當(dāng)任何Postgres 客戶應(yīng)用發(fā)送一個(gè)引用該名稱的 NOTIFY 消息后都會(huì)發(fā)生這個(gè)過程．（注意這個(gè)名字可以是，但又不必須是一個(gè)數(shù)據(jù)庫里現(xiàn)存的關(guān)系．）命令行字串是從 Tcl 空閑循環(huán)運(yùn)行的．那也是用 Tk 寫的應(yīng)用的正常的空閑狀態(tài)．在非 Tk 的 Tcl 腳本里，你可以執(zhí)行 update 或 vwait 來導(dǎo)致進(jìn)入空閑循環(huán)．
你在使用 pg_listen 時(shí)不應(yīng)該直接調(diào)用 SQL 語句 LISTEN 或 UNLISTEN．Pgtcl 替你使用那些語句．但是如果你想自己發(fā)送一個(gè) NOTIFY 消息，用 pg_exec 調(diào)用 SQL NOTIFY 語句．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_creat
名稱
pg_lo_creat ― 創(chuàng)建一個(gè)大對(duì)象
語法
pg_lo_creat conn mode
輸入
conn
聲明一個(gè)有效的數(shù)據(jù)庫聯(lián)接．
mode
聲明大對(duì)象的訪問模式
輸出
objOid
創(chuàng)建的大對(duì)象的 oid （對(duì)象標(biāo)識(shí)）．
描述
pg_lo_creat 創(chuàng)建一個(gè)倒轉(zhuǎn)大對(duì)象（Inversion Large Object ）
用法
模式可以是任意 INV_READ，INV_WRITE，和 INV_ARCHIVE 的或（OR）．或（OR）運(yùn)算的分隔符是 "|"．
[pg_lo_creat $conn "INV_READ|INV_WRITE"]
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_open
名稱
pg_lo_open ― 打開一個(gè)大對(duì)象
語法
pg_lo_open conn objOid mode
輸入
conn
聲明一個(gè)有效的數(shù)據(jù)庫聯(lián)接．
objOid
聲明一個(gè)有效的大對(duì)象 oid （對(duì)象標(biāo)識(shí)）．
mode
聲明大對(duì)象的訪問模式
輸出
fd
一個(gè)可以用于后面 pg_lo* 過程的文件描述符．
描述
pg_lo_open 打開一個(gè)轉(zhuǎn)置大對(duì)象（Inversion Large Object）．
用法
模式可以是 "r"，"w"，或 "rw"．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_close
名稱
pg_lo_close ― 關(guān)閉一個(gè)大對(duì)象
語法
pg_lo_close conn fd
輸入
conn
聲明一個(gè)有效的數(shù)據(jù)庫聯(lián)接．
fd
一個(gè)可以用于后面 pg_lo* 過程的文件描述符．
輸出
無
描述
pg_lo_close 關(guān)閉一個(gè)倒轉(zhuǎn)大對(duì)象．
用法
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_read
名稱
pg_lo_read ― 讀取一個(gè)大對(duì)象
語法
pg_lo_read conn fd bufVar len
輸入
conn
聲明一個(gè)有效的數(shù)據(jù)庫聯(lián)接．
fd
從 pg_lo_open 來的大對(duì)象的文件描述符．
bufVar
聲明一個(gè)有效的緩沖區(qū)變量用以包含大對(duì)象數(shù)據(jù)段．
len
聲明大對(duì)象數(shù)據(jù)段允許的最大尺寸．
輸出
無
描述
pg_lo_read 從一個(gè)大對(duì)象讀取最多 len 字節(jié)到名為 bufVar 的變量中．
用法
bufVar 必須是一個(gè)有效的變量名．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_write
名稱
pg_lo_write ― 寫入一個(gè)大對(duì)象
語法
pg_lo_write conn fd buf len
輸入
conn
聲明一個(gè)有效的數(shù)據(jù)庫聯(lián)接．
fd
從 pg_lo_open 來的大對(duì)象的文件描述符．
buf
聲明一個(gè)有效的字符串變量用于寫入大對(duì)象．
len
聲明要寫入的字符串的最大尺寸．
輸出
無
描述
pg_lo_write 從一個(gè)變量 buf 向一個(gè)大對(duì)象寫入至多 len 字節(jié)．
用法
buf 必須是實(shí)際要寫的字符串，而不是一個(gè)變量名．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_lseek
名稱
pg_lo_lseek ― 在一個(gè)大對(duì)象里定位到某個(gè)位置
語法
pg_lo_lseek conn fd offset whence
輸入
conn
聲明一個(gè)有效的數(shù)據(jù)庫聯(lián)接．
fd
從 pg_lo_open 來的大對(duì)象的文件描述符．
offset
聲明一個(gè)以零為基的字節(jié)數(shù)偏移量．
whence
起點(diǎn)（whence）可以是 "SEEK_CUR"，"SEEK_END"，或 "SEEK_SET"
輸出
無
描述
pg_lo_lseek 把當(dāng)前（文件）指針放到大對(duì)象開始偏移 offset 字節(jié)處．
用法
whence （起點(diǎn)）可以是 "SEEK_CUR"，"SEEK_END"，或 "SEEK_SET"．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_tell
名稱
pg_lo_tell ― 返回一個(gè)大對(duì)象的當(dāng)前（文件）指針位置
語法
pg_lo_tell conn fd
輸入
conn
聲明一個(gè)有效的數(shù)據(jù)庫聯(lián)接．
fd
從 pg_lo_open 來的大對(duì)象的文件描述符．
輸出
offset
一個(gè)零為基的字節(jié)數(shù)偏移量，可以用于 pg_lo_lseek 輸入．
描述
pg_lo_tell 返回以字節(jié)計(jì)的當(dāng)前指針相對(duì)大對(duì)象起點(diǎn)的偏移 offset ．
用法
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_unlink
名稱
pg_lo_unlink ― 刪除一個(gè)大對(duì)象
語法
pg_lo_unlink conn lobjId
輸入
conn
聲明一個(gè)有效的數(shù)據(jù)庫聯(lián)接．
lobjId
大對(duì)象的標(biāo)識(shí)．XXX 是否與其他調(diào)用里的 objOid （對(duì)象標(biāo)識(shí)）一樣呢？？ - thomas 1998-01-11
輸出
無
描述
pg_lo_unlink 刪除聲明的大對(duì)象．
用法
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_import
名稱
pg_lo_import ― 從一個(gè) Unix 文件輸入一個(gè)大對(duì)象
語法
pg_lo_import conn filename
輸入
conn
聲明一個(gè)有效的數(shù)據(jù)庫聯(lián)接．
filename
Unix 文件名．
輸出
無 XXX 這里是否返回一個(gè) lobjId？ 是否與其他調(diào)用里的 objOid （對(duì)象標(biāo)識(shí)）一樣呢？ thomas - 1998-01-11
描述
pg_lo_import 讀取聲明的文件并且把其內(nèi)容放到一個(gè)大對(duì)象中．
用法
pg_lo_import 必須在一對(duì) BEGIN/END 事務(wù)塊中調(diào)用．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
pg_lo_export
名稱
pg_lo_export ― 把一個(gè)大對(duì)象輸出到一個(gè) Unix 文件中去．
語法
pg_lo_export conn lobjId filename
輸入
conn
聲明一個(gè)有效的數(shù)據(jù)庫聯(lián)接．
lobjId
大對(duì)象標(biāo)識(shí)．XXX 是否與其他調(diào)用里的 objOid（對(duì)象標(biāo)識(shí)）一樣呢？？ thomas - 1998-01-11
filename
Unix 文件名．
輸出
無 XXX 這里是否返回一個(gè) lobjId？是否與其他調(diào)用里的 objOid （對(duì)象標(biāo)識(shí)）一樣呢？thomas - 1998-01-11
描述
pg_lo_export 把聲明的大對(duì)象寫入到一個(gè) Unix 文件中去．
用法
pg_lo_export 必須在一對(duì) BEGIN/END 事務(wù)塊中調(diào)用．
--------------------------------------------------------------------------------
