Postgresql 中文操作指南
34.13. Notice Processing #
服务器生成的通知和警告消息不会由查询执行函数返回,因为它们并不意味着查询失败。相反,它们会被传递给一个通知处理函数,并且处理程序返回后执行将正常继续。默认的通知处理函数将消息打印在 stderr 上,但是应用程序可以通过提供自己的处理函数来覆盖此行为。
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 stderr, but the application can override this behavior by supplying its own handling function.
出于历史原因,存在两级通知处理,即通知接收器和通知处理器。默认行为是通知接收器对通知进行格式化并将其作为字符串传递给通知处理器以进行打印。然而,应用程序如果选择提供自己的通知接收器,通常会忽略通知处理器层并仅在通知接收器中执行所有工作。
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.
函数 PQsetNoticeReceiver 用于设置或检查连接对象的当前通知接收器。类似地,PQsetNoticeProcessor 用于设置或检查当前通知处理器。
The function PQsetNoticeReceiver sets or examines the current notice receiver for a connection object. Similarly, PQsetNoticeProcessor sets or examines the current notice processor.
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);
这些函数每个都会返回前一个通知接收器或处理器函数指针,并设置新值。如果你提供了一个空函数指针,则不会执行任何操作,但会返回当前指针。
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.
当从服务器收到通知或警告信息,或者由 libpq 内部生成时,会调用通知接收器函数。消息将以 PGRES_NONFATAL_ERROR PGresult 的形式传递给它。(这允许接收器使用 PQresultErrorField 提取单个字段,或使用 PQresultErrorMessage 或 PQresultVerboseErrorMessage 获取一个完整的预格式化消息。)传递给 PQsetNoticeReceiver 的相同 void 指针也会被传递。(需要时,可使用此指针访问应用程序特定的状态。)
When a notice or warning message is received from the server, or generated internally by libpq, the notice receiver function is called. It is passed the message in the form of a PGRES_NONFATAL_ERROR PGresult. (This allows the receiver to extract individual fields using PQresultErrorField, or obtain a complete preformatted message using PQresultErrorMessage or PQresultVerboseErrorMessage.) The same void pointer passed to PQsetNoticeReceiver is also passed. (This pointer can be used to access application-specific state if needed.)
默认通知接收器只是提取消息(使用 PQresultErrorMessage )并将其传递给通知处理器。
The default notice receiver simply extracts the message (using PQresultErrorMessage) and passes it to the notice processor.
通知处理器负责处理以文本形式给出的通知或警告信息。传递的消息的 string 文本(包括尾随换行符)以及用作相同并传递给 PQsetNoticeProcessor 的 void 指针。(此指针可用于访问应用程序特定状态(如果需要的话)。)
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 PQsetNoticeProcessor. (This pointer can be used to access application-specific state if needed.)
默认的通知处理器简单来说就是:
The default notice processor is simply:
static void
defaultNoticeProcessor(void *arg, const char *message)
{
fprintf(stderr, "%s", message);
}
设置了通知接收器或处理器之后,应期望只要 PGconn 对象或 PGresult 从中生成的对象存在,就可以调用该函数。在创建 PGresult 时,会将 PGconn 的当前通知处理指针复制到 PGresult 中,以便像 PQgetvalue 这样的函数使用。
Once you have set a notice receiver or processor, you should expect that that function could be called as long as either the PGconn object or PGresult objects made from it exist. At creation of a PGresult, the PGconn's current notice handling pointers are copied into the PGresult for possible use by functions like PQgetvalue.