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

2019-09-08 23:34:13

字體：大中小

來源：轉載

供稿：網友

第五十四章.　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("http://./n");
data.EndCopy();

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

上一篇：PostgreSQL7.0手冊-接口-55. pgtcl - TCL 綁定庫

下一篇：PostgreSQL7.0手冊-接口-53. libpq - C 庫