begriffs open source - ai-pg/blob - full-docs/txt/libpq-notice-processing.txt

   1
   2 32.13. Notice Processing #
   3
   4    Notice and warning messages generated by the server are not returned by
   5    the query execution functions, since they do not imply failure of the
   6    query. Instead they are passed to a notice handling function, and
   7    execution continues normally after the handler returns. The default
   8    notice handling function prints the message on stderr, but the
   9    application can override this behavior by supplying its own handling
  10    function.
  11
  12    For historical reasons, there are two levels of notice handling, called
  13    the notice receiver and notice processor. The default behavior is for
  14    the notice receiver to format the notice and pass a string to the
  15    notice processor for printing. However, an application that chooses to
  16    provide its own notice receiver will typically ignore the notice
  17    processor layer and just do all the work in the notice receiver.
  18
  19    The function PQsetNoticeReceiver sets or examines the current notice
  20    receiver for a connection object. Similarly, PQsetNoticeProcessor sets
  21    or examines the current notice processor.
  22 typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
  23
  24 PQnoticeReceiver
  25 PQsetNoticeReceiver(PGconn *conn,
  26                     PQnoticeReceiver proc,
  27                     void *arg);
  28
  29 typedef void (*PQnoticeProcessor) (void *arg, const char *message);
  30
  31 PQnoticeProcessor
  32 PQsetNoticeProcessor(PGconn *conn,
  33                      PQnoticeProcessor proc,
  34                      void *arg);
  35
  36    Each of these functions returns the previous notice receiver or
  37    processor function pointer, and sets the new value. If you supply a
  38    null function pointer, no action is taken, but the current pointer is
  39    returned.
  40
  41    When a notice or warning message is received from the server, or
  42    generated internally by libpq, the notice receiver function is called.
  43    It is passed the message in the form of a PGRES_NONFATAL_ERROR
  44    PGresult. (This allows the receiver to extract individual fields using
  45    PQresultErrorField, or obtain a complete preformatted message using
  46    PQresultErrorMessage or PQresultVerboseErrorMessage.) The same void
  47    pointer passed to PQsetNoticeReceiver is also passed. (This pointer can
  48    be used to access application-specific state if needed.)
  49
  50    The default notice receiver simply extracts the message (using
  51    PQresultErrorMessage) and passes it to the notice processor.
  52
  53    The notice processor is responsible for handling a notice or warning
  54    message given in text form. It is passed the string text of the message
  55    (including a trailing newline), plus a void pointer that is the same
  56    one passed to PQsetNoticeProcessor. (This pointer can be used to access
  57    application-specific state if needed.)
  58
  59    The default notice processor is simply:
  60 static void
  61 defaultNoticeProcessor(void *arg, const char *message)
  62 {
  63     fprintf(stderr, "%s", message);
  64 }
  65
  66    Once you have set a notice receiver or processor, you should expect
  67    that that function could be called as long as either the PGconn object
  68    or PGresult objects made from it exist. At creation of a PGresult, the
  69    PGconn's current notice handling pointers are copied into the PGresult
  70    for possible use by functions like PQgetvalue.