这些函数控制 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
中找到。
在 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);