31.3. 命令执行函数

给服务器提交一条命令并且等待结果。

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

返回一个PGresult指针或者也可能是一个空指针。 通常返回一个非空指针，除非耗尽内存或发生了像不能把命令发送到服务器这样的严重错误。 应该调用PQresultStatus函数来检查任何错误的返回值 （包括空指针的值，在这种情况下它将返回PGRES_FATAL_ERROR）。 使用PQerrorMessage获取有关错误的更多信息。

向服务器提交一条命令并且等待结果，还有独立于SQL命令文本传递参数的能力。

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，但是提供了额外的功能： 参数值可以独立于命令字符串进行声明，并且可以要求查询结果的格式是文本或二进制的。 PQexecParams只是在协议3.0及以后的版本中支持；在使用协议2.0的时候会失败。

函数的参数是：

用给定的参数提交请求，创建一个预备语句，然后等待结束。

PGresult *PQprepare(PGconn *conn,
                    const char *stmtName,
                    const char *query,
                    int nParams,
                    const Oid *paramTypes);

PQprepare创建一个为后面PQexecPrepared执行用的预备语句。 这个特性允许那些重复使用的语句只分析和规划一次，而不是每次执行都分析规划。 只是在协议3.0和以后的连接里支持PQprepare；在使用2.0协议的时候，它会失败。

这个函数从query字串里创建一个叫stmtName的预备语句， query必须只包含一个 SQL 命令。stmtName可以是""， 这样就创建一个无名的语句，这种情况下，任何前面存在的无名语句都会自动被代替； 否则，如果语句名已经在当前会话里定义，那就是一个错误。如果使用了参数， 那么在查询里它们引用成$1，$2等等。nParams 是参数的个数，参数的类型在数组paramTypes[]里事先声明好了。 （如果nParams是零，那么这个数组指针可以是NULL。） paramTypes[]用 OID 的方式声明与参数符号关联的数据类型。 如果paramTypes为NULL，或者数组中某个特定元素是零， 那么服务器将用处理无类型文本同样的方法给这个参数符号赋予数据类型。还有， 查询可以使用比nParams数值更大的参数符号编号； 也为这些符号推断数据类型。（参阅PQdescribePrepared 作为一个找出推断的什么类型的手段。）

和PQexec相似，结果通常是一个PGresult对象， 其内容表明服务器端是成功还是失败。空的结果表示内存耗尽或者完全不能发送命令。 使用PQerrorMessage获取有关这类错误的更多信息。

发送一个请求，执行一个带有给出参数的预备语句，并且等待结果。

PGresult *PQexecPrepared(PGconn *conn,
                         const char *stmtName,
                         int nParams,
                         const char * const *paramValues,
                         const int *paramLengths,
                         const int *paramFormats,
                         int resultFormat);

PQexecPrepared和PQexecParams类似， 但是要执行的命令是通过命名一个前面准备好的语句声明的，而不是给出一个查询字串。 这个特性允许那些要重复使用的命令只进行一次分析和规划，而不是每次执行都来一遍。 这个语句必须在当前会话的前面已经准备好。PQexecPrepared 只在协议 3.0 和以后的版本里支持；在使用 2.0 版本的协议的时候，它们会失败。

参数和PQexecParams一样，只是给出的是一个预备语句的名字，而不是一个查询字串， 并且没有paramTypes[]参数（没必要，因为预备语句的参数类型是在创建的时候确定的）。

提交请求以获取有关指定的预备语句的信息，并等待完成。

PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);

PQdescribePrepared允许应用程序获取有关先前准备的语句的信息。 PQdescribePrepared只在协议 3.0 和以后的版本里支持； 在使用 2.0 版本的协议的时候，它们会失败。

stmtName可以是""或NULL以指向未命名声明， 要么必须与现有的预备语句同名。成功时，会返回一个带有PGRES_COMMAND_OK 的PGresult。可以在这个PGresult中使用 PQnparams和PQparamtype 函数以获得预备语句的参数信息，同时PQnfields， PQfname，PQftype等函数提供声明的结果列（如果有）的信息。

提交请求以获取有关指定的端口的信息，并等待完成。

PGresult *PQdescribePortal(PGconn *conn, const char *portalName);

PQdescribePortal允许应用程序获得关于之前创建的端口的信息。 （libpq不提供与端口的直接连接，但可以使用这个函数来检查 DECLARE CURSOR命令创建的游标的属性）。PQdescribePortal 只支持3.0及其之后的连接协议；当使用协议2.0时会失败。

