1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>28.10.Notice Processing</title>
<link rel="stylesheet" href="stylesheet.css" type="text/css">
<link rev="made" href="pgsql-docs@postgresql.org">
<meta name="generator" content="DocBook XSL Stylesheets V1.70.0">
<link rel="start" href="index.html" title="PostgreSQL 8.1.4 Documentation">
<link rel="up" href="libpq.html" title="Chapter28.libpq - C Library">
<link rel="prev" href="libpq-control.html" title="28.9.Control Functions">
<link rel="next" href="libpq-envars.html" title="28.11.Environment Variables">
<link rel="copyright" href="ln-legalnotice.html" title="Legal Notice">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="libpq-notice-processing"></a>28.10.Notice Processing</h2></div></div></div>
<a name="id685505"></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 name="id685553"></a><a name="id685559"></a>
sets or examines the current notice receiver for a connection object.
Similarly, <code class="function">PQsetNoticeProcessor</code>
<a name="id685575"></a><a name="id685582"></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 the complete preformatted message using
<code class="function">PQresultErrorMessage</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>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></body>
</html>
|
