diff options
Diffstat (limited to 'doc/src/sgml/html/libpq-notice-processing.html')
| -rw-r--r-- | doc/src/sgml/html/libpq-notice-processing.html | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/doc/src/sgml/html/libpq-notice-processing.html b/doc/src/sgml/html/libpq-notice-processing.html new file mode 100644 index 0000000..2b2dad8 --- /dev/null +++ b/doc/src/sgml/html/libpq-notice-processing.html @@ -0,0 +1,86 @@ +<?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>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 15.4 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</h2></div></div></div><a id="id-1.7.3.20.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" id="LIBPQ-PQSETNOTICERECEIVER">PQsetNoticeReceiver</code> + <a id="id-1.7.3.20.5.2" class="indexterm"></a> + <a id="id-1.7.3.20.5.3" class="indexterm"></a> sets or + examines the current notice receiver for a connection object. + Similarly, <code class="function" id="LIBPQ-PQSETNOTICEPROCESSOR">PQsetNoticeProcessor</code> + <a id="id-1.7.3.20.5.5" class="indexterm"></a> + <a id="id-1.7.3.20.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 <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORFIELD"><code class="function">PQresultErrorField</code></a>, or obtain a + complete preformatted message using <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a> + or <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTVERBOSEERRORMESSAGE"><code class="function">PQresultVerboseErrorMessage</code></a>.) 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 + <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTERRORMESSAGE"><code class="function">PQresultErrorMessage</code></a>) 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 + <a class="xref" href="libpq-exec.html#LIBPQ-PQGETVALUE"><code class="function">PQgetvalue</code></a>. + </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 15.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.14. Event System</td></tr></table></div></body></html>
\ No newline at end of file |