PostgreSQL数据库学习手册之libpq(2)

PQdb 和下面几个函数返回联接时建立起来的几个值．这些值在PGconn对象的生存期内是固定的． *

PQuser 返回联接的用户名． char *PQuser(const PGconn *conn) *

PQpass 返回联接的口令． char *PQpass(const PGconn *conn) *

PQhost 返回联接的服务器主机名． char *PQhost(const PGconn *conn) *

PQport 返回联接的端口号． char *PQport(const PGconn *conn) *

PQtty 返回联接的调试控制台（ tty ）． char *PQtty(const PGconn *conn) *

PQoptions 返回联接中使用的后端选项． char *PQoptions(const PGconn *conn) *

PQstatus 返回联接的状态．

ConnStatusType PQstatus(const PGconn *conn)

这个状态可以是一些值之一。 不过，如果不是一次异步联接过程的话，我们只能看到其中的两个 - CONNECTION_OK 或 CONNECTION_BAD。一个与数据库的成功的联接返回状态 CONNECTION_OK。 一次失败的企图用状态 CONNECTION_BAD 标识。 通常，一个 OK 状态保持到 PQfinish，但是一个通讯失败可能会导致状态过早地改变为 CONNECTION_BAD 。这时应用可以试着调用 PQreset 来恢复． 参阅PQconnectStart和PQconnectPoll 条目看看可能出现的其他的状态码。 *

PQerrorMessage 返回联接中操作产生的最近的错误信息． char *PQerrorMessage(const PGconn* conn);

几乎所有libpq函数在失败时都会设置 PQerrorMessage．注意libpq的传统是， 一个非空的 PQerrorMessage 将在结尾包含一个新行． *

PQbackendPID 返回控制此联接的后端服务器的进程号ID。 int PQbackendPID(const PGconn *conn);

这个后端PID 在调试和对比 NOTIFY 信息（ 包含发出通知的后端的 PID ）时很有用． 注意该 PID 属于运行数据库服务器的主机的进程， 而不是本地主机! *

PQgetssl 返回联接使用的 SSL 结构，或者如果 SSL 没有使用的话返回 NULL． SSL *PQgetssl(const PGconn *conn);

这个结构可以用于核实加密级别，检查服务器认证等信息．参考 SSL 文档获取关于这个结构的更多信息． 为了获取这个函数的原形，你必须定义 USE_SSL． 这样做会自动包含来自OpenSSL的 ssl.h．

PostgreSQL数据库学习手册之libpq-C库----命令执行函数(转)[@more@]

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可以返回下面数值之一： o

PGRES_EMPTY_QUERY -- 发送给后端的字串是空的 o

PGRES_COMMAND_OK -- 成功完成一个没有返回数据的命令 o

PGRES_TUPLES_OK -- 成功执行查询 o

PGRES_COPY_OUT -- （从服务器）Copy Out （拷贝出）数据传输开始 o

PGRES_COPY_IN -- Copy In （拷贝入）（到服务器）数据传输开始 o

PGRES_BAD_RESPONSE -- 服务器的响应无法理解 o

PGRES_NONFATAL_ERROR o

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 */

百度搜索“77cn”或“免费范文网”即可找到本站免费阅读全部范文。收藏本站方便下次阅读，免费范文网，提供经典小说教育文库PostgreSQL数据库学习手册之libpq(2)在线全文阅读。