?
本文檔使用
php中文網(wǎng)手冊 發(fā)布
31.3. 命令執(zhí)行函數(shù)
一旦與數(shù)據(jù)庫服務(wù)器的連接成功建立，便可用這里描述的函數(shù)執(zhí)行SQL查詢和命令。
31.3.1. 主函數(shù)
-
PQexec -
給服務(wù)器提交一條命令并且等待結(jié)果。
PGresult *PQexec(PGconn *conn，const char *command);
返回一個PGresult指針或者也可能是一個NULL指針。通常返回一個非空的指針， 除非沒有內(nèi)存或發(fā)生了象不能把命令發(fā)送到服務(wù)器這樣的嚴(yán)重錯誤。如果返回的是NULL， 它應(yīng)該被當(dāng)作PGRES_FATAL_ERROR結(jié)果處理。用
PQerrorMessage獲取有關(guān)錯誤的更多信息。
我們可以在命令行字串里包含多個SQL命令（用分號分隔）。在一次PQexec調(diào)用中發(fā)送的多個查詢是在一
個事務(wù)里處理的，除非在查詢字串里有明確的BEGIN/COMMIT命令用于把整個字串分隔成多個事務(wù)。
請注意這樣返回的PGresult結(jié)構(gòu)只描述字串里執(zhí)行的最后一條命令的結(jié)果。如果有一個命令失敗，
那么字串處理的過程就會停止并且返回的PGresult會描述錯誤條件。
-
PQexecParams -
向服務(wù)器提交一條命令并且等待結(jié)果，還有額外的傳遞與SQL命令文本獨立的參數(shù)的能力。
PGresult *PQexecParams(PGconn *conn， const char *command， int nParams， const Oid *paramTypes， const char * const *paramValues， const int *paramLengths， const int *paramFormats， int resultFormat);PQexecParams類似PQexec，但是提供了額外的功能：參數(shù)值可以獨立于命令串進(jìn)行聲明， 并且可以要求查詢結(jié)果的格式是文本或者二進(jìn)制格式。PQexecParams只是在協(xié)議3.0以及以后的版本中支持； 在使用2.0的版本的時候會失敗。函數(shù)的參數(shù)是：
- conn
連接對象通過發(fā)送命令。
- command
要執(zhí)行的SQL命令字符串。如果使用參數(shù)， 他們被稱為命令字符串作為$1， $2等等。
- nParams
提供的參數(shù)數(shù)目;它是paramTypes[]，paramValues[]， paramLengths[]，a和paramFormats[].數(shù)組的長度 （ 數(shù)組指針可以是NULL，當(dāng)nParams為零。）
- paramTypes[]
通過OID，將聲明數(shù)據(jù)類型指定到參數(shù)標(biāo)記。如果paramTypes是NULL， 或數(shù)組中任何的特定參數(shù)是0，服務(wù)器為參數(shù)標(biāo)記推斷數(shù)據(jù)類型，采用的方式與一個未定義類型 的文本字符串相同。
- paramValues[]
聲明參數(shù)的實際值。在這個數(shù)組中的一個空指針表示相應(yīng)的參數(shù)是空； 要么指針指向一個以零結(jié)尾的文本字符串或以服務(wù)器希望的方式存在的二進(jìn)制數(shù)據(jù)。
- paramLengths[]
為二進(jìn)制格式的參數(shù)聲明實際數(shù)據(jù)長度，該設(shè)置忽略空參數(shù)或文本格式的參數(shù)。 如果沒有二進(jìn)制參數(shù)，那么數(shù)組指針可以為空。
- paramFormats[]
-
聲明參數(shù)為一個文本（為相應(yīng)參數(shù)在數(shù)組條目中放置一個0）還是一個二進(jìn)制格式 （為相應(yīng)參數(shù)在一個數(shù)組條目中放置一個1）。 如果數(shù)組指針是空，那么所有參數(shù)被看做是文本字符串。
以二進(jìn)制格式傳遞的值需要能夠被后臺識別的內(nèi)部表示。 例如，整數(shù)必須以網(wǎng)絡(luò)字節(jié)順序來傳遞； 傳遞numeric時需要服務(wù)器存儲格式的識別，如在src/backend/utils/adt/numeric.c::numeric_send()和 src/backend/utils/adt/numeric.c::numeric_recv()中那樣。
- resultFormat
聲明0用于以文本格式獲得結(jié)果，或1用于以二進(jìn)制格式獲得結(jié)果。 （目前沒有規(guī)定以不同的格式來獲取不同的結(jié)果列，即使底層協(xié)議中可能實現(xiàn)）。
PQexecParams比PQexec主要優(yōu)勢是
參數(shù)值可以分開字符串命令，從而避免了繁瑣和容易出錯的需要
引用和逃逸。
和PQexec不同的是，PQexecParams在一個給出的字串里最多允
許一個 SQL 命令。（里面可以有分號，但是不得超過一個非空的命令。）這是下層的協(xié)議的一個限制，
但是也有些額外的好處，比如可以有另外一層防止SQL攻擊的層次。
Tip: 提示: 通過OID聲明參數(shù)類型是非常煩瑣的，尤其是你不希望在你的程序里寫死特定的 OID 值的時候。 不過，你可以避免這么做，即使在服務(wù)器自己無法判斷參數(shù)類型，或者是選擇了一種與你預(yù)期不同的 參數(shù)類型的時候也一樣。在 SQL 命令文本里，給參數(shù)負(fù)號附加一個明確的類型轉(zhuǎn)換， 顯示你準(zhǔn)備發(fā)送的數(shù)據(jù)類型。比如：
SELECT * FROM mytable WHERE x = $1::bigint;這樣強制參數(shù)$1當(dāng)作bigint看待，即使缺省情況下它會被賦予和x。一樣的類型。 在以二進(jìn)制格式發(fā)送參數(shù)值的時候，我們強烈建議通過這種方法或者是聲明數(shù)字類型OID的方法強制類型判斷， 因為二進(jìn)制格式比文本格式少一些冗余，因此服務(wù)器就會少一些機會捕捉類型的錯誤匹配。
-
PQprepare -
用給定的參數(shù)提交請求，創(chuàng)建一個準(zhǔn)備好的語句，然后等待結(jié)束。
PGresult *PQprepare(PGconn *conn， const char *stmtName， const char *query， int nParams， const Oid *paramTypes);PQprepare創(chuàng)建一個為后面PQexecPrepared執(zhí)行用的準(zhǔn)備好語句。這個特性允許那 些重復(fù)使用的語句只分析和規(guī)劃一次，而不是每次執(zhí)行都分析規(guī)劃。這個語句必須在當(dāng)前 會話的前面已經(jīng)準(zhǔn)備好。只是在協(xié)議3.0和以后的連接里支持PQprepare； 在使用2.0協(xié)議的時候，它會失敗。這個函數(shù)從query字串里創(chuàng)建一個叫stmtName的準(zhǔn)備好的語句，query 必須只包含 一個 SQL 命令。stmtName可以是""，這樣就創(chuàng)建一個無名的語句，這種情況下，任何前面 存在的無名語句都會自動被代替；否則，如果語句名已經(jīng)在當(dāng)前會話里定義，那就是一個錯誤。 如果使用了參數(shù)，那么在查詢里它們引用成$1，$2等等。nParams是參數(shù)的個數(shù)，參數(shù)的類型在 數(shù)組paramTypes[]里事先聲明好了。（如果 nParams 是零，那么這個數(shù)組指針可以是NULL。） paramTypes[]. 用 OID 的方式聲明與參數(shù)符號關(guān)聯(lián)的數(shù)據(jù)類型。如果paramTypes為NULL，或者數(shù)組中 某個特定元素是零，那么服務(wù)器將用處理無類型文本同樣的方法給這個參數(shù)符號賦予數(shù)據(jù)類型。還有， 查詢可以使用比 nParams 數(shù)值更大的參數(shù)符號編號；這些參數(shù)的數(shù)據(jù)類型也是用一樣的方法推導(dǎo)的。 （見
PQdescribePrepared作為一種手段，以找出> 什么樣的數(shù)據(jù)類型推斷。）和
PQexec似，結(jié)果通常是一個PGresult對象，其內(nèi)容表明服務(wù)器端是成功還是失敗。 空的結(jié)果表示內(nèi)存耗盡或者完全不能發(fā)送命令。使用PQerrorMessage獲取有關(guān)這類錯誤的更多信息。
用于PQexecPrepared的準(zhǔn)備好語句也可以通過執(zhí)行 SQLPREPARE語句來創(chuàng)建。
（不過 PQprepare 更靈活，因為它不要求預(yù)先聲明參數(shù)類型。）還有，盡管沒有libpq函數(shù)
可以刪除一個準(zhǔn)備好語句，SQLDEALLOCATE語句卻可以刪除。
-
PQexecPrepared -
發(fā)送一個請求，執(zhí)行一個帶有給出參數(shù)的準(zhǔn)備好的語句，并且等待結(jié)果。
PGresult *PQexecPrepared(PGconn *conn， const char *stmtName， int nParams， const char * const *paramValues， const int *paramLengths， const int *paramFormats， int resultFormat);PQexecPrepared和PQexecParams類似，但是要執(zhí)行的命令是通過命名一個前面準(zhǔn)備好的語句聲明的， 而不是給出一個查詢字串。這個特性允許那些要重復(fù)使用的命令只進(jìn)行一次分析和規(guī)劃， 而不是每次執(zhí)行都來一遍。PQexecPrepared只在協(xié)議 3.0 和以后的版本里支持； 在使用 2.0 版本的協(xié)議的時候，它們會失敗。參數(shù)和
PQexecParams一樣，只是給出的是一個準(zhǔn)備好語句的名字，而不是一個查詢字串， 并且沒有paramTypes[]參數(shù)（沒必要，因為準(zhǔn)備好語句的參數(shù)類型是在創(chuàng)建的時候確定的）。 -
PQdescribePrepared -
提交請求以獲取有關(guān)指定的信息 準(zhǔn)備的聲明，并等待完成。
PGresult *PQdescribePrepared(PGconn *conn，const char *stmtName);
PQdescribePrepared允許應(yīng)用程序獲取 有關(guān)先前準(zhǔn)備的語句。PQdescribePrepared只在協(xié)議 3.0 和以后的版本里支持； 在使用 2.0 版本的協(xié)議的時候，它們會失敗。stmtName可以是""或NULL以指向未命名聲明， 要么必須與現(xiàn)有的預(yù)處理聲明同名，成功時，會返回一個帶有PGRES_COMMAND_OK的PGresult。 可以在這個PGresult中使用
PQnparams和PQparamtype函數(shù)以 獲得預(yù)處理聲明中的參數(shù)信息，同時PQnfields，PQfname，PQftype三個函數(shù)提供聲明的結(jié)果列的信息。 -
PQdescribePortal -
提交請求以獲取有關(guān)指定的信息 門戶網(wǎng)站，并等待完成......
PGresult *PQdescribePortal(PGconn *conn，const char *portalName);
PQdescribePortal允許應(yīng)用程序獲得關(guān)于之前創(chuàng)建的端口的信息。 （libpq不提供與端口的直接連接，但可以使用這個函數(shù)來檢查 DECLARE CURSOR命令創(chuàng)建的游標(biāo)的屬性）。PQdescribePortal只支持3.0及其之后的連接協(xié)議。portalName可以是""或NULL以指向未命名端口， 要么必須與現(xiàn)有的端口同名，成功時，會返回一個帶有PGRES_COMMAND_OK的PGresult。 可以在這個PGresult中使用
PQnfields，PQfname和PQftype函數(shù)以 獲得端口的結(jié)果列的信息。
PGresult結(jié)構(gòu)封裝了服務(wù)器返回的結(jié)果。 libpq應(yīng)該小心維護(hù)PGresult的抽象。 使用下面的訪問函數(shù)獲取PGresult的內(nèi)容。 避免直接引用PGresult里面的字段 ，因為它們在未來版本里可能會被修改。
-
PQresultStatus -
返回命令的結(jié)果狀態(tài)。
ExecStatusType PQresultStatus(const PGresult *res);
PQresultStatus可以返回下面數(shù)值之一：- PGRES_EMPTY_QUERY
發(fā)送給服務(wù)器的字串是空的
- PGRES_COMMAND_OK
成功完成一個不返回數(shù)據(jù)的命令
- PGRES_TUPLES_OK
成功執(zhí)行一個返回數(shù)據(jù)的查詢查詢（比如SELECT或者SHOW）。
- PGRES_COPY_OUT
（從服務(wù)器）Copy Out （拷貝出）數(shù)據(jù)傳輸開始
- PGRES_COPY_IN
Copy In（拷貝入）（到服務(wù)器）數(shù)據(jù)傳輸開始
- PGRES_BAD_RESPONSE
服務(wù)器的響應(yīng)無法理解
- PGRES_NONFATAL_ERROR
發(fā)生了一個非致命錯誤（通知或者警告）
- PGRES_FATAL_ERROR
發(fā)生了一個致命錯誤
如果結(jié)果狀態(tài)是PGRES_TUPLES_OK，那么可以用下面的函數(shù)從查詢的返回中抽取元組信息。 注意一個碰巧檢索了零條元組的SELECT仍然顯示PGRES_TUPLES_OKPGRES_COMMAND_OK 用于不返回元組的命令（INSERT，UPDATE等）。返回PGRES_EMPTY_QUERY 的響應(yīng)通常意味著暴露了客戶端軟件里面的臭蟲。
狀態(tài)為PGRES_NONFATAL_ERROR的結(jié)果永遠(yuǎn)不會直接由
PQexec或者其它查詢執(zhí)行函數(shù)返回； 這類的結(jié)果會被傳遞給通知處理器（參閱Section 31.11）。 -
PQresStatus -
把P
PQresultStatus返回的枚舉類型轉(zhuǎn)換成一個描述狀態(tài)碼的字符串常量。 調(diào)用者不應(yīng)該釋放結(jié)果。char *PQresStatus(ExecStatusType status);
-
PQresultErrorMessage -
返回與查詢關(guān)聯(lián)的錯誤信息，或在沒有錯誤時返回一個空字符串。
char *PQresultErrorMessage(const PGresult *res);
如果有錯誤，那么返回的字串將包括一個結(jié)尾的新行。調(diào)用者不應(yīng)該直接釋放結(jié)果。 在相關(guān)的PGresult句柄傳遞給
PQclear之后，它會自動釋放。緊跟在一個
PQexec或PQgetResult調(diào)用后面，PQerrorMessage（對連接）將返回 與PQresultErrorMessage(對結(jié)果)一樣的字符串。不過，一個PGresult將保有其錯誤信息直到被刪除， 而連結(jié)的錯誤信息將在后續(xù)的操作完成時被改變。當(dāng)你想知道與某個PGresult相關(guān)聯(lián)的狀態(tài)時 用PQresultErrorMessage；當(dāng)你想知道與連接的最近一個操作相關(guān)聯(lián)的狀態(tài)時用PQerrorMessage。 PQresultErrorField-
返回一個獨立的錯誤報告字段。
char *PQresultErrorField(const PGresult *res，int fieldcode);
fieldcode是一個錯誤字段標(biāo)識符；參閱下面列出的符號。如果PGresult不是錯誤或者警告結(jié) 果或者不包括指定的字段，那么返回NULL。字段值通常將不包括結(jié)尾的新行。調(diào)用者不應(yīng)該直接釋放結(jié)果。 在相關(guān)聯(lián)的PGresult句柄傳遞給
PQclear之后，它將被自動釋放。The following field codes are available: 下列代碼是可用的：
- PG_DIAG_SEVERITY
嚴(yán)重程度，這個字段的內(nèi)容是ERROR，FATAL或者PANIC（在錯誤信息里）， 或者WARNING，NOTICE，DEBUG， INFO或LOG（在注意信息里）， 或者是這些東西的一個本地化翻譯。總是出現(xiàn)。 PG_DIAG_SQLSTATE
- PG_DIAG_SQLSTATE
這個錯誤的 SQLSTATE 代碼。SQLSTATE 代碼表示所發(fā)生的錯誤的類型； 可以由前端應(yīng)用用于對特定的數(shù)據(jù)庫錯誤執(zhí)行特定的操作（比如錯誤處理）。關(guān)于可能 的 SQLSTATE 代碼的列表，請參閱Appendix A。這個字段是不能區(qū)域化的，并且總是出現(xiàn)。
- PG_DIAG_MESSAGE_PRIMARY
主要的人類可讀錯誤的信息（通常一條線）。 Always present.
- PG_DIAG_MESSAGE_DETAIL
細(xì)節(jié)：一個可選的從屬錯誤信息，里面有更多有關(guān)該問題的細(xì)節(jié)?？赡苡卸嘈?。
- PG_DIAG_MESSAGE_HINT
提示：一個可選的有關(guān)如何處理該問題的建議。它和細(xì)節(jié)的區(qū)別是它提供了建議 （可能不太合適）而不光是事實?？赡苡泻脦仔?。
- PG_DIAG_STATEMENT_POSITION
一個包含十進(jìn)制整數(shù)的字串，當(dāng)作一個錯誤游標(biāo)使用，指出最初的語句串出錯的地方的下標(biāo)。 第一個字符的索引是 1，并且這個位置是用字符計，而不是用字節(jié)計。
- PG_DIAG_INTERNAL_POSITION
這個和PG_DIAG_STATEMENT_POSITION字段定義是一樣的，區(qū)別是它用于內(nèi)部生成的命令的下標(biāo)指示， 而不是客戶端提交的命令。如果出現(xiàn)了這個字段，那么PG_DIAG_INTERNAL_QUERY字段也總是出現(xiàn)。
- PG_DIAG_INTERNAL_QUERY
一個失敗的內(nèi)部生成的命令的文本。比如，這個可能是一個 PL/pgSQL 函數(shù)發(fā)出的 SQL 查詢。
- PG_DIAG_CONTEXT
一個指示器，表明錯誤發(fā)生的環(huán)境。目前這個包括活躍的過程語言函數(shù)和內(nèi)部生成的查詢的調(diào)用堆棧。 堆棧是每行一條，最近的在上面。
- PG_DIAG_SOURCE_FILE
所報告的錯誤的源代碼位置的所在文件。
- PG_DIAG_SOURCE_LINE
報告的這個錯誤所在的源代碼位置的行號。
- PG_DIAG_SOURCE_FUNCTION
報告這個錯誤的源代碼函數(shù)的名字。
按照自身的要求格式化顯示信息是客戶端的責(zé)任；特別是根據(jù)需要對長行進(jìn)行折行。在錯誤信息字段里出現(xiàn)的新行字符應(yīng)該當(dāng)作分段符號，而不是換行。
libpq生成的錯誤將會有嚴(yán)重性和主信息，但是通常沒有其它字段。3.0 協(xié)議之前返回的錯誤 將包含嚴(yán)重性和主信息，有時候還有詳細(xì)信息，但是沒有其它字段。
請注意這些錯誤字段只能從PGresult對象里獲得， 而不是PGconn對象；沒有
PQerrorField函數(shù)。 PQclear-
PQclear釋放于PGresult相關(guān)聯(lián)的存儲空間。 任何不再需要的查詢結(jié)果在不需要的時候都應(yīng)該用PQclear釋放掉。void PQclear(PGresult *res);
只要你需要，你可以保留PGresult對象任意長的時間； 當(dāng)你提交新的查詢時它并不消失， 甚至你斷開連接后也是這樣。要刪除它，你必須調(diào)用
PQclear。 不這么做將導(dǎo)致你的應(yīng)用中的內(nèi)存泄漏。
31.3.2. Retrieving Query Result Information檢索查詢結(jié)果信息
這些函數(shù)用于從一個代表著成功查詢結(jié)果（也就是說，狀態(tài)為PGRES_TUPLES_OK的查詢）的PGresult對象。 對于其它狀態(tài)值的對象，他們的行為會好像他們有零行和零列一樣。
-
PQntuples -
返回查詢結(jié)果里的行（元組）個數(shù)。因為在32位操作系統(tǒng) 它返回一個整數(shù)的結(jié)果，大型結(jié)果集可能溢出返回值。
int PQntuples(const PGresult *res);
-
PQnfields -
返回查詢結(jié)果里數(shù)據(jù)行的數(shù)據(jù)域（字段）的個數(shù)。
int PQnfields(const PGresult *res);
-
PQfname -
返回與給出的數(shù)據(jù)域編號相關(guān)聯(lián)的數(shù)據(jù)域（字段）的名稱。數(shù)據(jù)域編號從 0 開始。 調(diào)用者不應(yīng)該直接釋放結(jié)果。在相關(guān)聯(lián)的PGresult 句柄傳遞給
PQclear之后，結(jié)果會被自動釋放。char *PQfname(const PGresult *res， int column_number);如果字段編號超出范圍，那么返回NULL
-
PQfnumber -
返回與給出的數(shù)據(jù)域名稱相關(guān)聯(lián)的數(shù)據(jù)域（字段）的編號。
int PQfnumber(const PGresult *res， const char *column_name);如果給出的名字不匹配任何字段，返回 -1。
給出的名字是當(dāng)作 SQL 命令里的一個標(biāo)識符看待的，也就是說，如果沒有加雙引號， 那么會轉(zhuǎn)換為小寫。比如，如果我們有一個從 SQL 命令里生成的查詢結(jié)果
SELECT 1 AS FOO，2 AS "BAR";
那么我們會有下面的結(jié)果：
PQfname(res，0) foo PQfname(res，1) BAR PQfnumber(res，"FOO") 0 PQfnumber(res，"foo") 0 PQfnumber(res，"BAR") -1 PQfnumber(res，"\"BAR\"")1
-
PQftable -
返回我們抓取的字段所在的表的 OID。字段編號從 0 開始。
Oid PQftable(const PGresult *res， int column_number);如果字段編號超出了范圍，或者聲明的字段不是一個指向某個表的字段的簡單引用， 或者使用了 3.0 版本之前的協(xié)議，那么就會返回InvalidOid。 你可以查詢系統(tǒng)表pg_class來判斷究竟引用了哪個表。
在你包含libpq頭文件的時候， 就會定義類型Oid和常量InvalidOid。 他們都是相同的整數(shù)類型。
-
PQftablecol -
返回組成聲明的查詢結(jié)果字段的字段號（在它的表內(nèi)部）。查詢結(jié)果字段編號從 0 開始，但是表字段編號不會是 0。
int PQftablecol(const PGresult *res， int column_number);如果字段編號超出范圍，或者聲明的字段并不是一個表字段的簡單引用，或者使用的是 3.0 之前的協(xié)議，那么返回零。
-
PQfformat -
返回說明給出字段的格式的格式代碼。字段編號從 0 開始。
int PQfformat(const PGresult *res， int column_number);格式碼為 0 表示文本數(shù)據(jù)，而格式碼是一表示二進(jìn)制數(shù)據(jù)。 （其它編碼保留給將來定義。）
-
PQftype -
返回與給定數(shù)據(jù)域編號關(guān)聯(lián)的數(shù)據(jù)域類型。 返回的整數(shù)是一個該類型的內(nèi)部 OID 號。數(shù)據(jù)域編號從0 開始。
Oid PQftype(const PGresult *res， int column_number);你可以查詢系統(tǒng)表pg_type以獲取各種數(shù)據(jù)類型的名稱和屬性。 內(nèi)建的數(shù)據(jù)類型的 OID 在源碼樹的src/include/catalog/pg_type.h文件里定義。
-
PQfmod -
返回與給定字段編號相關(guān)聯(lián)的類型修飾詞。 字段編號從 0 開始。
int PQfmod(const PGresult *res， int column_number);類型修飾符的值是類型相關(guān)的；他們通常包括精度或者尺寸限制。數(shù)值 -1 用 于表示"沒有可用信息"。大多數(shù)數(shù)據(jù)類型不用修飾詞，這種情況下該值總是 -1。
-
PQfsize -
返回與給定字段編號關(guān)聯(lián)的字段以字節(jié)計的大小。 字段編號從0 開始。
int PQfsize(const PGresult *res， int column_number);PQfsize返回在數(shù)據(jù)庫行里面給該數(shù)據(jù)字段分配的空間，換句話說就是該數(shù)據(jù)類型在 服務(wù)器里的二進(jìn)制形式的大小（尺寸）。（因此，這個對客戶端沒有什么用。） 如果該數(shù)據(jù)域是可變尺寸，返回 -1。 -
PQbinaryTuples -
如果PGresult包含二進(jìn)制元組數(shù)據(jù)時返回 1， 如果包含 ASCII 數(shù)據(jù)返回 0。
int PQbinaryTuples(const PGresult *res);
這個函數(shù)已經(jīng)廢棄了（除了還用于與COPY連接之外），因為我們可能在 一個PGresult的某些字段里包含文本數(shù)據(jù)，而另外一些字段包含二進(jìn)制數(shù)據(jù) 。更好的是使用
PQfformat。PQbinaryTuples只有在結(jié)果中的所有字段 都是二進(jìn)制（格式 1）的時候才返回 1。 -
PQgetvalue -
返回一個PGresult里面一行的單獨的一個字段的值。行和字段編號從 0 開始。 調(diào)用者不應(yīng)該直接釋放結(jié)果。在把PGresult句柄傳遞給
PQclear之后， 結(jié)果會被自動釋放。char *PQgetvalue(const PGresult *res， int row_number， int column_number);對于文本格式的數(shù)據(jù)，
PQgetvalue返回的值是一個表示字段值的空（NULL） 結(jié)尾的字符串。對于二進(jìn)制格式，返回的值就是由該數(shù)據(jù)類型的typsend和typreceive決定的二進(jìn)制表現(xiàn)形式。（在這種情況下，數(shù)值實際上也跟著一個字節(jié)零， 但是通常這個字節(jié)沒什么用處，因為數(shù)值本身很可能包含內(nèi)嵌的空。）如果字段值是空，則返回一個空字串。參閱
PQgetisnull來區(qū)別空值和空字串值。PQgetvalue返回的指針指向一個本身是PGresult結(jié)構(gòu)的一部分的存儲區(qū)域。我們不能更改它， 并且如果我們要在PGresult結(jié)構(gòu)的生存期后還要使用它的話， 我們必須明確地把該數(shù)值拷貝到其他存儲器中。 -
PQgetisnull -
測試一個字段是否為空（NULL）。行和字段編號從 0 開始。
int PQgetisnull(const PGresult *res， int row_number， int column_number);如果該域包含 NULL，函數(shù)返回 1，如果包含非空（non-null ）值，返回 0。 （注意，對一個 NULL 數(shù)據(jù)域，
PQgetvalue將返回一個空字符串，不是一個空指針。） -
PQgetlength -
返回以字節(jié)計的字段的長度。行和字段編號從 0 開始。
int PQgetlength(const PGresult *res， int row_number， int column_number);這是某一特定數(shù)據(jù)值的實際數(shù)據(jù)長度。行和字段編號從 0 開始。 這是特定數(shù)值的實際數(shù)據(jù)長度，也就是說，
PQgetvalue指向的對象的大小。 對于文本數(shù)據(jù)格式，它和strlen()相同。對于二進(jìn)制格式，這是潛在的信息。 請注意我們不應(yīng)該依靠PQfsize獲取實際數(shù)據(jù)長度。 -
PQnparams -
返回一份聲明中的參數(shù)的數(shù)目。
int PQnparams(const PGresult *res);
檢查的結(jié)果時，這個功能是非常有用的
PQdescribePrepared。對于其他類型的查詢 將返回零。 -
PQparamtype -
返回指示語句中的參數(shù)的數(shù)據(jù)類型。 參數(shù)編號從0開始。
Oid PQparamtype(const PGresult *res，int param_number);
檢查的結(jié)果時，這個功能是非常有用的
PQdescribePrepared。對于其他類型的查詢 將返回零。 -
PQprint -
向指定的輸出流打印所有的行和（可選的）字段名稱。
void PQprint(FILE *fout，/* output stream */ const PGresult *res， const PQprintOpt *po); typedef struct { pqbool header; /* 打印輸出域頭和行計數(shù)*/ pqbool align; /*填充對齊各字段*/ pqbool standard; /* 舊的傻格式 */ pqbool html3; /* 輸出 HTML 表 */ pqbool expanded; /* 擴(kuò)展表*/ pqbool pager; /* 必要時在輸出中使用分頁器 */ char *fieldSep; /* 字段分隔符*/ char *tableOpt; /* 在 HTML 中插入 table ... */ char *caption; /* HTML caption */ char **fieldName; /* 替換字段名組成的空零結(jié)尾的數(shù)組*/ } PQprintOpt;這個函數(shù)以前被psql用于打印查詢結(jié)果，但是現(xiàn)在已經(jīng)不用這個函數(shù)了。請注意它假設(shè)所有的數(shù)據(jù)都是文本格式。
31.3.3. 檢索其它命令的結(jié)果信息
這些函數(shù)用于從PGresult對象里檢索那些非 SELECT 結(jié)果的信息。
-
PQcmdStatus -
返回產(chǎn)生PGresult的 SQL 命令的命令狀態(tài)字符串。
char *PQcmdStatus(PGresult *res);
通常這只是命令的名字，但是它可能包括額外的數(shù)據(jù)，比如處理過的行數(shù)。調(diào)用者不應(yīng)該釋放 結(jié)果。結(jié)果會在把PGresult句柄傳遞給
PQclear的時候釋放。 -
PQcmdTuples -
返回被 SQL 命令影響的行的數(shù)量。
char *PQcmdTuples(PGresult *res);
這個函數(shù)返回一個生成這個PGresult的這個SQL語句影響的行數(shù)的字串。 這個函數(shù)只能用于SELECT，CREATE TABLE AS， INSERT，UPDATE，DELETE， MOVE，FETCH，或者COPY或者COPYEXECUTE語句執(zhí)行之后的結(jié)果。 或者是一個包含INSERT，UPDATE或DELETE或者DELETE語句EXECUTE的一個準(zhǔn)備好的查詢。 如果生成這個PGresult的命令是其他的東西，那么 PQcmdTuples 返回一個空字串。 調(diào)用者不應(yīng)該直接釋放返回的數(shù)值。在相關(guān)聯(lián)的PGresult被傳遞給
PQclear之后， 它會被自動釋放。 -
PQoidValue -
返回一個插入的行的對象標(biāo)識（）—— 如果SQL命令是INSERT， 或者是一個包含合適INSERT語句的準(zhǔn)備好的EXECUTE的時候。否則， 函數(shù)返回InvalidOid。如果受INSERT影響的表不包含 OID， 也返回InvalidOid。
Oid PQoidValue(const PGresult *res);
-
PQoidStatus -
如果SQL命令是INSERT，或者包含合適INSERT的準(zhǔn)備好語句EXECUTE了。 返回一個被插入的行的 OID 的字串。（如果INSERT并非恰好插入一行， 或者目標(biāo)表沒有OID，那么字串將是0。） 如果命令不是INSERT，則返回一個空字串。
char *PQoidStatus(const PGresult *res);
這個函數(shù)已經(jīng)廢棄了，因為有了
PQoidValue，而且它也不是線程安全的。
31.3.4. 逃逸包含在 SQL 命令中的字串
-
PQescapeLiteral -
char *PQescapeLiteral(PGconn *conn，const char *str，size_t length);
PQescapeLiteral為在 SQL 命令中使用字串而對之進(jìn)行逃逸處理。在我們向 SQL 命令里把數(shù)據(jù)值當(dāng)作文本常量插入的時候很有用。有些字符（比如單引號和反斜杠） 必須被逃逸，以避免他們被 SQL 分析器作為特殊字符解析。PQescapeLiteral執(zhí)行這個操作。PQescapeLiteral返回一個內(nèi)存中分配有malloc()的str參數(shù) 的逃逸版本。當(dāng)結(jié)果不在需要時，需要通過PQfreemem()來釋放這塊內(nèi)存。 不需要一個0字節(jié)結(jié)束，并且不應(yīng)以length排序。 （如果在處理length字節(jié)之前出現(xiàn)0字節(jié)的結(jié)束，PQescapeLiteral在此處結(jié)束； 不同于strncpy）。返回的字符串包含所有更換的聲明的字符，因此 可以很好的被PostgreSQL字符串文本解析器處理，同樣，允許增加一個0字節(jié)結(jié)尾。 必須在PostgreSQL字符串文本兩邊的單引號包含在結(jié)果字符串中。一旦錯誤，
PQescapeLiteral返回NULL和在CONN對象存儲合適的信息。Tip: 處理從不可信來源收到的字符串是必須進(jìn)行合適的逃逸，否則存在一定的安全風(fēng)險： 容易受到"SQL injection"攻擊，數(shù)據(jù)庫中會被寫入未知的SQL命令。
需要注意的是，當(dāng)一個數(shù)據(jù)以
PQexecParams或它的兄弟格式，作為一個單獨的參數(shù)傳遞時， 做逃逸是不必要，也是不正確的。 -
PQescapeIdentifier -
char *PQescapeIdentifier(PGconn *conn，const char *str，size_t length);
PQescapeIdentifier逃逸一個字符串作為一個SQL標(biāo)識符使用，如 一個表，列，或函數(shù)名。當(dāng)一個用戶自定義標(biāo)識符需要包含特殊的字符，否則將不能被SQL解析器解析為標(biāo)識符的一部分時， 或者當(dāng)標(biāo)識符需要包含大寫字母，且這種情況必須保留時，這樣做是很有用的。PQescapeIdentifier返回str參數(shù)逃逸為一個內(nèi)存中分配有malloc()的SQL標(biāo)識符 的版本。當(dāng)結(jié)果不再需要時，這塊內(nèi)存必須使用PQfreemem()來釋放。 不需要一個0字節(jié)結(jié)束，并且不應(yīng)以length排序。 （如果在處理length字節(jié)之前出現(xiàn)0字節(jié)的結(jié)束，PQescapeLiteral在此處結(jié)束； 不同于strncpy）。返回的字符串包含所有更換的聲明的字符，因此 可以很好的被PostgreSQL字符串文本解析器處理，同樣，允許增加一個0字節(jié)結(jié)尾。 返回結(jié)果也是被雙引號環(huán)繞。出錯時，
PQescapeIdentifier返回NULL，并且在conn對象中存貯合適的信息。Tip: 由于帶有字符串常量，為阻止SQL攻擊，當(dāng)從一個不可信任資源獲得時，SQL標(biāo)識符必須逃逸。
-
PQescapeStringConn -
size_t PQescapeStringConn(PGconn *conn， char *to，const char *from，size_t length， int *error);PQescapeStringConn逃逸字符串常量，必須同于PQescapeLiteral。 不同于PQescapeLiteral，請求應(yīng)該提供一個適當(dāng)大小的緩沖區(qū)。 更重要的是，PQescapeStringConn不會生成一個必須在PostgreSQL字符串 常量兩端的單引號；SQL命令中應(yīng)該提供，這樣結(jié)果中會被插入。 from參數(shù)指向字符串的第一個字符（用以逃逸）， length參數(shù)指出了在這個字符串中的字節(jié)數(shù)。 不需要一個0字節(jié)結(jié)束，并且不應(yīng)以length排序。 （如果在處理length字節(jié)之前出現(xiàn)0字節(jié)的結(jié)束，PQescapeLiteral在此處結(jié)束； 不同于strncpy）。to應(yīng)該指向一個包含至少多余兩倍length大小的 緩沖區(qū)，要么就不會定義該行為。如果to和from字符串交疊，那么 也不會定義該行為。error參數(shù)非NULL，那么在成功的時候*error會被設(shè)置為空， 失敗的時候設(shè)置為非0。目前唯一可能的錯誤條件涉及在源字符串中無效的多字節(jié)編碼。 輸出字符串同樣產(chǎn)生錯誤，但服務(wù)器可以視其為異常以拒絕。一旦發(fā)生錯誤，一條合適的信息會存儲在conn對象中， 無論error是否為NULL。
PQescapeStringConn返回寫到to的字節(jié)數(shù)，不包含0字節(jié)終止。 -
PQescapeString -
PQescapeString是一個老的，已經(jīng)被PQescapeStringConn棄用了的版本。size_t PQescapeString (char *to，const char *from，size_t length);
與
PQescapeStringConn唯一的不同是，PQescapeString不適用PGconn或error參數(shù)。 因此，不能夠根據(jù)連接屬性（如字符編碼）來調(diào)整其行為，因此可能會給出錯誤的結(jié)果，同樣， 不會報告錯誤條件。PQescapeString可以在客戶端編程（一次只有一個PostgreSQL連接）中安全的使用。 在這種情況下，它可以找到"在屏幕背后"想要知道的。 在其他情況下，這是一個安全隱患，在使用PQescapeStringConn應(yīng)該避免。 -
PQescapeByteaConn -
逃逸那些在 SQL 命令中使用的用bytea表示的二進(jìn)制數(shù)據(jù)。和
PQescapeStringConn一樣， 這個函數(shù)只有在直接向 SQL 字串插入數(shù)據(jù)的時候使用。unsigned char *PQescapeByteaConn(PGconn *conn， const unsigned char *from， size_t from_length， size_t *to_length);在SQL語句中用做bytea字串文本的一部分的時候，有些字節(jié)值必需逃逸（但是對于所有字節(jié)而言是可以逃逸），
PQescapeByteaConn執(zhí)行這個操作，它只逃逸需要逃逸的最少的字符。參閱Section 8.4獲取更多信息。from參數(shù)指向需要逃逸的字串的第一個字節(jié)，from_length參數(shù)反映在這個二進(jìn)制字串（ 結(jié)尾的字節(jié)零既不必要也不計算在內(nèi)的字串）里字節(jié)的個數(shù)。to_length參數(shù)應(yīng)該是一個指向某個緩沖區(qū)的指針， 它的空間應(yīng)該能夠保存逃逸后的結(jié)果字串長度。結(jié)果字串長度不包括結(jié)果結(jié)尾的字節(jié)零。
PQescapeByteaConn在內(nèi)存重返回一個from參數(shù)的二進(jìn)制字串的逃逸后的版本， 這片內(nèi)存是用malloc()分配的（如果無法分配內(nèi)存，則返回空指針）。在不再需要結(jié)果的時候， 必須用PQfreemem()釋放它。返回的字串已經(jīng)把所有特殊的字符替換掉了， 這樣他們就可以由PostgreSQL的字串文本分析器以及bytea的輸入函數(shù)正確地處理。 同時還追加了一個結(jié)尾的字節(jié)零。那些必需包圍在PostgreSQL字串文本周圍的單引號并非結(jié)果字串的一部分。當(dāng)出錯時，返回一個空指針，一個合適的錯誤信息會被儲存在conn對象中，事實上唯一可能的錯誤是結(jié)果字符串的內(nèi)存不足。
-
PQescapeBytea -
PQescapeBytea是PQescapeByteaConn的一個舊的，過時的版本。unsigned char *PQescapeBytea(const unsigned char *from， size_t from_length， size_t *to_length);與
PQescapeByteaConn唯一的不同之處在于，PQescapeBytea不使用PGconn參數(shù)， 因此，PQescapeBytea可以在客戶端編程（一次只有一個PostgreSQL連接）中安全的使用。 在這種情況下，它可以找到"在屏幕背后"想要知道的。 如果在編程中使用多個數(shù)據(jù)庫連接（在這種情況下使用PQescapeByteaConn），那么可能會給出錯誤結(jié)果。 -
PQunescapeBytea -
把一個二進(jìn)制數(shù)據(jù)的逃逸后的字串表現(xiàn)形式轉(zhuǎn)換成二進(jìn)制數(shù)據(jù) —
PQescapeBytea的反作用。 在以文本格式抽取bytea數(shù)據(jù)的時候是必須的， 但是在以二進(jìn)制格式抽取的時候是不必要的。unsigned char *PQunescapeBytea(const unsigned char *from，size_t *to_length);
from參數(shù)指向一個逃逸后的字串，比如
PQgetvalue處理過一個bytea字段后返回的。PQunescapeBytea把它的字串表現(xiàn)形式轉(zhuǎn)換成二進(jìn)制形式， 它返回一個用malloc()分配的指向該緩沖區(qū)的指針，或者是出錯時返回空， 緩沖區(qū)的尺寸放在to_length里。在不再需要這個結(jié)果之后，這片內(nèi)存必須用PQfreemem釋放。這種
PQescapeBytea轉(zhuǎn)換實際上是不可逆的， 因為，當(dāng)從PQgetvalue接收時，字符串不被希望逃逸。 尤其是，這意味著，不需要考慮字符串引用，并且不需要PGconn參數(shù)。