PostgreSQL 7.3 文件
Prev	Chapter 1. libpq - C 庫	Next

1.3. 命令執行函數

一旦與資料庫伺服器的連結成功建立，便可用這裡描述的函數執行 SQL 查詢和命令。

1.3.1. 主過程

PQexec 給伺服器提交一條命令並且等待結果．
```
PGresult *PQexec(PGconn *conn,
                 const char *query);
```
傳回一個PGresult指針或者也可能是一個 NULL 指針．通常傳回一個非空（non-NULL）的指針，除非沒有記憶體或發生了象不能把命令發送到後端這樣的嚴重錯誤．如果傳回的是 NULL，它應該被當作PGRES_FATAL_ERROR結果處理．用PQerrorMessage獲取有關錯誤的更多資訊．

PGresult 結構封裝了後端傳回的結果． libpq 應用程式員應該仔細維護PGresult抽象．用下面的存取函數來獲取PGresult的內容．避免直接參照 PGresult結構的資料域，因為這個結構可能會在未來被改變．（從 PostgreSQL 版本 6.4 開始， struct PGresult的定義甚至都沒有放在 libpq-fe.h裡．如果你有一些直接存取 PGresult資料域的老代碼，你可以通過包含libpq-int.h繼續使用它們，但是我們鼓勵你立刻修改代碼．）

PQresultStatus 傳回命令的結果狀態．
```
ExecStatusType PQresultStatus(const PGresult *res)
```
PQresultStatus可以傳回下面數值之一：
- PGRES_EMPTY_QUERY -- 發送給後端的字串是空的
- PGRES_COMMAND_OK -- 成功完成一個沒有傳回資料的命令
- PGRES_TUPLES_OK -- 成功執行查詢
- PGRES_COPY_OUT -- （從伺服器）Copy Out （拷貝出）資料傳輸開始
- PGRES_COPY_IN -- Copy In （拷貝入）（到伺服器）資料傳輸開始
- PGRES_BAD_RESPONSE -- 伺服器的響應無法理解
- PGRES_NONFATAL_ERROR
- PGRES_FATAL_ERROR
如果結果狀態是 PGRES_TUPLES_OK ，那麼可以用下面的過程從查詢的傳回中抽取元組資訊．注意一個碰巧檢索了零條元組的 SELECT 仍然顯示 PGRES_TUPLES_OK。 PGRES_COMMAND_OK用於不傳回元組的命令（INSERT，UPDATE，等）。傳回 PGRES_EMPTY_QUERY 的響應通常意味著客戶端軟體裡面的臭虫。
PQresStatus 把PQresultStatus傳回的枚舉類型轉換成一個描述狀態碼的字串常數。
```
char *PQresStatus(ExecStatusType status);
```
PQresultErrorMessage 傳回與查詢關聯的錯誤資訊，或在沒有錯誤時傳回一個空字串．
```
char *PQresultErrorMessage(const PGresult *res);
```
緊跟在一個 PQexec 或 PQgetResult 調用後面，PQerrorMessage （對連結）將傳回與 PQresultErrorMessage （對結果）一樣的字串．不過，一個PGresult將保有其錯誤資訊直到被刪除，而連結的錯誤資訊將在後續的操作完成時被改變．當你想知道與某個 PGresult相關聯的狀態時用 PQresultErrorMessage ﹔當你想知道與連結的最近一個操作相關聯的狀態時用 PQerrorMessage﹔
PQclear 釋放於PGresult相關聯的儲存空間．任何不再需要的查詢結果在不需要的時候都應該用 PQclear釋放掉．
```
void PQclear(PQresult *res);
```
你可以保留PGresult物件任意長的時間﹔ 當你提交新的查詢時它並不消失，甚至你中斷連結後也是這樣．要刪除它，你必須調用 PQclear．不這麼做將導致前端的儲存器泄漏．
PQmakeEmptyPGresult 構造一個給出狀態的為空的PGresult物件．
```
PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
```
這是libpq的內部過程，用於分配和初始化一個空PGresult物件．它被輸出是因為一些應用需要自行生成結果物件（尤其是特定的帶有錯誤狀態的物件）．如果conn非空（NULL）並且狀態指示一個錯誤，連結目前的錯誤資訊被拷貝到PGresult．注意最終對該物件要調用PQclear，正如libpq本身傳回的PGresult一樣．

1.3.2. 為包含在 SQL 查詢中逃逸字串

PQescapeString 為在 SQL 查詢中使用逃逸一個字串．

size_t PQescapeString (char *to, const char *from, size_t length);

