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