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

2019-09-08 23:34:13

字體：大中小

供稿：網(wǎng)友

第五十四章.　libpq　-　C++　綁定庫
內(nèi)容　
控制和初始化　
libpq++　類　
數(shù)據(jù)庫聯(lián)接函數(shù)　
查詢執(zhí)行函數(shù)　
異步通知　
F與　COPY　命令Command　
libpq++　是　Postgres　的　C++　API?。ń涌冢?。libpq++　是一個　C++　類的集合，這些類允許客戶端程序與　Postgres　后端服務(wù)器進行聯(lián)接。聯(lián)接有兩種形式：一個數(shù)據(jù)庫類和一個大對象類?！?
數(shù)據(jù)庫類用于操作數(shù)據(jù)庫，你可以向　Postgres　后端服務(wù)器發(fā)送任何　SQL　查詢并檢索服務(wù)器的返回?！?

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

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

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

PGDATABASE　設(shè)置缺省的　Postgres　數(shù)據(jù)庫名．　

PGUSER　設(shè)置用于與數(shù)據(jù)庫聯(lián)接和用于認(rèn)證的用戶名．　

PGPASSWORD　如果后端要求口令認(rèn)證，設(shè)置使用的口令．　

PGREALM　設(shè)置與　Postgres　一起使用的　Kerberos?。绻撚蚺c本地域不同的話。如果設(shè)置了　PGREALM，Postgres　應(yīng)用將試圖用這個域（realm）與服務(wù)器進行認(rèn)證并且使用獨立的門票文件（ticket　files）以避免與本地的門票文件沖突．只有在后端選擇了　Kerberos　認(rèn)證時才使用這個環(huán)境變量．（譯注：門票文件是　Kerberos　認(rèn)證協(xié)議中用于交換密鑰的一個文件/服務(wù)器。）

PGOPTIONS　為　Postgres　設(shè)置附加的運行時選項．　
PGTTY　設(shè)置后端調(diào)試信息顯示輸出的文件或者控制臺（tty）．

下面的環(huán)境變量可以用于為每個　Postgres　會話聲明用戶級別的缺省特性：　
PGDATESTYLE　設(shè)置缺省的日期/時間表現(xiàn)形式．　
PGTZ　設(shè)置缺省的時區(qū)．

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

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

libpq++　類
聯(lián)接類：PgConnection
聯(lián)接類與數(shù)據(jù)庫進行實際的聯(lián)接，被所有的訪問類繼承?！?
數(shù)據(jù)庫類：PgDatabase
數(shù)據(jù)庫類提供與一個服務(wù)器后端已聯(lián)接的　C++　對象。要創(chuàng)建這樣的一個對象，我們首先需要用于訪問后端的環(huán)境。下面的構(gòu)造器處理從　C++　程序里面訪問后端服務(wù)器的工作。

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

數(shù)據(jù)庫聯(lián)接函數(shù)
PgConnection　與一個后端服務(wù)器建議一個新聯(lián)接?！?
　　　　　　　　PgConnection::PgConnection(const　char　*conninfo)
盡管典型的是從一個訪問類里面調(diào)用（此函數(shù)），與后端服務(wù)器的聯(lián)接很有可能是通過創(chuàng)建一個　PgConnection　對象實現(xiàn)的?！?
ConnectionBad　返回與一個后端服務(wù)器的聯(lián)接是否成功?！?

　　　　　　　　int　PgConnection::ConnectionBad()
如果聯(lián)接失敗返回　TRUE　（真）?！?
Status　返回與一個后端服務(wù)器的聯(lián)接的狀態(tài)?！?

　　　　　　　　ConnStatusType　PgConnection::Status()
取決于聯(lián)接的狀態(tài)，返回　CONNECTION_OK　或　CONNECTION_BAD?！?
PgDatabase　與后端服務(wù)器建立一個新聯(lián)接?！?

　　　　　　　　PgDatabase(const　char　*conninfo)
在創(chuàng)建一個　PgDatabase　后，我們在向?qū)ο蟀l(fā)送查詢前要通過檢查來驗證與數(shù)據(jù)庫的聯(lián)接是否成功。這一點很容易通過使用　Status　或　ConnectionBad　方法檢索　PgDatabase　對象當(dāng)前的狀態(tài)來實現(xiàn)?！?
DBName　返回當(dāng)前數(shù)據(jù)庫的名稱。　

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

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

查詢執(zhí)行函數(shù)
Exec　向后端服務(wù)器發(fā)送一個查詢?？赡芪覀兏敢馐褂孟旅鎯蓚€函數(shù)之一?！?
　　　　　　　　ExecStatusType　PgConnection::Exec(const　char*　query)
返回查詢的結(jié)果。可能的狀態(tài)結(jié)果可以是下面的值：　
　　　
　PGRES_EMPTY_QUERY　　
PGRES_COMMAND_OK，如果查詢是一條命令　
PGRES_TUPLES_OK，如果查詢成功返回記錄　
PGRES_COPY_OUT　　
PGRES_COPY_IN　　
PGRES_BAD_RESPONSE，如收到一個未知的響應(yīng)　
PGRES_NONFATAL_ERROR　　
PGRES_FATAL_ERROR　　

