MAINHACK

Viewing / Editing File: libpq-notice-processing.html

File is not writable. Editing disabled.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Notice Processing</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.2.24 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="libpq - C Library"
HREF="libpq.html"><LINK
REL="PREVIOUS"
TITLE="Miscellaneous Functions"
HREF="libpq-misc.html"><LINK
REL="NEXT"
TITLE="Event System"
HREF="libpq-events.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2017-11-06T22:43:11"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.2.24 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="Miscellaneous Functions"
HREF="libpq-misc.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpq.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Chapter 31. <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> - C Library</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="Event System"
HREF="libpq-events.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="LIBPQ-NOTICE-PROCESSING"
>31.12. Notice Processing</A
></H1
><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
   <TT
CLASS="FILENAME"
>stderr</TT
>, 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
>
   
    sets or
   examines the current notice receiver for a connection object.
   Similarly, <CODE
CLASS="FUNCTION"
>PQsetNoticeProcessor</CODE
>
   
    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 <TT
CLASS="SYMBOL"
>PGRES_NONFATAL_ERROR</TT
>
   <TT
CLASS="STRUCTNAME"
>PGresult</TT
>.  (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>
  </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
   <TT
CLASS="STRUCTNAME"
>PGconn</TT
> object or <TT
CLASS="STRUCTNAME"
>PGresult</TT
> objects made
   from it exist.  At creation of a <TT
CLASS="STRUCTNAME"
>PGresult</TT
>, the
   <TT
CLASS="STRUCTNAME"
>PGconn</TT
>'s current notice handling pointers are copied
   into the <TT
CLASS="STRUCTNAME"
>PGresult</TT
> for possible use by functions like
   <CODE
CLASS="FUNCTION"
>PQgetvalue</CODE
>.
  </P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpq-misc.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="libpq-events.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Miscellaneous Functions</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="libpq.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Event System</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Cancel / Back
[ MAINHACK ]

Viewing / Editing File: libpq-notice-processing.html

Server Info

System Features

User Info