portalName可以是""或NULL以指向未命名声明， 要么必须与现有的预备语句同名。成功时，会返回一个带有PGRES_COMMAND_OK 的PGresult。可以在PGresult中使用 PQnfields，PQfname， PQftype等函数获取端口的结果列（如果有）的信息。

返回命令的结果状态。

ExecStatusType PQresultStatus(const PGresult *res);

PQresultStatus可以返回下面数值之一：

如果结果状态是PGRES_TUPLES_OK或PGRES_SINGLE_TUPLE， 那么可以用下面的函数从查询的返回中抽取元组信息。注意一个碰巧检索了零条元组的 SELECT仍然显示PGRES_TUPLES_OK。 PGRES_COMMAND_OK用于不返回元组的命令（没有RETURNING 子句的INSERT，UPDATE等）。 返回PGRES_EMPTY_QUERY的响应通常意味着暴露了客户端软件里面的Bug。

状态为PGRES_NONFATAL_ERROR的结果永远不会直接由PQexec 或者其它查询执行函数返回；这类的结果会被传递给通知处理器 （参阅第 31.12 节）。

把PQresultStatus返回的枚举类型转换成一个描述状态码的字符串常量。 调用者不应该释放结果。

char *PQresStatus(ExecStatusType status);

返回与查询关联的错误消息，或在没有错误时返回一个空字符串。

char *PQresultErrorMessage(const PGresult *res);

如果有错误，那么返回的字串将包括一个结尾的新行。调用者不应该直接释放结果。 在相关的PGresult句柄传递给PQclear之后，它会自动释放。

紧跟在一个PQexec或PQgetResult调用后面， PQerrorMessage（对连接）将返回与PQresultErrorMessage (对结果)一样的字符串。不过，一个PGresult将保有其错误消息直到被删除， 而连接的错误消息将在后续的操作完成时被改变。当你想知道与某个PGresult 相关联的状态时用PQresultErrorMessage； 当你想知道与连接的最近一个操作相关联的状态时用PQerrorMessage。

返回一个独立的错误报告字段。

char *PQresultErrorField(const PGresult *res, int fieldcode);

fieldcode是一个错误字段标识符；参阅下面列出的符号。 如果PGresult不是错误或者警告结果或者不包括指定的字段， 那么返回NULL。字段值通常将不包括结尾的新行。调用者不应该直接释放结果。 在相关联的PGresult句柄传递给PQclear之后，它将被自动释放。

下列代码是可用的：

按照自身的要求格式化显示信息是客户端的责任；特别是根据需要对长行进行折行。 在错误消息字段里出现的新行字符应该当作分段符号，而不是换行。

libpq生成的错误将会有严重性和主信息，但是通常没有其它字段。 3.0 协议之前返回的错误将包含严重性和主信息，有时候还有详细信息，但是没有其它字段。

请注意这些错误字段只能从PGresult对象里获得， 而不是PGconn对象；没有PQerrorField函数。

释放与PGresult相关联的存储空间。 任何不再需要的查询结果都应该用PQclear释放掉。

void PQclear(PGresult *res);

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

返回查询结果里的行（元组）个数。因为它返回一个整数的结果，在32位操作系统上大型结果集可能溢出返回值。

int PQntuples(const PGresult *res);

返回查询结果里数据行的列（字段）的个数。

int PQnfields(const PGresult *res);

返回与给出的字段编号相关联的字段名。字段编号从 0 开始。调用者不应该直接释放结果。 在相关联的PGresult句柄传递给PQclear之后，结果会被自动释放。

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

如果字段编号超出范围，那么返回NULL。

返回与给出的字段名相关的字段编号。

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

如果给出的名字不匹配任何字段，返回-1。

给出的名字是当作 SQL 命令里的一个标识符看待的，也就是说，如果没有加双引号， 那么会转换为小写。比如，如果我们有一个从 SQL 命令里生成的查询结果：

SELECT 1 AS FOO, 2 AS "BAR";

那么我们会有下面的结果：

PQfname(res, 0)              foo
PQfname(res, 1)              BAR
PQfnumber(res, "FOO")        0
PQfnumber(res, "foo")        0
PQfnumber(res, "BAR")        -1
PQfnumber(res, "\"BAR\"")    1

返回我们抓取的字段所在的表的 OID。字段编号从 0 开始。

Oid PQftable(const PGresult *res,
             int column_number);

