查询执行函数

一旦与数据库服务器的联接成功建立，便可用这里描述的函数执行 SQL 查询和命令。

PQexec 提交一个查询给 Postgres 并且等待结果．

PGresult *PQexec(PGconn *conn,
                 const char *query);

返回一个 PGresult 指针或者也可能是一个 NULL 指针．通常返回一个非空（non-NULL）的指针，除非没有内存或发生了象不能把查询发送到后端这样的严重错误．如果返回的是 NULL，它应该被当作 PGRES_FATAL_ERROR 结果处理．用 PQerrorMessage 获取有关错误的更多信息．

PGresult 结构封装了后端返回的查询结果．libpq 应用程序员应该仔细维护 PGresult．用下面的访问函数来获取 PGresult 的内容．避免直接引用 PGresult 结构的数据域，因为这个结构可能会在未来被改变．（从 Postgres 版本 6.4 开始，结构 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；

PQntuples 返回查询结果里的记录（实例）个数．

int PQntuples(const PGresult *res);

PQnfields 返回查询结果里每个记录的数据域（字段）的个数．

int PQnfields(const PGresult *res);

PQbinaryTuples 如果 PGresult 包含二进制记录数据时返回 1，如果包含 ASCII 数据返回 0．

int PQbinaryTuples(const PGresult *res);

目前，二进制记录数据只能从一个从 BINARY 游标里抽取数据的查询返回．

PQfname 返回与给出的数据域索引相关联的数据域（字段）的名称．数据域索引从 0 开始

char *PQfname(const PGresult *res,
                    int field_index);

PQfnumber Returns the field (attribute) index associated with the given field name.

int PQfnumber(const PGresult *res,
              const char *field_name);

-1 is returned if the given name does not match any field.

PQftype 返回与给定数据域索引关联的数据域类型．整数返回值是一个该类型的内部编码．数据域索引从 0 开始．

Oid PQftype(const PGresult *res,
            int field_num);

你可以查询系统表 pg_type 以获取各种数据类型的名称和属性。内建的数据类型的OID 在源码树的 src/include/catalog/pg_type.h 文件里定义。

PQfsize 返回与给定数据域索引关联的数据域的大小．数据域索引从 0 开始．

int PQfsize(const PGresult *res,
            int field_index);

PQfsize 返回在数据库记录里面给该数据域分配的空间，换句话说就是该数据类型在服务器里的二进制形式的大小（尺寸）．如果该数据域是可变尺寸，返回 -1．

PQfmod 返回与给定数据域索引相关联的类型相关的修正数据（??）．数据域索引从 0 开始．

int PQfmod(const PGresult *res,
           int field_index);

PQgetvalue 返回一个 PGresult 里面的一条记录的单独的一个数据域（字段）的值．记录和数据域索引从 0 开始．

char* PQgetvalue(const PGresult *res,
                 int tup_num,
                 int field_num);

对大多数查询而言，PQgetvalue 返回的值是一个表示字段值的空（NULL）结尾的ASCII 字符串．但是如果 PQbinaryTuples() 为 1，PQgetvalue 返回的值就是该类型在后端服务器内部的二进制表现形式（但是不包括尺寸字－－如果数据域是变长的）．这样，把数据转换成对应的 C 类型就是程序员的责任了．PQgetvalue 返回的指针指向一个本身是 PGresult 结构的一部分的存储区域．我们不能更改它，并且如果我们要在 PGresult 结构的生存期后还要使用它的话，我们必须显式的把该数值拷贝到其他存储器中．

PQgetlength 返回以字节计的数据域（字段）的长度．记录和数据域索引从 0 开始．

int PQgetlength(const PGresult *res,
                int tup_num,
                int field_num);

这是某一特定数据值的实际数据长度，也就是由 PQgetvalue 指向的对象的尺寸．注意，对于 ASCII 代表的数值，这个尺寸与 PQfsize 报告的二进制尺寸无关．

PQgetisnull 测试一个数据域是否为空（NULL）．记录和数据域索引从 0 开始．

int PQgetisnull(const PGresult *res,
                int tup_num,
                int field_num);

如果该域包含 NULL，函数返回 1，如果包含非空（non-null ）值，返回 0．（注意，对一个 NULL 数据域，PQgetvalue 将返回一个空字符串，不是一个空指针．）

PQcmdStatus 返回产生 PGresult 的 SQL 命令的命令状态字符串．

char * PQcmdStatus(const PGresult *res);

PQcmdTuples 返回被 SQL 命令影响的行的数量．

char * PQcmdTuples(const 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，我们不建议使用这个函数，而且它在线程里使用也是不安全的。

    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 用于打印查询结果，但是现在已经不用这个函数了，并且此函数不再有活跃的支持。

PQclear 释放与 PGresult 关联的存储器．当不再需要时，每个查询结果都应该通过 PQclear 释放．

void PQclear(PQresult *res);

你可以保留 PGresult 对象任意长的时间；当你提交新的查询时它并不消失，甚至你断开联接后也是这样．要删除它，你必须调用 PQclear．不这么做将导致前端的存储器泄漏．

PQmakeEmptyPGresult 构建一个给出状态的空的 PGresult 对象．

PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);

这是 libpq 的内部过程，用于分配和初始化一个空 PGresult 对象．它被输出是因为一些应用需要自行生成结果对象（尤其是特定的带有错误状态的对象）．如果 conn 非空（NULL）并且状态指示一个错误，联接当前的 errorMessage 被拷贝到 PGresult．注意最终对该对象要调用 PQclear，正如 libpq 本身返回的 PGresult 一样．