PostgreSQL 中文参考文档
🌐 英文原版 官方 ↗

32.11. 控制函数 #

这些函数控制 libpq 行为的各种杂项细节。

PQclientEncoding #

返回客户端编码。

int PQclientEncoding(const PGconn *conn);

注意,它返回的是编码 ID, 而非一个符号化的字符串, 例如 EUC_JP。 如果不成功, 它返回 -1。 要把一个编码 ID 转换为编码名, 你可以使用:

char *pg_encoding_to_char(int encoding_id);

PQsetClientEncoding #

设置客户端编码。

int PQsetClientEncoding(PGconn *conn, const char *encoding);

conn 是一条到服务器的连接, encoding 是你想要使用的编码。 如果该函数成功地设置了编码, 它返回 0, 否则返回 -1。 这条连接的当前编码可以用 PQclientEncoding 确定。

PQsetErrorVerbosity #

决定由 PQerrorMessage 和 PQresultErrorMessage 返回的消息的详细程度。

typedef enum
{
    PQERRORS_TERSE,
    PQERRORS_DEFAULT,
    PQERRORS_VERBOSE,
    PQERRORS_SQLSTATE
} PGVerbosity;

PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);

PQsetErrorVerbosity 设置详细程度模式, 并返回连接先前的设置。 在 TERSE 模式下, 返回的消息只包括严重级别、 主要文本和位置; 这通常能放进单行中。 DEFAULT 模式产生的消息包括上述内容, 再加上任何详情、提示或上下文字段 (这些可能跨越多行)。 VERBOSE 模式包括所有可用的字段。 SQLSTATE 模式只包括错误严重级别和 SQLSTATE 错误码(如果有的话; 如果没有, 输出就像 TERSE 模式)。

更改详细程度设置不影响已经存在的 PGresult 对象可用的消息, 只影响随后创建的对象。 (但如果你想用不同的详细程度打印先前的错误, 请参见 PQresultVerboseErrorMessage。)

PQsetErrorContextVisibility #

决定 PQerrorMessage 和 PQresultErrorMessage 返回的消息中 CONTEXT 字段的处理方式。

typedef enum
{
    PQSHOW_CONTEXT_NEVER,
    PQSHOW_CONTEXT_ERRORS,
    PQSHOW_CONTEXT_ALWAYS
} PGContextVisibility;

PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context);

PQsetErrorContextVisibility 设置上下文显示模式, 并返回连接先前的设置。 这个模式控制 CONTEXT 字段是否被包含在消息中。 NEVER 模式从不包含 CONTEXT, 而 ALWAYS 总是包含它(如果可用)。 在 ERRORS 模式(默认值)下, CONTEXT 字段只被包含在错误消息中, 不包含在通知和警告中。 (不过,如果详细程度设置是 TERSE 或 SQLSTATE, 无论上下文显示模式如何, CONTEXT 字段都会被省略。)

更改这个模式不影响已经存在的 PGresult 对象可用的消息, 只影响随后创建的对象。 (但如果你想用不同的显示模式打印先前的错误, 请参见 PQresultVerboseErrorMessage。)

PQtrace #

启用把客户端/服务器通信追踪到一个调试文件流。

void PQtrace(PGconn *conn, FILE *stream);

每一行由以下内容组成: 一个可选的时间戳、 一个方向指示符 (从客户端到服务器的消息用 F, 从服务器到客户端的消息用 B)、 消息长度、消息类型和消息内容。 非消息内容字段 (时间戳、方向、长度和消息类型) 之间用制表符分隔。 消息内容之间用空格分隔。 协议字符串被双引号环绕, 而用作数据值的字符串被单引号环绕。 不可打印的字符以十六进制转义打印。 更多与消息类型相关的细节可以在 Section 54.7 中找到。

Note

在 Windows 上, 如果 libpq 库与应用程序以不同的标志编译, 对这个函数的调用会使应用程序崩溃, 因为 FILE 指针的内部表示不同。 具体来说, 库和所有使用该库的应用程序的多线程/单线程、 release/debug 以及静态/动态标志都应当保持一致。

PQsetTraceFlags #

控制客户端/服务器通信的追踪行为。

void PQsetTraceFlags(PGconn *conn, int flags);

flags 包含描述追踪操作模式的标志位。 如果 flags 包含 PQTRACE_SUPPRESS_TIMESTAMPS, 那么打印每条消息时不会包括时间戳。 如果 flags 包含 PQTRACE_REGRESS_MODE, 那么打印每条消息时某些字段会被遮蔽 (例如对象 OID), 以使输出在测试框架中更便于使用。 这个函数必须在调用 PQtrace 之后调用。

PQuntrace #

禁用由 PQtrace 启动的追踪。

void PQuntrace(PGconn *conn);