|
- <?xml version="1.0" encoding="UTF-8" standalone="no"?>
- <!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>33.12. 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 V1.79.1" /><link rel="prev" href="libpq-misc.html" title="33.11. Miscellaneous Functions" /><link rel="next" href="libpq-events.html" title="33.13. Event System" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">33.12. Notice Processing</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-misc.html" title="33.11. Miscellaneous Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 33. libpq - C Library">Up</a></td><th width="60%" align="center">Chapter 33. <span xmlns="http://www.w3.org/1999/xhtml" class="application">libpq</span> - C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 12.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-events.html" title="33.13. Event System">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="LIBPQ-NOTICE-PROCESSING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">33.12. Notice Processing</h2></div></div></div><a id="id-1.7.3.19.2" class="indexterm"></a><p>
- Notice and warning messages generated by the server are not returned
- by the query execution functions, since they do not imply failure of
- the query. Instead they are passed to a notice handling function, and
- execution continues normally after the handler returns. The default
- notice handling function prints the message on
- <code class="filename">stderr</code>, but the application can override this
- behavior by supplying its own handling function.
- </p><p>
- For historical reasons, there are two levels of notice handling, called
- the notice receiver and notice processor. The default behavior is for
- the notice receiver to format the notice and pass a string to the notice
- processor for printing. However, an application that chooses to provide
- its own notice receiver will typically ignore the notice processor
- layer and just do all the work in the notice receiver.
- </p><p>
- The function <code class="function">PQsetNoticeReceiver</code>
- <a id="id-1.7.3.19.5.2" class="indexterm"></a>
- <a id="id-1.7.3.19.5.3" class="indexterm"></a> sets or
- examines the current notice receiver for a connection object.
- Similarly, <code class="function">PQsetNoticeProcessor</code>
- <a id="id-1.7.3.19.5.5" class="indexterm"></a>
- <a id="id-1.7.3.19.5.6" class="indexterm"></a> sets or
- examines the current notice processor.
-
- </p><pre class="synopsis">
- typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
-
- PQnoticeReceiver
- PQsetNoticeReceiver(PGconn *conn,
- PQnoticeReceiver proc,
- void *arg);
-
- typedef void (*PQnoticeProcessor) (void *arg, const char *message);
-
- PQnoticeProcessor
- PQsetNoticeProcessor(PGconn *conn,
- PQnoticeProcessor proc,
- void *arg);
- </pre><p>
-
- Each of these functions returns the previous notice receiver or
- processor function pointer, and sets the new value. If you supply a
- null function pointer, no action is taken, but the current pointer is
- returned.
- </p><p>
- When a notice or warning message is received from the server, or
- generated internally by <span class="application">libpq</span>, the notice
- receiver function is called. It is passed the message in the form of
- a <code class="symbol">PGRES_NONFATAL_ERROR</code>
- <code class="structname">PGresult</code>. (This allows the receiver to extract
- individual fields using <code class="function">PQresultErrorField</code>, or obtain a
- complete preformatted message using <code class="function">PQresultErrorMessage</code>
- or <code class="function">PQresultVerboseErrorMessage</code>.) The same
- void pointer passed to <code class="function">PQsetNoticeReceiver</code> is also
- passed. (This pointer can be used to access application-specific state
- if needed.)
- </p><p>
- The default notice receiver simply extracts the message (using
- <code class="function">PQresultErrorMessage</code>) and passes it to the notice
- processor.
- </p><p>
- The notice processor is responsible for handling a notice or warning
- message given in text form. It is passed the string text of the message
- (including a trailing newline), plus a void pointer that is the same
- one passed to <code class="function">PQsetNoticeProcessor</code>. (This pointer
- can be used to access application-specific state if needed.)
- </p><p>
- The default notice processor is simply:
- </p><pre class="programlisting">
- static void
- defaultNoticeProcessor(void *arg, const char *message)
- {
- fprintf(stderr, "%s", message);
- }
- </pre><p>
- </p><p>
- Once you have set a notice receiver or processor, you should expect
- that that function could be called as long as either the
- <code class="structname">PGconn</code> object or <code class="structname">PGresult</code> objects made
- from it exist. At creation of a <code class="structname">PGresult</code>, the
- <code class="structname">PGconn</code>'s current notice handling pointers are copied
- into the <code class="structname">PGresult</code> for possible use by functions like
- <code class="function">PQgetvalue</code>.
- </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">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-events.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">33.11. Miscellaneous Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 33.13. Event System</td></tr></table></div></body></html>
|
