begriffs open source - ai-pg/blob - full-docs/src/sgml/html/libpq-notice-processing.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.13. Notice Processing</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-misc.html" title="32.12. Miscellaneous Functions" /><link rel="next" href="libpq-events.html" title="32.14. Event System" /></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.13. Notice Processing</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-misc.html" title="32.12. Miscellaneous Functions">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-events.html" title="32.14. Event System">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-NOTICE-PROCESSING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">32.13. Notice Processing <a href="#LIBPQ-NOTICE-PROCESSING" class="id_link">#</a></h2></div></div></div><a id="id-1.7.3.20.2" class="indexterm"></a><p>
   3    Notice and warning messages generated by the server are not returned
   4    by the query execution functions, since they do not imply failure of
   5    the query.  Instead they are passed to a notice handling function, and
   6    execution continues normally after the handler returns.  The default
   7    notice handling function prints the message on
   8    <code class="filename">stderr</code>, but the application can override this
   9    behavior by supplying its own handling function.
  10   </p><p>
  11    For historical reasons, there are two levels of notice handling, called
  12    the notice receiver and notice processor.  The default behavior is for
  13    the notice receiver to format the notice and pass a string to the notice
  14    processor for printing.  However, an application that chooses to provide
  15    its own notice receiver will typically ignore the notice processor
  16    layer and just do all the work in the notice receiver.
  17   </p><p>
  18    The function <code class="function" id="LIBPQ-PQSETNOTICERECEIVER">PQsetNoticeReceiver</code>
  19    <a id="id-1.7.3.20.5.2" class="indexterm"></a>
  20    <a id="id-1.7.3.20.5.3" class="indexterm"></a> sets or
  21    examines the current notice receiver for a connection object.
  22    Similarly, <code class="function" id="LIBPQ-PQSETNOTICEPROCESSOR">PQsetNoticeProcessor</code>
  23    <a id="id-1.7.3.20.5.5" class="indexterm"></a>
  24    <a id="id-1.7.3.20.5.6" class="indexterm"></a> sets or
  25    examines the current notice processor.
  26
  27 </p><pre class="synopsis">
  28 typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
  29
  30 PQnoticeReceiver
  31 PQsetNoticeReceiver(PGconn *conn,
  32                     PQnoticeReceiver proc,
  33                     void *arg);
  34
  35 typedef void (*PQnoticeProcessor) (void *arg, const char *message);
  36
  37 PQnoticeProcessor
  38 PQsetNoticeProcessor(PGconn *conn,
  39                      PQnoticeProcessor proc,
  40                      void *arg);
  41 </pre><p>
  42
  43    Each of these functions returns the previous notice receiver or
  44    processor function pointer, and sets the new value.  If you supply a
  45    null function pointer, no action is taken, but the current pointer is
  46    returned.
  47   </p><p>
  48    When a notice or warning message is received from the server, or
  49    generated internally by <span class="application">libpq</span>, the notice
  50    receiver function is called.  It is passed the message in the form of
  51    a <code class="symbol">PGRES_NONFATAL_ERROR</code>
  52    <code class="structname">PGresult</code>.  (This allows the receiver to extract
  53    individual fields using <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORFIELD"><code class="function">PQresultErrorField</code></a>, or obtain a
  54    complete preformatted message using <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a>
  55    or <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTVERBOSEERRORMESSAGE"><code class="function">PQresultVerboseErrorMessage</code></a>.)  The same
  56    void pointer passed to <code class="function">PQsetNoticeReceiver</code> is also
  57    passed.  (This pointer can be used to access application-specific state
  58    if needed.)
  59   </p><p>
  60    The default notice receiver simply extracts the message (using
  61    <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a>) and passes it to the notice
  62    processor.
  63   </p><p>
  64    The notice processor is responsible for handling a notice or warning
  65    message given in text form.  It is passed the string text of the message
  66    (including a trailing newline), plus a void pointer that is the same
  67    one passed to <code class="function">PQsetNoticeProcessor</code>.  (This pointer
  68    can be used to access application-specific state if needed.)
  69   </p><p>
  70    The default notice processor is simply:
  71 </p><pre class="programlisting">
  72 static void
  73 defaultNoticeProcessor(void *arg, const char *message)
  74 {
  75     fprintf(stderr, "%s", message);
  76 }
  77 </pre><p>
  78   </p><p>
  79    Once you have set a notice receiver or processor, you should expect
  80    that that function could be called as long as either the
  81    <code class="structname">PGconn</code> object or <code class="structname">PGresult</code> objects made
  82    from it exist.  At creation of a <code class="structname">PGresult</code>, the
  83    <code class="structname">PGconn</code>'s current notice handling pointers are copied
  84    into the <code class="structname">PGresult</code> for possible use by functions like
  85    <a class="xref" href="libpq-exec.html#LIBPQ-PQGETVALUE"><code class="function">PQgetvalue</code></a>.
  86   </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-misc.html" title="32.12. Miscellaneous Functions">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-events.html" title="32.14. Event System">Next</a></td></tr><tr><td width="40%" align="left" valign="top">32.12. Miscellaneous Functions </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.14. Event System</td></tr></table></div></body></html>