如果字段编号超出了范围，或者声明的字段不是一个指向某个表的字段的简单引用， 或者使用了 3.0 版本之前的协议，那么就会返回InvalidOid。 你可以查询系统表pg_class来判断究竟引用了哪个表。

在你包含libpq头文件的时候，就会定义类型Oid 和常量InvalidOid。他们都是相同的整数类型。

返回组成声明的查询结果字段的字段号（在它的表内部）。查询结果字段编号从 0 开始， 但是表字段编号不会是 0。

int PQftablecol(const PGresult *res,
                int column_number);

如果字段编号超出范围，或者声明的字段并不是一个表字段的简单引用， 或者使用的是 3.0 之前的协议，那么返回零。

返回说明给出字段的格式的格式代码。字段编号从 0 开始。

int PQfformat(const PGresult *res,
              int column_number);

格式码为 0 表示文本数据，而格式码是一表示二进制数据。（其它编码保留给将来定义。）

返回与给定字段编号关联的数据类型。返回的整数是一个该类型的内部 OID 号。字段编号从0 开始。

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

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

返回与给定字段编号相关联的字段的类型修饰符。字段编号从 0 开始。

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

类型修饰符的值是类型相关的；他们通常包括精度或者尺寸限制。 数值 -1 用于表示"没有可用信息"。大多数数据类型不用修饰词，这种情况下该值总是-1。

返回与给定字段编号关联的字段以字节计的大小。字段编号从0 开始。

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

PQfsize返回在数据库行里面给该数据字段分配的空间， 换句话说就是该数据类型在服务器的内部表现形式的大小（尺寸）。（因此， 这个对客户端没有什么用。） 负值表示该数据类型是可变长度。

如果PGresult包含二进制数据时返回 1，如果包含文本数据返回 0。

int PQbinaryTuples(const PGresult *res);

这个函数已经废弃了（除了还用于与COPY连接之外）， 因为我们可能在一个PGresult的某些字段里包含文本数据， 而另外一些字段包含二进制数据。更好的是使用PQfformat。 PQbinaryTuples只有在结果中的所有字段都是二进制（格式 1）的时候才返回 1。

返回一个PGresult里面一行的单独的一个字段的值。 行和字段编号从 0 开始。调用者不应该直接释放结果。在把PGresult 句柄传递给PQclear之后，结果会被自动释放。

char *PQgetvalue(const PGresult *res,
                 int row_number,
                 int column_number);

对于文本格式的数据，PQgetvalue返回的值是一个表示字段值的空（NULL） 结尾的字符串。对于二进制格式，返回的值就是由该数据类型的typsend 和typreceive决定的二进制表现形式。（在这种情况下， 数值实际上也跟着一个字节零，但是通常这个字节没什么用处，因为数值本身很可能包含内嵌的空。）

如果字段值是空，则返回一个空字串。参阅PQgetisnull来区别空值和空字串值。

PQgetvalue返回的指针指向一个本身是PGresult 结构的一部分的存储区域。我们不能更改它，并且如果我们要在PGresult 结构的生存期后还要使用它的话，我们必须明确地把该数值拷贝到其他存储器中。

测试一个字段是否为空（NULL）。行和字段编号从 0 开始。

int PQgetisnull(const PGresult *res,
                int row_number,
                int column_number);

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

返回以字节计的字段的长度。行和字段编号从 0 开始。

int PQgetlength(const PGresult *res,
                int row_number,
                int column_number);

这是特定数值的实际数据长度，也就是说，PQgetvalue指向的对象的大小。 对于文本数据格式，它和strlen()相同。对于二进制格式，这是基本信息。 请注意我们不应该依靠PQfsize 获取实际数据长度。

返回一个预备语句中的参数的数目。

int PQnparams(const PGresult *res);

只有在检查PQdescribePrepared的结果时，这个函数是有用的。 对于其他类型的查询将返回零。

返回指示语句中的参数的数据类型。参数编号从0开始。

Oid PQparamtype(const PGresult *res, int param_number);

只有在检查PQdescribePrepared的结果时，这个函数是有用的。 对于其他类型的查询将返回零。

向指定的输出流打印所有的行和（可选的）字段名称。

void PQprint(FILE *fout,      /* 输出流 */
             const PGresult *res,
             const PQprintOpt *po);
