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?。ㄆ瘘c）可以是 "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?。▽ο髽俗R）一樣呢？ 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?。▽ο髽俗R）一樣呢？thomas - 1998-01-11
描述
pg_lo_export 把聲明的大對象寫入到一個 Unix 文件中去．
用法
pg_lo_export 必須在一對 BEGIN/END 事務塊中調用．
--------------------------------------------------------------------------------
