Функции управления

Эти функции управляют различными нюансами поведения libpq.

PQclientEncoding

Возвращает клиентскую кодировку.

int PQclientEncoding(const PGconn *conn);

Обратите внимание, что эта функция возвращает идентификатор кодировки, а не символьную строку наподобие EUC_JP. В случае сбоя она возвращает -1. Чтобы преобразовать идентификатор кодировки в ее имя, можно использовать следующий синтаксис:

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

Определяет режим обработки полей CONTEXT в сообщениях, возвращаемых функциями PQerrorMessage и PQresultErrorMessage.

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 для сообщений от сервера клиенту), длины, типа и содержимого сообщения. Поля содержимого, не относящиеся к сообщению (метка времени, направление, длина и тип сообщения) разделяются табуляцией. Содержимое сообщения разделяется пробелами. Строки протокола заключаются в кавычки, тогда как строки, используемые в качестве значений данных, заключаются в апострофы. Непечатаемые символы выводятся в виде шестнадцатеричных управляющих последовательностей. Дополнительную информацию о типах сообщений см. в разделе Форматы сообщений.

PQsetTraceFlags

Управляет поведением трассировки клиент-серверного взаимодействия.

void PQsetTraceFlags(PGconn *conn, int flags);

Аргумент flags содержит биты флагов, описывающие режим работы трассировки. Если flags содержит PQTRACE_SUPPRESS_TIMESTAMPS, то метка времени не включается при выводе каждого сообщения. Если flags содержит PQTRACE_REGRESS_MODE, то при выводе каждого сообщения редактируются некоторые поля, например OID объектов, чтобы этот вывод было удобнее использовать в средах тестирования. Эту функцию следует вызывать после вызова функции PQtrace.

PQuntrace

Выключает трассировку, запущенную функцией PQtrace.

void PQuntrace(PGconn *conn);