typedef struct
{
    pqbool  header;      /* 打印输出字段头和行计数 */
    pqbool  align;       /* 填充对齐字段 */
    pqbool  standard;    /* 旧的格式 */
    pqbool  html3;       /* 输出HTML表 */
    pqbool  expanded;    /* 扩展表 */
    pqbool  pager;       /* 必要时在输出中使用分页器 */
    char    *fieldSep;   /* 字段分隔符 */
    char    *tableOpt;   /* HTML表格元素的属性 */
    char    *caption;    /* HTML表标题 */
    char    **fieldName; /* 替换字段名组成的空结尾的数组 */
} PQprintOpt;

这个函数以前被psql用于打印查询结果，但是现在已经不用这个函数了。 请注意它假设所有的数据都是文本格式。

返回产生PGresult的 SQL 命令的命令状态标签。

char *PQcmdStatus(PGresult *res);

通常这只是命令的名字，但是它可能包括额外的数据，比如处理过的行数。调用者不应该直接释放结果。 结果会在把PGresult句柄传递给PQclear的时候释放。

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

char *PQcmdTuples(PGresult *res);

这个函数返回一个字符串，包含PGresult产生的SQL语句影响的行数。 这个函数只能用于下列的执行：SELECT，CREATE TABLE AS，INSERT， UPDATE，DELETE，MOVE，FETCH，或者 COPY语句，或者是一个包含INSERT，UPDATE或DELETE 语句的预备查询的EXECUTE。如果生成这个PGresult的命令是其他的东西， 那么PQcmdTuples返回一个空字串。调用者不应该直接释放返回的数值。 在相关联的PGresult被传递给PQclear之后，它会被自动释放。

返回插入的行的OID， 如果SQL命令是INSERT，插入了正好一行到有OID的表格， 或者是一个包含合适INSERT语句的预备查询EXECUTE的时候。 否则，函数返回InvalidOid。如果受INSERT 影响的表不包含 OID，也返回InvalidOid。

Oid PQoidValue(const PGresult *res);

为了支持PQoidValue，这个函数已经废弃了，并且不是线程安全的。 它返回插入行的带有OID的字符串，而PQoidValue返回OID值。

char *PQoidStatus(const PGresult *res);

char *PQescapeLiteral(PGconn *conn, const char *str, size_t length);

PQescapeLiteral为在 SQL 命令中使用字串而对之进行转义处理。 在我们向 SQL 命令里把数据值当作文本常量插入的时候很有用。有些字符 （比如单引号和反斜杠）必须被转义，以避免他们被 SQL 分析器作为特殊字符解析。 PQescapeLiteral执行这个操作。

PQescapeLiteral返回一个内存中分配有malloc()的 str参数的转义版本。当结果不再需要时，需要通过PQfreemem() 来释放这块内存。不需要一个0字节结束，并且不应以length计数。 （如果在处理length字节之前出现0字节的结束，PQescapeLiteral 在此处结束；这个行为有点像strncpy）。返回的字符串中所有特殊字符都替换掉了， 因此可以很好的被PostgreSQL字符串文本解析器处理，同样， 允许增加一个0字节结尾。必须在PostgreSQL 字符串文本两边的单引号包含在结果字符串中。

一旦错误，PQescapeLiteral返回NULL并在conn对象中存储合适的信息。

需要注意的是，当一个数据以PQexecParams或它的兄弟格式， 作为一个单独的参数传递时，做转义是不必要，也是不正确的。

char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length);

PQescapeIdentifier转义一个字符串作为一个SQL标识符使用， 如一个表，列，或函数名。当一个用户自定义标识符需要包含特殊的字符， 否则将不能被SQL解析器解析为标识符的一部分时，或者当标识符需要包含大写字母， 且这种情况必须保留时，这样做是很有用的。

PQescapeIdentifier返回str参数转义为一个内存中分配有 malloc()的SQL标识符的版本。当结果不再需要时，这块内存必须使用 PQfreemem()来释放。不需要一个0字节结束，并且不应以length计数。 （如果在处理length字节之前出现0字节的结束，PQescapeIdentifier 在此处结束；这个行为比较像strncpy）。返回的字符串中所有特殊字符都替换掉了， 因此可以很好的作为SQL标识符被处理。也可以添加一个结尾的0字节。返回字符串也是被双引号环绕。

出错时，PQescapeIdentifier返回NULL，并且在conn对象中存贮合适的信息。

size_t PQescapeStringConn(PGconn *conn,
                          char *to, const char *from, size_t length,
                          int *error);

