codekingpro/portable-devtools

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>34.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="34.12. Miscellaneous Functions" /><link rel="next" href="libpq-events.html" title="34.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">34.13. Notice Processing</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-misc.html" title="34.12. Miscellaneous Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-events.html" title="34.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">34.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 returned4   by the query execution functions, since they do not imply failure of5   the query.  Instead they are passed to a notice handling function, and6   execution continues normally after the handler returns.  The default7   notice handling function prints the message on8   <code class="filename">stderr</code>, but the application can override this9   behavior by supplying its own handling function.10  </p><p>11   For historical reasons, there are two levels of notice handling, called12   the notice receiver and notice processor.  The default behavior is for13   the notice receiver to format the notice and pass a string to the notice14   processor for printing.  However, an application that chooses to provide15   its own notice receiver will typically ignore the notice processor16   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 or21   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 or25   examines the current notice processor.26 27</p><pre class="synopsis">28typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);29 30PQnoticeReceiver31PQsetNoticeReceiver(PGconn *conn,32                    PQnoticeReceiver proc,33                    void *arg);34 35typedef void (*PQnoticeProcessor) (void *arg, const char *message);36 37PQnoticeProcessor38PQsetNoticeProcessor(PGconn *conn,39                     PQnoticeProcessor proc,40                     void *arg);41</pre><p>42 43   Each of these functions returns the previous notice receiver or44   processor function pointer, and sets the new value.  If you supply a45   null function pointer, no action is taken, but the current pointer is46   returned.47  </p><p>48   When a notice or warning message is received from the server, or49   generated internally by <span class="application">libpq</span>, the notice50   receiver function is called.  It is passed the message in the form of51   a <code class="symbol">PGRES_NONFATAL_ERROR</code>52   <code class="structname">PGresult</code>.  (This allows the receiver to extract53   individual fields using <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORFIELD"><code class="function">PQresultErrorField</code></a>, or obtain a54   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 same56   void pointer passed to <code class="function">PQsetNoticeReceiver</code> is also57   passed.  (This pointer can be used to access application-specific state58   if needed.)59  </p><p>60   The default notice receiver simply extracts the message (using61   <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a>) and passes it to the notice62   processor.63  </p><p>64   The notice processor is responsible for handling a notice or warning65   message given in text form.  It is passed the string text of the message66   (including a trailing newline), plus a void pointer that is the same67   one passed to <code class="function">PQsetNoticeProcessor</code>.  (This pointer68   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">72static void73defaultNoticeProcessor(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 expect80   that that function could be called as long as either the81   <code class="structname">PGconn</code> object or <code class="structname">PGresult</code> objects made82   from it exist.  At creation of a <code class="structname">PGresult</code>, the83   <code class="structname">PGconn</code>'s current notice handling pointers are copied84   into the <code class="structname">PGresult</code> for possible use by functions like85   <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="34.12. Miscellaneous Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-events.html" title="34.14. Event System">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.12. Miscellaneous Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.14. Event System</td></tr></table></div></body></html>