[ 永遠的UNIX > PostgreSQL7.0手冊-接口-54. libpq

[ 永遠的UNIX::UNIX技術資料的寶庫 ] GB | BIG5

首頁 > 數據庫 > 其它 > 正文

PostgreSQL7.0手冊-接口-54. libpq - C++ 綁定庫

編譯：何偉平 laser@zhengmai.com.cn (2001-04-21 23:22:02)

第五十四章.　libpq　-　C++　綁定庫
內容　
控制和初始化　
libpq++　類　
數據庫聯接函數　
查詢執行函數　
異步通知　
F與　COPY　命令Command　
libpq++　是　Postgres　的　C++　API　（接口）。libpq++　是一個　C++　類的集合，這些類允許客戶端程序與　Postgres　端服務器進行聯接。聯接有兩種形式：一個數據庫類和一個大對象類。　
數據庫類用操作數據庫，你可以向　Postgres　端服務器發送任何　SQL　查詢並檢索服務器的返回。　

大對象類用操作數據庫中的大對象。盡管一個大對象實例可以給Postgres　端發送正常的查詢，但通常只是用那些不返回任何數據的簡單查詢。一個大對象應該看作一個文件流。以它應該顯得更象　C++　文件流　cin，cout　和　cerr。　

本章基　libpq　C　庫的文檔。本章的末尾有三個短程序列出來作為　libpq++　編程的例子（盡管不是很好的編程例子）。在　src/libpq++/examples　裡有好幾個　libpq++　應用的例子，包括本章的三個例子的源碼。　

控制和初始化
環境變量
下面的環境變量可以在一個環境裡設置缺省值以避免在應用程序裡面把數據庫名放到硬代碼裡：　
　　
注意：請參考　libpq　-　C　庫　獲取一個可用聯接選項的完整列表。
下面的環境變量可以用選擇缺省的聯接參數值，這些值將被　PQconnectdb　或　PQsetdbLogin　使用－－如果調用代碼沒有直接聲明相應值的話．這些（環境變量）可以避免把麻煩的數據庫名強加入簡單的應用程序的硬代碼裡面。　
注意：libpq++　只使用環境變量或者　PQconnectdb　conninfo　風格的字串。
PGHOST　設置缺省的服務器名．如果聲明了一個非零長的字符串，將使用　TCP/IP　通訊．如果沒有主機名，libpq　將使用本地的Unix　域套接字．　
PGPORT　設置與　Postgres　端通訊的缺省端口號或本地　Unix　主控套接字的文件擴展（文件標識符）．　

PGDATABASE　設置缺省的　Postgres　數據庫名．　

PGUSER　設置用與數據庫聯接和用認証的用戶名．　

PGPASSWORD　如果端要求口令認証，設置使用的口令．　

PGREALM　設置與　Postgres　一起使用的　Kerberos　－－如果該域與本地域不同的話。如果設置了　PGREALM，Postgres　應用將試圖用這個域（realm）與服務器進行認証並且使用獨立的門票文件（ticket　files）以避免與本地的門票文件沖突．只有在端選擇了　Kerberos　認証時才使用這個環境變量．（譯注：門票文件是　Kerberos　認証協議中用交換密鑰的一個文件/服務器。）

PGOPTIONS　為　Postgres　設置附加的運行時選項．　
PGTTY　設置端調試信息顯示輸出的文件或者控制台（tty）．

下面的環境變量可以用為每個　Postgres　會話聲明用戶級別的缺省特性：　
PGDATESTYLE　設置缺省的日期/時間表現形式．　
PGTZ　設置缺省的時區．

下面的環境變量可以用為每個　Postgres　會話聲明缺省的內部特性：　
PGGEQO　為基因優化器設置缺省模式．
參閱　SET　SQL　命令獲取這些環境變量的正確值的信息．　

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

libpq++　類
聯接類：PgConnection
聯接類與數據庫進行實際的聯接，被所有的訪問類繼承。　
數據庫類：PgDatabase
數據庫類提供與一個服務器端已聯接的　C++　對象。要創建這樣的一個對象，我們首先需要用訪問端的環境。下面的構造器處理從　C++　程序裡面訪問端服務器的工作。

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

數據庫聯接函數
PgConnection　與一個端服務器建議一個新聯接。　
　　　　　　　　PgConnection::PgConnection(const　char　*conninfo)
盡管典型的是從一個訪問類裡面調用（此函數），與端服務器的聯接很有可能是通過創建一個　PgConnection　對象實現的。　
ConnectionBad　返回與一個端服務器的聯接是否成功。　

　　　　　　　　int　PgConnection::ConnectionBad()
如果聯接失敗返回　TRUE　（真）。　
Status　返回與一個端服務器的聯接的狀態。　

　　　　　　　　ConnStatusType　PgConnection::Status()
取決聯接的狀態，返回　CONNECTION_OK　或　CONNECTION_BAD。　
PgDatabase　與端服務器建立一個新聯接。　

　　　　　　　　PgDatabase(const　char　*conninfo)
在創建一個　PgDatabase　，我們在向對象發送查詢前要通過檢查來驗証與數據庫的聯接是否成功。這一點很容易通過使用　Status　或　ConnectionBad　方法檢索　PgDatabase　對象當前的狀態來實現。　
DBName　返回當前數據庫的名稱。　

　　　　　　　　const　char　*PgConnection::DBName()
Notifies　返回一個從端收到的未處理通知信息列表裡的下一條通知。　
　　　　　　　　PGnotify*　PgConnection::Notifies()
參閱　PQnotifies()　獲取細節。

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

查詢執行函數
Exec　向端服務器發送一個查詢。可能我們更願意使用下面兩個函數之一。　
　　　　　　　　ExecStatusType　PgConnection::Exec(const　char*　query)
返回查詢的結果。可能的狀態結果可以是下面的值：　
　　　
　PGRES_EMPTY_QUERY　　
PGRES_COMMAND_OK，如果查詢是一條命令　
PGRES_TUPLES_OK，如果查詢成功返回記錄　
PGRES_COPY_OUT　　
PGRES_COPY_IN　　
PGRES_BAD_RESPONSE，如收到一個未知的響應　
PGRES_NONFATAL_ERROR　　
PGRES_FATAL_ERROR　　

ExecCommandOk　向端服務器發送一條命令查詢。　

　　　　　　　　int　PgConnection::ExecCommandOk(const　char　*query)
如果命令查詢成功返回　TRUE。　
ExecTuplesOk　向端服務器發送一條命令查詢。　

　　　　　　　　int　PgConnection::ExecTuplesOk(const　char　*query)
如果命令查詢成功返回　TRUE。　
ErrorMessage　返回最一條錯誤信息文本。　

　　　　　　　　const　char　*PgConnection::ErrorMessage()
Tuples　返回查詢結果裡記錄（實例）的條數。　
　　　　　　　　int　PgDatabase::Tuples()
CmdTuples　返回在一次　INSERT，UPDATE　或　DELETE　涉及的行數．如果是其他命令，返回　-1．　
　　　　　　int　PgDatabase::CmdTuples()
Fields　返回查詢結果裡每條記錄的數據域（字段）數。　
　　　　　　　　int　PgDatabase::Fields()
FieldName　返回與指定域索引相聯的域（字段）名稱。域索引從　0　開始計數。　
　　　　　　　　const　char　*PgDatabase::FieldName(int　field_num)
FieldNum　返回與指定域（字段）名稱相聯的域索引。　
　　　　　　　　int　PgDatabase::FieldNum(const　char*　field_name)
如果給出的名稱無法與任何域匹配返回　-1。　
FieldType　返回與給出域索引相聯的域的類型。返回的整數是該類型的內部編碼。域索引從　0　開始計數。　

　　　　　　　　Oid　PgDatabase::FieldType(int　field_num)
FieldType　返回與給出域名稱相聯的域的類型。返回的整數是該類型的內部編碼。域索引從　0　開始計數。　
　　　　　　　　Oid　PgDatabase::FieldType(const　char*　field_name)
FieldSize　返回與給出域索引相聯的域的以字節計算的尺寸。域索引從　0　開始計數。　
　　　　　　　　short　PgDatabase::FieldSize(int　field_num)
返回在數據庫記錄裡面給該數據域分配的空間，換句話說就是該數據類型在服務器裡的二進制形式的大小（尺寸）．如果該數據域是可變尺寸，返回　-1．　
FieldSize　返回與給出域名稱相聯的域的以字節計算的尺寸。域索引從　0　開始計數。　

　　　　　　　　short　PgDatabase::FieldSize(const　char　*field_name)
返回在數據庫記錄裡面給該數據域分配的空間，換句話說就是該數據類型在服務器裡的二進制形式的大小（尺寸）．如果該數據域是可變尺寸，返回　-1．　
GetValue　返回一個　PGresult　裡面的一條記錄的單獨的一個數據域（字段）的值．記錄和數據域索引從　0　開始．　

　　　　　　　　const　char　*PgDatabase::GetValue(int　tup_num,　int　field_num)
對大多數查詢而言，GetValue　返回的值是一個表示字段值的空（NULL）結尾的　ASCII　字符串．但是如果　BinaryTuples()　為　TRUE，　GetValue　返回的值就是該類型在端服務器內部的二進制表現形式（但是不包括尺寸字－－如果數據域是變長的）．這樣，把數據轉換成對應的　C　類型就是程序員的責任了．　GetValue　返回的指針指向一個本身是　PGresult　結構的一部分的存儲區域．我們不能更改它，並且如果我們要在　PGresult　結構的生存期還要使用它的話，我們必須顯式的把該數值拷貝到其他存儲器中．BinaryTuples()　還沒有實現。　
GetValue　返回一個　PGresult　裡面的一條記錄的單獨的一個數據域（字段）的值．記錄和數據域索引從　0　開始．　

　　　　　　　　const　char　*PgDatabase::GetValue(int　tup_num,　const　char　*field_name)
對大多數查詢而言，GetValue　返回的值是一個表示字段值的空（NULL）結尾的　ASCII　字符串．但是如果　BinaryTuples()　為　TRUE，　GetValue　返回的值就是該類型在端服務器內部的二進制表現形式（但是不包括尺寸字－－如果數據域是變長的）．這樣，把數據轉換成對應的　C　類型就是程序員的責任了．　GetValue　返回的指針指向一個本身是　PGresult　結構的一部分的存儲區域．我們不能更改它，並且如果我們要在　PGresult　結構的生存期還要使用它的話，我們必須顯式的把該數值拷貝到其他存儲器中．BinaryTuples()　還沒有實現。　
GetLength　返回以字節計的數據域（字段）的長度．記錄和數據域索引從　0　開始．　

　　　　　　　　int　PgDatabase::GetLength(int　tup_num,　int　field_num)
這是某一特定數據值的實際數據長度，也就是由　GetValue　指向的對象的尺寸．注意，對　ASCII　代表的數值，這個尺寸與　PQfsize　報告的二進制尺寸無關．　
GetLength　返回以字節計的數據域（字段）的長度．記錄和數據域索引從　0　開始．　

　　　　　　　　int　PgDatabase::GetLength(int　tup_num,　const　char*　field_name)
這是某一特定數據值的實際數據長度，也就是由　GetValue　指向的對象的尺寸．注意，對　ASCII　代表的數值，這個尺寸與　PQfsize　報告的二進制尺寸無關．　
DisplayTuples　向指定輸出流打印所有記錄和（可選的）字段名。　

　　　　　　　　void　PgDatabase::DisplayTuples(FILE　*out　=　0,　int　fillAlign　=　1,　
　　　　　　　　const　char*　fieldSep　=　"|",int　printHeader　=　1,　int　quiet　=　0)
PrintTuples　向指定輸出流打印所有記錄和（可選的）字段名。　
　　　　　　　　void　PgDatabase::PrintTuples(FILE　*out　=　0,　int　printAttName　=　1,　
　　　　　　　　int　terseOutput　=　0,　int　width　=　0)
GetLine　
　　　　　　　　int　PgDatabase::GetLine(char*　string,　int　length)
PutLine　
　　　　　　　　void　PgDatabase::PutLine(const　char*　string)
OidStatus　
　　　　　　　　const　char　*PgDatabase::OidStatus()
EndCopy　
　　　　　　　　int　PgDatabase::EndCopy()

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

異步通知
Postgres　支持通過　LISTEN　和　NOTIFY　命令產生的異步通知．一個端用　LISTEN　命令注冊一個它感興趣的信號燈．所有正在監聽某一命名信號燈的端在該條件名的　NOTIFY　（通知）被另一個端執行都將被異步地通知．沒有附加的信息從通知發出者傳遞到通知接收者．因此，很典型地，任何實際的需要被傳遞的數據都是通過一個數據庫關系傳遞的．通常條件名是與相關聯的關系同名，但是並不是一定要與某個關系相關才行．　
注意：以前，本文檔把用異步通知的名稱與關系或者表相聯。但實際上在這兩個概念的實現上沒有任何直接的聯系，因而實際上命名信號燈不需要象以前定義的那樣與對應的關系相關聯。
libpq++　應用在與之相聯的端收到一個異步通知時將被通知。不過，從端到前端的通訊不是異步的。libpq++　應用必須輪詢端以便查找是否有待處理的信息。在一個查詢執行完畢，前端可以調用　PgDatabase::Notifies　來判斷目前是否有從端來的任何通知數據。PgDatabase::Notifies　從一個來自端的未處理通知列表裡返回一個通知。如果沒有來自端的待處理的通知，該函數返回　NULL。PgDatabase::Notifies　的表現想一個彈出棧。一旦從　PgDatabase::Notifies　返回了一個通知，該通知就被認為已處理並且被從通知列表裡刪除。　
PgDatabase::Notifies　從服務器裡檢索待處理通知。　
　　

　　　　　　　　PGnotify*　PgDatabase::Notifies()
第二個例子程序給出了一個使用異步通知的例子。

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

與　COPY　命令向關聯的函數
Postgres　裡的　copy　命令裡有用　libpq++　裡從網絡聯接讀出或者寫入的選項．因此，這些函數有必要直接訪問網絡聯接，以便應用可以充分利用這個功能．　
PgDatabase::GetLine　讀取一個以回車符（換行符）結尾的字符行中　length　字節的字符（由端服務器傳輸）到一個字符串緩沖區　string　裡．　
　　　　　　　　int　PgDatabase::GetLine(char*　string,　int　length)
類似　Unix　系統過程　fgets(3)，這個過程拷貝最多　length-1　個字符到字符串　string　裡．但是它會象　gets(3)　那樣把結尾的換行符轉換成一個空字符（null）。　
PgDatabase::GetLine　在碰到文件結束時返回　EOF，如果整行都被讀取了返回　0，如果緩沖區填滿了而還沒有遇到結束的換行符則返回　1．　

注意，應用程序必須檢查新行是否包含單個句點（"."），這表明端服務器已經完成了　copy　命令結果的發送。因此，如果應用預計接收超過　length-1　字符長的行，應用就必須保証仔細地檢查PgDatabase::GetLine　的返回值。　

PgDatabase::PutLine　發送一個空結尾的　string　到端服務器。　

　　　　　　　　void　PgDatabase::PutLine(char*　string)
應用必須顯式的發送一個句點字符（"."）告訴端它已經完成它的數據發送。　
　　
PgDatabase::EndCopy　與端同步。　

　　　　　　　　int　PgDatabase::EndCopy()
這個函數等到端完成　copy（才返回？）．你可以在用　PgDatabase::PutLine　向端發送完最一個字符串或者用　PgDatabase::GetLine　從端獲取最一行字符串調用它．我們必須調用這個函數，否則端可能會和前端“丟失同步”。在這個函數返回，端就已經準備好接收下一個查詢了。　
成功時返回　0，否則返回非零值。

一個例子：　
PgDatabase　data;
data.Exec("create　table　foo　(a　int4,　b　char(16),　d　float8)");
data.Exec("copy　foo　from　stdin");
data.PutLine("3\tHello　World\t4.5\n");
data.PutLine("4\tGoodbye　World\t7.11\n");
&...
data.PutLine("\\.\n");
data.EndCopy();

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

(http://www.fanqiang.com) 進入【UNIX論壇】

相關文章

===更多相關===

★ 樊強制作歡迎分享 ★