如果你需要在查詢字串中包含一個從不可靠的源頭接收的字串 (比如，它們是隨機使用者輸入的)，那麼，出於安全原因，你不能把它們直接包含在 SQL 查詢裡．你應該把特殊字元引起來，否則它們就會被 SQL 分析器代換．

PQescapeString 執行這個操作．from 指向將要逃逸的字串的第一個字元，length 參數計算在這個字串裡的字元數量(字串結尾的字節零不是必須的，也不計入長度)． to 應該指向一個緩衝區，這個緩衝區至少能保存 length 數值的兩倍還多一個的字元，否則該函數行為將不可預測．調用 PQescapeString 就會把逃逸的 from 字串轉換到 to 緩衝區，把特殊字元取代掉以免發生意外，並且追加終止的字節零．那些必須包圍在PostgreSQL 字串純文字周圍的單引號不算結果字串的一部分．

PQescapeString 傳回寫到 to 裡面的字元數目，不包括結尾的字節零．如果 to 和 from 字串相互重疊，那麼其行為不可預測．

1.3.3. 逃逸包含在 SQL 查詢中的二進位字串

PQescapeBytea 逃逸那些在 SQL 查詢中使用二進位字串(bytea 類型)．

    unsigned char *PQescapeBytea(const unsigned char *from,
                                         size_t from_length,
                                         size_t *to_length);

在 SQL 語句中用做 BYTEA 字串純文字的一部分的時候，有些 ASCII 字元必需被逃逸 (但是對於所有字元而言是可以逃逸)．通常，要逃逸一個字元，它是被轉換成一個三位八進制數位，該數位數值等於相應的十進制 ASCII 數值，然後前綴兩個反斜扛．單引號(')和反斜扛字元(\)有自己特殊的逃逸序列．參閱使用者手冊獲取更多資訊． PQescapeBytea 執行這個操作，它只逃逸需要逃逸的最少的字元．

from 參數指向需要逃逸的字串的第一個字元， from_length 參數反映在這個二進位字串 (那種字節零既不必要也不計算在內的字串)裡字元的個數． to_length 參數應該是一個指向某個緩衝區的指針，它的空間應該能夠保存逃逸後的結果字串長度. 結果字串長度不包括結果結尾的字節零．

PQescapeBytea 傳回一個 from 參數的二進位字串的逃逸後的版本，傳回給調用者提供的緩衝區．傳回的字串已經把所有特殊的字元取代調了，這樣他們就可以由 PostgreSQL的字串純文字分析器以及 bytea 的輸入函數正確地處理．同時還追加了一個結尾的字節零．那些必需包圍在 PostgreSQL字串純文字周圍的單引號不算結果字串的一部分．

PQunescapeBytea 把一個二進位資料的逃逸後的字串表現形式轉換成二進位資料 - PQescapeBytea 的反作用．

    unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);

from 參數指向一個逃逸後的字串，比如 PQgetvalue 從一個 BYTEA 欄位傳回的．PQunescapeBytea 把它的字串表現形式轉換成二進位形式，填充到一個緩衝區．它傳回一個指向該緩衝區的指針，若為 NULL 則出錯，緩衝區的尺寸放在 to_length 裡．該指針隨後可以用做 free(3) 的參數．

1.3.4. 檢索 SELECT 的結果資訊

PQntuples 傳回查詢結果裡的元組（元組）個數．
```
int PQntuples(const PGresult *res);
```
PQnfields 傳回查詢結果裡每個元組的資料域（欄位）的個數．
```
int PQnfields(const PGresult *res);
```
PQfname 傳回與給出的資料域編號相關聯的資料域（欄位）的名稱．資料域編號從 0 開始
```
char *PQfname(const PGresult *res,
                    int field_index);
```
PQfnumber 傳回與給出的資料域名稱相關聯的資料域（欄位）的編號．
```
int PQfnumber(const PGresult *res,
              const char *field_name);
```
如果給出的名字不相符任何域，傳回-1．
PQftype 傳回與給定資料域編號關聯的資料域類型．整數傳回值是一個該類型的內部編碼．資料域編號從0 開始．
```
Oid PQftype(const PGresult *res,
            int field_index);
```
你可以查詢系統表 pg_type 以獲取各種資料類型的名稱和屬性。內建的資料類型的 OID 在源碼樹的 src/include/catalog/pg_type.h 文件裡定義。
PQfmod 傳回與給定資料域編號相關聯的類型相關的修正資料（??）．資料域編號從 0 開始．
```
int PQfmod(const PGresult *res,
           int field_index);
```
PQfsize 傳回一個PGresult 裡面的一條元組的單獨的一個資料域（欄位）的值．元組和資料域編號從0 開始．
```
int PQfsize(const PGresult *res,
            int field_index);
```
PQfsize傳回在資料庫元組裡面給該資料域分配的空間，換句話說就是該資料類型在伺服器裡的二進位形式的大小（尺寸）．如果該資料域是可變尺寸，傳回 -1．
PQbinaryTuples 如果PGresult包含二進位元組資料時傳回 1，如果包含 ASCII 資料傳回 0．
```
int PQbinaryTuples(const PGresult *res);
```
目前，二進位元組資料只能從一個二進位游標裡抽取資料的查詢傳回．

