31.3. 命令执行函数

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

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

返回一个PGresult指针或者也可能是一个NULL指针。通常返回一个非空的指针， 除非没有内存或发生了象不能把命令发送到服务器这样的严重错误。如果返回的是NULL， 它应该被当作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及其之后的连接协议。

portalName可以是""或NULL以指向未命名端口， 要么必须与现有的端口同名，成功时，会返回一个带有PGRES_COMMAND_OK的PGresult。 可以在这个PGresult中使用PQnfields，PQfname和PQftype函数以 获得端口的结果列的信息。

返回命令的结果状态。

ExecStatusType PQresultStatus(const PGresult *res);

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

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

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

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

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之后，它将被自动释放。

The following field codes are available: 下列代码是可用的：

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

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

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

PQclear释放于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返回在数据库行里面给该数据字段分配的空间，换句话说就是该数据类型在 服务器里的二进制形式的大小（尺寸）。（因此，这个对客户端没有什么用。） 如果该数据域是可变尺寸，返回 -1。

如果PGresult包含二进制元组数据时返回 1， 如果包含 ASCII 数据返回 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);

这是某一特定数据值的实际数据长度。行和字段编号从 0 开始。 这是特定数值的实际数据长度，也就是说，PQgetvalue指向的对象的大小。 对于文本数据格式，它和strlen()相同。对于二进制格式，这是潜在的信息。 请注意我们不应该依靠PQfsize获取实际数据长度。

返回一份声明中的参数的数目。

int PQnparams(const PGresult *res);

检查的结果时，这个功能是非常有用的 PQdescribePrepared。对于其他类型的查询 将返回零。

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

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

检查的结果时，这个功能是非常有用的 PQdescribePrepared。对于其他类型的查询 将返回零。

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

void PQprint(FILE *fout，/* output stream */
             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 中插入 table ... */
    char    *caption;    /* HTML caption */
    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或者COPYEXECUTE语句执行之后的结果。 或者是一个包含INSERT，UPDATE或DELETE或者DELETE语句EXECUTE的一个准备好的查询。 如果生成这个PGresult的命令是其他的东西，那么 PQcmdTuples 返回一个空字串。 调用者不应该直接释放返回的数值。在相关联的PGresult被传递给PQclear之后， 它会被自动释放。

返回一个插入的行的对象标识（）—— 如果SQL命令是INSERT， 或者是一个包含合适INSERT语句的准备好的EXECUTE的时候。否则， 函数返回InvalidOid。如果受INSERT影响的表不包含 OID， 也返回InvalidOid。

Oid PQoidValue(const PGresult *res);

如果SQL命令是INSERT，或者包含合适INSERT的准备好语句EXECUTE了。 返回一个被插入的行的 OID 的字串。（如果INSERT并非恰好插入一行， 或者目标表没有OID，那么字串将是0。） 如果命令不是INSERT，则返回一个空字串。

char *PQoidStatus(const PGresult *res);

这个函数已经废弃了，因为有了PQoidValue，而且它也不是线程安全的。

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字节的结束，PQescapeLiteral在此处结束； 不同于strncpy）。返回的字符串包含所有更换的声明的字符，因此 可以很好的被PostgreSQL字符串文本解析器处理，同样，允许增加一个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字节的结束，PQescapeLiteral在此处结束； 不同于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执行这个操作，它只逃逸需要逃逸的最少的字符。参阅Section 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唯一的不同之处在于，PQescapeBytea不使用PGconn参数， 因此，PQescapeBytea可以在客户端编程（一次只有一个PostgreSQL连接）中安全的使用。 在这种情况下，它可以找到"在屏幕背后"想要知道的。 如果在编程中使用多个数据库连接（在这种情况下使用PQescapeByteaConn），那么可能会给出错误结果。

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

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

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

这种PQescapeBytea转换实际上是不可逆的， 因为，当从PQgetvalue接收时，字符串不被希望逃逸。 尤其是，这意味着，不需要考虑字符串引用，并且不需要PGconn参数。