PQescapeStringConn转义字符串常量，比较像PQescapeLiteral。 不同于PQescapeLiteral，请求应该提供一个适当大小的缓冲区。更重要的是， PQescapeStringConn不会生成一个必须在PostgreSQL 字符串常量两端的单引号；SQL命令中应该提供，这样结果中会被插入。from 参数指向字符串的第一个字符（用以转义），length参数指出了在这个字符串中的字节数。 不需要一个0字节结束，并且不应以length计数。 （如果在处理length字节之前出现0字节的结束，PQescapeStringConn 在此处结束；这个行为比较像strncpy）。to应该指向一个包含至少多于两倍 length大小的缓冲区，要么就不会定义该行为。如果to和from 字符串交叠，那么也不会定义该行为。

error参数非NULL，那么在成功的时候*error会被设置为零， 失败的时候设置为非0。目前唯一可能的错误条件涉及在源字符串中无效的多字节编码。 输出字符串同样产生错误，但服务器可以视其为异常以拒绝。一旦发生错误， 一条合适的信息会存储在conn对象中，无论error是否为NULL。

PQescapeStringConn返回写到to的字节数，不包含0字节终止。

PQescapeString是一个老的，已经被PQescapeStringConn弃用了的版本。

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

与PQescapeStringConn唯一的不同是，PQescapeString 不使用PGconn或error参数。因此，不能够根据连接属性 （如字符编码）来调整其行为，因此可能会给出错误的结果，同样，不会报告错误条件。

PQescapeString可以在客户端编程（一次只有一个PostgreSQL连接） 中安全的使用。在这种情况下，它可以找到"在屏幕背后"想要知道的。在其他情况下， 这是一个安全隐患，使用PQescapeStringConn时应该避免。

转义那些在 SQL 命令中使用的用bytea表示的二进制数据。 和PQescapeStringConn一样，这个函数只有在直接向 SQL 字串插入数据的时候使用。

unsigned char *PQescapeByteaConn(PGconn *conn,
                                 const unsigned char *from,
                                 size_t from_length,
                                 size_t *to_length);

在SQL语句中用做bytea字串文本的一部分的时候， 有些字节值必需转义。PQescapeByteaConn转义字节使用十六进制编码或反斜杠转义。 参阅第 8.4 节获取更多信息。

from参数指向需要转义的字串的第一个字节，from_length 参数反映在这个二进制字串（结尾的字节零既不必要也不计算在内）里字节的个数。 to_length参数指向一个变量，它保存转义后字符串长度的结果。 结果字串长度包括结果结尾的零字节。

PQescapeByteaConn在内存中返回一个from 参数的二进制字串的转义后的版本，这片内存是用malloc()分配的 在不再需要结果的时候，必须用PQfreemem()释放内存。 返回的字串已经把所有特殊的字符替换掉了，这样他们就可以由PostgreSQL 的字串文本分析器以及bytea的输入函数正确地处理。同时还追加了一个结尾的字节零。 那些必需包围在PostgreSQL字串文本周围的单引号并非结果字串的一部分。

当出错时，返回一个空指针，一个合适的错误消息会被储存在conn对象中， 当前唯一可能的错误是结果字符串的内存不足。

PQescapeBytea是PQescapeByteaConn的一个旧的，过时的版本。

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

与PQescapeByteaConn唯一的不同之处在于，PQescapeByteaConn 不使用PGconn参数，因此，PQescapeBytea可以在客户端编程 （一次只有一个PostgreSQL连接）中安全的使用。在这种情况下， 它可以找到"在屏幕背后"想要知道的。如果在编程中使用多个数据库连接 （在这种情况下使用PQescapeByteaConn），那么可能会给出错误结果。

把一个二进制数据的字符串表现形式转换成二进制数据— PQescapeBytea的反作用。在以文本格式抽取bytea 数据的时候是必须的，但是在以二进制格式抽取的时候是不必要的。

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

from参数指向一个字符串，比如应用到bytea字段时， PQgetvalue返回的。PQunescapeBytea 把它的字串表现形式转换成二进制形式，它返回一个用malloc() 分配的指向该缓冲区的指针，或者是出错时返回NULL，缓冲区的尺寸放在 to_length里。在不再需要这个结果之后， 这片内存必须用PQfreemem释放。

这个转换不正好是PQescapeBytea逆转换，因为，当从 PQgetvalue接收时，字符串不希望被"转义"。尤其是，这意味着， 不需要考虑字符串引用，并且不需要PGconn参数。