1.3.5. 檢索 SELECT 結果數值

PQgetvalue 傳回一個PGresult 裡面一個元組單獨的一個資料域（欄位）的值．元組和資料域編號從 0 開始．
```
char* PQgetvalue(const PGresult *res,
                 int tup_num,
                 int field_num);
```
對大多數查詢而言， PQgetvalue 傳回的值是一個表示欄位值的空（NULL）結尾的字串．但是如果 PQbinaryTuples() 為 1， PQgetvalue 傳回的值就是該類型在後端伺服器內部的二進位表現形式（但是不包括尺寸字－－如果資料域是變長的）．這樣，把資料轉換成對應的 C 類型就是程式員的責任了． PQgetvalue 傳回的指針指向一個本身是 PGresult結構的一部分的儲存區域．我們不能變更它，並且如果我們要在PGresult結構的生存期後還要使用它的話，我們必須明確地把該數值拷貝到其他儲存器中．
PQgetisnull 測試一個資料域是否為空（NULL）．元組和資料域編號從 0 開始．
```
int PQgetisnull(const PGresult *res,
                int tup_num,
                int field_num);
```
如果該域包含 NULL，函數傳回 1，如果包含非空（non-null ）值，傳回 0．（注意，對一個 NULL 資料域，PQgetvalue 將傳回一個空字串，不是一個空指針．）
PQgetlength 傳回以字節計的資料域（欄位）的長度．元組和資料域編號從 0 開始．
```
int PQgetlength(const PGresult *res,
                int tup_num,
                int field_num);
```
這是某一特定資料值的實際資料長度，也就是由PQgetvalue 指向的物件的尺寸．注意，對於 ASCII 表示的數值，這個尺寸與PQfsize 報告的二進位尺寸無關．

PQprint 向指定的輸出流列印所有的元組和（可選的）欄位名稱．

void PQprint(FILE* fout,      /* output stream */
             const PGresult *res,
             const PQprintOpt *po);

struct {
    pqbool  header;      /* print output field headings and row count */
    pqbool  align;       /* fill align the fields */
    pqbool  standard;    /* old brain dead format */
    pqbool  html3;       /* output html tables */
    pqbool  expanded;    /* expand tables */
    pqbool  pager;       /* use pager for output if needed */
    char    *fieldSep;   /* field separator */
    char    *tableOpt;   /* insert to HTML table ... */
    char    *caption;    /* HTML caption */
    char    **fieldName; /* null terminated array of replacement field names */
} PQprintOpt;

這個函數以前被 psql 用於列印查詢結果，但是現在已經不用這個函數了，並且此函數不再有活躍的支援。

1.3.6. 檢索非-SELECT 結果資訊

PQcmdStatus 傳回產生PGresult的 SQL 命令的命令狀態字串．
```
char * PQcmdStatus(PGresult *res);
```
PQcmdTuples 傳回被 SQL 命令影響的行的數量．
```
char * PQcmdTuples(PGresult *res);
```
如果產生PGresult的SQL 命令是 INSERT， UPDATE 或 DELETE，這裡傳回涉及行的行數．如果是其他命令傳回一個空字串．
PQoidValue 傳回一個插入的元組的物件標識（OID）──如果 SQL 命令是 INSERT．否則，傳回 InvalidOid．
```
Oid PQoidValue(const PGresult *res);
```
如果你包含了 libpq頭文件，那麼 Oid 和常數 InvalidOid 的類型將被定義。他們都是某種整型類型。
PQoidStatus 傳回一個被插入的元組的物件標識的字串，如果 SQL 命令是 INSERT。否則. 傳回一個空字串。
```
char * PQoidStatus(const PGresult *res);
```
因為有了 PQoidValue ，我們不建議使用這個函數，而且它線上程裡使用也是不安全的。

Prev	Home	Next
資料庫連結函數	Up	異步查詢處理