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

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

Примечание

В Windows, если библиотека libpq и приложение скомпилированы с разными флагами, эта функция может вызвать крах приложения из-за различий внутреннего представления указателей FILE. В частности, флаги многопоточной/однопоточной, выпускаемой/отладочной или статической/динамической сборки должны быть одинаковыми для библиотеки и всех использующих её приложений.

PQsetTraceFlags

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

void PQsetTraceFlags(PGconn *conn, int flags);

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

PQuntrace

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

void PQuntrace(PGconn *conn);