ExecCommandOk　向后端服務(wù)器發(fā)送一條命令查詢。　

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

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

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

　　　　　　　　Oid　PgDatabase::FieldType(int　field_num)
FieldType　返回與給出域名稱相聯(lián)的域的類型。返回的整數(shù)是該類型的內(nèi)部編碼。域索引從　0　開始計數(shù)?！?
　　　　　　　　Oid　PgDatabase::FieldType(const　char*　field_name)
FieldSize　返回與給出域索引相聯(lián)的域的以字節(jié)計算的尺寸。域索引從　0　開始計數(shù)?！?
　　　　　　　　short　PgDatabase::FieldSize(int　field_num)
返回在數(shù)據(jù)庫記錄里面給該數(shù)據(jù)域分配的空間，換句話說就是該數(shù)據(jù)類型在服務(wù)器里的二進制形式的大?。ǔ叽纾绻摂?shù)據(jù)域是可變尺寸，返回　-1．　
FieldSize　返回與給出域名稱相聯(lián)的域的以字節(jié)計算的尺寸。域索引從　0　開始計數(shù)?！?

　　　　　　　　short　PgDatabase::FieldSize(const　char　*field_name)
返回在數(shù)據(jù)庫記錄里面給該數(shù)據(jù)域分配的空間，換句話說就是該數(shù)據(jù)類型在服務(wù)器里的二進制形式的大?。ǔ叽纾绻摂?shù)據(jù)域是可變尺寸，返回　-1．　
GetValue　返回一個　PGresult　里面的一條記錄的單獨的一個數(shù)據(jù)域（字段）的值．記錄和數(shù)據(jù)域索引從　0　開始．　

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

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

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

　　　　　　　　int　PgDatabase::GetLength(int　tup_num,　const　char*　field_name)
這是某一特定數(shù)據(jù)值的實際數(shù)據(jù)長度，也就是由　GetValue　指向的對象的尺寸．注意，對于　ASCII　代表的數(shù)值，這個尺寸與　PQfsize　報告的二進制尺寸無關(guān)．　
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　命令產(chǎn)生的異步通知．一個后端用　LISTEN　命令注冊一個它感興趣的信號燈．所有正在監(jiān)聽某一命名信號燈的后端在該條件名的　NOTIFY　（通知）被另一個后端執(zhí)行后都將被異步地通知．沒有附加的信息從通知發(fā)出者傳遞到通知接收者．因此，很典型地，任何實際的需要被傳遞的數(shù)據(jù)都是通過一個數(shù)據(jù)庫關(guān)系傳遞的．通常條件名是與相關(guān)聯(lián)的關(guān)系同名，但是并不是一定要與某個關(guān)系相關(guān)才行．　
注意：以前，本文檔把用于異步通知的名稱與關(guān)系或者表相聯(lián)。但實際上在這兩個概念的實現(xiàn)上沒有任何直接的聯(lián)系，因而實際上命名信號燈不需要象以前定義的那樣與對應(yīng)的關(guān)系相關(guān)聯(lián)。
libpq++　應(yīng)用在與之相聯(lián)的后端收到一個異步通知時將被通知。不過，從后端到前端的通訊不是異步的。libpq++　應(yīng)用必須輪詢后端以便查找是否有待處理的信息。在一個查詢執(zhí)行完畢后，前端可以調(diào)用　PgDatabase::Notifies　來判斷目前是否有從后端來的任何通知數(shù)據(jù)。PgDatabase::Notifies　從一個來自后端的未處理通知列表里返回一個通知。如果沒有來自后端的待處理的通知，該函數(shù)返回　NULL。PgDatabase::Notifies　的表現(xiàn)想一個彈出棧。一旦從　PgDatabase::Notifies　返回了一個通知，該通知就被認(rèn)為已處理并且被從通知列表里刪除?！?
PgDatabase::Notifies　從服務(wù)器里檢索待處理通知?！?
　　

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

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

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

注意，應(yīng)用程序必須檢查新行是否包含單個句點（"."），這表明后端服務(wù)器已經(jīng)完成了　copy　命令結(jié)果的發(fā)送。因此，如果應(yīng)用預(yù)計接收超過　length-1　字符長的行，應(yīng)用就必須保證仔細(xì)地檢查PgDatabase::GetLine　的返回值?！?

PgDatabase::PutLine　發(fā)送一個空結(jié)尾的　string　到后端服務(wù)器。　

　　　　　　　　void　PgDatabase::PutLine(char*　string)
應(yīng)用必須顯式的發(fā)送一個句點字符（"."）告訴后端它已經(jīng)完成它的數(shù)據(jù)發(fā)送?！?
　　
PgDatabase::EndCopy　與后端同步?！?

　　　　　　　　int　PgDatabase::EndCopy()
這個函數(shù)等到后端完成　copy（才返回？）．你可以在用　PgDatabase::PutLine　向后端發(fā)送完最后一個字符串后或者用　PgDatabase::GetLine　從后端獲取最后一行字符串后調(diào)用它．我們必須調(diào)用這個函數(shù)，否則后端可能會和前端“丟失同步”。在這個函數(shù)返回后，后端就已經(jīng)準(zhǔn)備好接收下一個查詢了。　
成功時返回　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 庫