begriffs open source - ai-pg/blob - full-docs/src/sgml/html/libpq-control.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>32.11. Control Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-copy.html" title="32.10. Functions Associated with the COPY Command" /><link rel="next" href="libpq-misc.html" title="32.12. Miscellaneous Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">32.11. Control Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-copy.html" title="32.10. Functions Associated with the COPY Command">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 32. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-misc.html" title="32.12. Miscellaneous Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-CONTROL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">32.11. Control Functions <a href="#LIBPQ-CONTROL" class="id_link">#</a></h2></div></div></div><p>
   3    These functions control miscellaneous details of <span class="application">libpq</span>'s
   4    behavior.
   5   </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQCLIENTENCODING"><span class="term"><code class="function">PQclientEncoding</code><a id="id-1.7.3.18.3.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCLIENTENCODING" class="id_link">#</a></dt><dd><p>
   6       Returns the client encoding.
   7 </p><pre class="synopsis">
   8 int PQclientEncoding(const PGconn *<em class="replaceable"><code>conn</code></em>);
   9 </pre><p>
  10
  11       Note that it returns the encoding ID, not a symbolic string
  12       such as <code class="literal">EUC_JP</code>. If unsuccessful, it returns -1.
  13       To convert an encoding ID to an encoding name, you
  14       can use:
  15
  16 </p><pre class="synopsis">
  17 char *pg_encoding_to_char(int <em class="replaceable"><code>encoding_id</code></em>);
  18 </pre><p>
  19      </p></dd><dt id="LIBPQ-PQSETCLIENTENCODING"><span class="term"><code class="function">PQsetClientEncoding</code><a id="id-1.7.3.18.3.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETCLIENTENCODING" class="id_link">#</a></dt><dd><p>
  20       Sets the client encoding.
  21 </p><pre class="synopsis">
  22 int PQsetClientEncoding(PGconn *<em class="replaceable"><code>conn</code></em>, const char *<em class="replaceable"><code>encoding</code></em>);
  23 </pre><p>
  24
  25       <em class="replaceable"><code>conn</code></em> is a connection to the server,
  26       and <em class="replaceable"><code>encoding</code></em> is the encoding you want to
  27       use. If the function successfully sets the encoding, it returns 0,
  28       otherwise -1. The current encoding for this connection can be
  29       determined by using <a class="xref" href="libpq-control.html#LIBPQ-PQCLIENTENCODING"><code class="function">PQclientEncoding</code></a>.
  30      </p></dd><dt id="LIBPQ-PQSETERRORVERBOSITY"><span class="term"><code class="function">PQsetErrorVerbosity</code><a id="id-1.7.3.18.3.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETERRORVERBOSITY" class="id_link">#</a></dt><dd><p>
  31       Determines the verbosity of messages returned by
  32       <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE">
  33       <code class="function">PQerrorMessage</code>
  34
  35      </a> and <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a>.
  36 </p><pre class="synopsis">
  37 typedef enum
  38 {
  39     PQERRORS_TERSE,
  40     PQERRORS_DEFAULT,
  41     PQERRORS_VERBOSE,
  42     PQERRORS_SQLSTATE
  43 } PGVerbosity;
  44
  45 PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
  46 </pre><p>
  47
  48       <a class="xref" href="libpq-control.html#LIBPQ-PQSETERRORVERBOSITY"><code class="function">PQsetErrorVerbosity</code></a> sets the verbosity mode,
  49       returning the connection's previous setting.
  50       In <em class="firstterm">TERSE</em> mode, returned messages include
  51       severity, primary text, and position only; this will normally fit on a
  52       single line.  The <em class="firstterm">DEFAULT</em> mode produces messages
  53       that include the above plus any detail, hint, or context fields (these
  54       might span multiple lines).  The <em class="firstterm">VERBOSE</em> mode
  55       includes all available fields.  The <em class="firstterm">SQLSTATE</em>
  56       mode includes only the error severity and the <code class="symbol">SQLSTATE</code>
  57       error code, if one is available (if not, the output is like
  58       <em class="firstterm">TERSE</em> mode).
  59      </p><p>
  60       Changing the verbosity setting does not affect the messages available
  61       from already-existing <code class="structname">PGresult</code> objects, only
  62       subsequently-created ones.
  63       (But see <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTVERBOSEERRORMESSAGE"><code class="function">PQresultVerboseErrorMessage</code></a> if you
  64       want to print a previous error with a different verbosity.)
  65      </p></dd><dt id="LIBPQ-PQSETERRORCONTEXTVISIBILITY"><span class="term"><code class="function">PQsetErrorContextVisibility</code><a id="id-1.7.3.18.3.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETERRORCONTEXTVISIBILITY" class="id_link">#</a></dt><dd><p>
  66       Determines the handling of <code class="literal">CONTEXT</code> fields in messages
  67       returned by <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE">
  68       <code class="function">PQerrorMessage</code>
  69
  70      </a>
  71       and <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a>.
  72 </p><pre class="synopsis">
  73 typedef enum
  74 {
  75     PQSHOW_CONTEXT_NEVER,
  76     PQSHOW_CONTEXT_ERRORS,
  77     PQSHOW_CONTEXT_ALWAYS
  78 } PGContextVisibility;
  79
  80 PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context);
  81 </pre><p>
  82
  83       <a class="xref" href="libpq-control.html#LIBPQ-PQSETERRORCONTEXTVISIBILITY"><code class="function">PQsetErrorContextVisibility</code></a> sets the context display mode,
  84       returning the connection's previous setting.  This mode controls
  85       whether the <code class="literal">CONTEXT</code> field is included in messages.
  86       The <em class="firstterm">NEVER</em> mode
  87       never includes <code class="literal">CONTEXT</code>, while <em class="firstterm">ALWAYS</em> always
  88       includes it if available.  In <em class="firstterm">ERRORS</em> mode (the
  89       default), <code class="literal">CONTEXT</code> fields are included only in error
  90       messages, not in notices and warnings.
  91       (However, if the verbosity setting is <em class="firstterm">TERSE</em>
  92       or <em class="firstterm">SQLSTATE</em>, <code class="literal">CONTEXT</code> fields
  93       are omitted regardless of the context display mode.)
  94      </p><p>
  95       Changing this mode does not
  96       affect the messages available from
  97       already-existing <code class="structname">PGresult</code> objects, only
  98       subsequently-created ones.
  99       (But see <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTVERBOSEERRORMESSAGE"><code class="function">PQresultVerboseErrorMessage</code></a> if you
 100       want to print a previous error with a different display mode.)
 101      </p></dd><dt id="LIBPQ-PQTRACE"><span class="term"><code class="function">PQtrace</code><a id="id-1.7.3.18.3.5.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQTRACE" class="id_link">#</a></dt><dd><p>
 102       Enables tracing of the client/server communication to a debugging file
 103       stream.
 104 </p><pre class="synopsis">
 105 void PQtrace(PGconn *conn, FILE *stream);
 106 </pre><p>
 107      </p><p>
 108       Each line consists of: an optional timestamp, a direction indicator
 109       (<code class="literal">F</code> for messages from client to server
 110       or <code class="literal">B</code> for messages from server to client),
 111       message length, message type, and message contents.
 112       Non-message contents fields (timestamp, direction, length and message type)
 113       are separated by a tab. Message contents are separated by a space.
 114       Protocol strings are enclosed in double quotes, while strings used as data
 115       values are enclosed in single quotes.  Non-printable chars are printed as
 116       hexadecimal escapes.
 117       Further message-type-specific detail can be found in
 118       <a class="xref" href="protocol-message-formats.html" title="54.7. Message Formats">Section 54.7</a>.
 119      </p><div class="note"><h3 class="title">Note</h3><p>
 120        On Windows, if the <span class="application">libpq</span> library and an application are
 121        compiled with different flags, this function call will crash the
 122        application because the internal representation of the <code class="literal">FILE</code>
 123        pointers differ.  Specifically, multithreaded/single-threaded,
 124        release/debug, and static/dynamic flags should be the same for the
 125        library and all applications using that library.
 126       </p></div></dd><dt id="LIBPQ-PQSETTRACEFLAGS"><span class="term"><code class="function">PQsetTraceFlags</code><a id="id-1.7.3.18.3.6.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETTRACEFLAGS" class="id_link">#</a></dt><dd><p>
 127       Controls the tracing behavior of client/server communication.
 128 </p><pre class="synopsis">
 129 void PQsetTraceFlags(PGconn *conn, int flags);
 130 </pre><p>
 131      </p><p>
 132       <code class="literal">flags</code> contains flag bits describing the operating mode
 133       of tracing.
 134       If <code class="literal">flags</code> contains <code class="literal">PQTRACE_SUPPRESS_TIMESTAMPS</code>,
 135       then the timestamp is not included when printing each message.
 136       If <code class="literal">flags</code> contains <code class="literal">PQTRACE_REGRESS_MODE</code>,
 137       then some fields are redacted when printing each message, such as object
 138       OIDs, to make the output more convenient to use in testing frameworks.
 139       This function must be called after calling <code class="function">PQtrace</code>.
 140      </p></dd><dt id="LIBPQ-PQUNTRACE"><span class="term"><code class="function">PQuntrace</code><a id="id-1.7.3.18.3.7.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQUNTRACE" class="id_link">#</a></dt><dd><p>
 141       Disables tracing started by <a class="xref" href="libpq-control.html#LIBPQ-PQTRACE"><code class="function">PQtrace</code></a>.
 142 </p><pre class="synopsis">
 143 void PQuntrace(PGconn *conn);
 144 </pre><p>
 145      </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-copy.html" title="32.10. Functions Associated with the COPY Command">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-misc.html" title="32.12. Miscellaneous Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">32.10. Functions Associated with the <code class="command">COPY</code> Command </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 32.12. Miscellaneous Functions</td></tr></table></div></body></html>