begriffs open source - ai-pg/blob - full-docs/txt/libpq-control.txt

   1
   2 32.11. Control Functions #
   3
   4    These functions control miscellaneous details of libpq's behavior.
   5
   6    PQclientEncoding #
   7           Returns the client encoding.
   8
   9 int PQclientEncoding(const PGconn *conn);
  10
  11           Note that it returns the encoding ID, not a symbolic string such
  12           as EUC_JP. If unsuccessful, it returns -1. To convert an
  13           encoding ID to an encoding name, you can use:
  14
  15 char *pg_encoding_to_char(int encoding_id);
  16
  17    PQsetClientEncoding #
  18           Sets the client encoding.
  19
  20 int PQsetClientEncoding(PGconn *conn, const char *encoding);
  21
  22           conn is a connection to the server, and encoding is the encoding
  23           you want to use. If the function successfully sets the encoding,
  24           it returns 0, otherwise -1. The current encoding for this
  25           connection can be determined by using PQclientEncoding.
  26
  27    PQsetErrorVerbosity #
  28           Determines the verbosity of messages returned by PQerrorMessage
  29           and PQresultErrorMessage.
  30
  31 typedef enum
  32 {
  33     PQERRORS_TERSE,
  34     PQERRORS_DEFAULT,
  35     PQERRORS_VERBOSE,
  36     PQERRORS_SQLSTATE
  37 } PGVerbosity;
  38
  39 PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
  40
  41           PQsetErrorVerbosity sets the verbosity mode, returning the
  42           connection's previous setting. In TERSE mode, returned messages
  43           include severity, primary text, and position only; this will
  44           normally fit on a single line. The DEFAULT mode produces
  45           messages that include the above plus any detail, hint, or
  46           context fields (these might span multiple lines). The VERBOSE
  47           mode includes all available fields. The SQLSTATE mode includes
  48           only the error severity and the SQLSTATE error code, if one is
  49           available (if not, the output is like TERSE mode).
  50
  51           Changing the verbosity setting does not affect the messages
  52           available from already-existing PGresult objects, only
  53           subsequently-created ones. (But see PQresultVerboseErrorMessage
  54           if you want to print a previous error with a different
  55           verbosity.)
  56
  57    PQsetErrorContextVisibility #
  58           Determines the handling of CONTEXT fields in messages returned
  59           by PQerrorMessage and PQresultErrorMessage.
  60
  61 typedef enum
  62 {
  63     PQSHOW_CONTEXT_NEVER,
  64     PQSHOW_CONTEXT_ERRORS,
  65     PQSHOW_CONTEXT_ALWAYS
  66 } PGContextVisibility;
  67
  68 PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibilit
  69 y show_context);
  70
  71           PQsetErrorContextVisibility sets the context display mode,
  72           returning the connection's previous setting. This mode controls
  73           whether the CONTEXT field is included in messages. The NEVER
  74           mode never includes CONTEXT, while ALWAYS always includes it if
  75           available. In ERRORS mode (the default), CONTEXT fields are
  76           included only in error messages, not in notices and warnings.
  77           (However, if the verbosity setting is TERSE or SQLSTATE, CONTEXT
  78           fields are omitted regardless of the context display mode.)
  79
  80           Changing this mode does not affect the messages available from
  81           already-existing PGresult objects, only subsequently-created
  82           ones. (But see PQresultVerboseErrorMessage if you want to print
  83           a previous error with a different display mode.)
  84
  85    PQtrace #
  86           Enables tracing of the client/server communication to a
  87           debugging file stream.
  88
  89 void PQtrace(PGconn *conn, FILE *stream);
  90
  91           Each line consists of: an optional timestamp, a direction
  92           indicator (F for messages from client to server or B for
  93           messages from server to client), message length, message type,
  94           and message contents. Non-message contents fields (timestamp,
  95           direction, length and message type) are separated by a tab.
  96           Message contents are separated by a space. Protocol strings are
  97           enclosed in double quotes, while strings used as data values are
  98           enclosed in single quotes. Non-printable chars are printed as
  99           hexadecimal escapes. Further message-type-specific detail can be
 100           found in Section 54.7.
 101
 102 Note
 103
 104           On Windows, if the libpq library and an application are compiled
 105           with different flags, this function call will crash the
 106           application because the internal representation of the FILE
 107           pointers differ. Specifically, multithreaded/single-threaded,
 108           release/debug, and static/dynamic flags should be the same for
 109           the library and all applications using that library.
 110
 111    PQsetTraceFlags #
 112           Controls the tracing behavior of client/server communication.
 113
 114 void PQsetTraceFlags(PGconn *conn, int flags);
 115
 116           flags contains flag bits describing the operating mode of
 117           tracing. If flags contains PQTRACE_SUPPRESS_TIMESTAMPS, then the
 118           timestamp is not included when printing each message. If flags
 119           contains PQTRACE_REGRESS_MODE, then some fields are redacted
 120           when printing each message, such as object OIDs, to make the
 121           output more convenient to use in testing frameworks. This
 122           function must be called after calling PQtrace.
 123
 124    PQuntrace #
 125           Disables tracing started by PQtrace.
 126
 127 void PQuntrace(PGconn *conn);