警告処理

PostgreSQL 9.0.0文書
前のページ | 巻戻し | 第 31章libpq - C ライブラリ | 早送り | 次のページ

# 31.11. 警告処理

問い合わせ実行関数では、サーバにより生成された通知と警告メッセージは、問い合わせの失敗を意味していないので返されません。 その代わり、それらは通知処理関数に渡され、ハンドラから返った後も継続して実行されます。 デフォルトの通知処理関数は`stderr`にメッセージを出力しますが、アプリケーションは自身の処理関数を提供することでこの動作を書き換えることができます。

歴史的理由で、通知レシーバと通知プロセッサと呼ばれる２階層の通知処理が存在します。 デフォルトの動作は、通知レシーバが通知を書式化し、出力のため通知プロセッサに文字列を渡します。 しかし、自身の通知レシーバの提供を選択したアプリケーションは、通知プロセッサ層を通常無視し、全ての作業を単に通知レシーバで行います。

関数`PQsetNoticeReceiver`は接続オブジェクトに対し現在の通知レシーバを設定もしくは確認します。 同様に、`PQsetNoticeProcessor`は現在の通知プロセッサの設定もしくは確認を行います。

    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);

各関数は、以前の通知レシーバもしくは通知プロセッサ用の関数へのポインタを返し、新しい値を設定します。 関数ポインタにヌルを渡した場合、何も変更されず、現在のポインタが返されるだけです。

サーバから注意/警告メッセージを受け取ると、あるいは、libpq内部で注意/警告メッセージが生成されると、通知レシーバ関数が呼び出されます。 `PGRES_NONFATAL_ERROR` `PGresult`という形でメッセージが渡されます。 （これにより、レシーバは`PQresultErrorField`を使用して個々のフィールドを取り出すことや、`PQresultErrorMessage`を使用して事前に整形された完全なメッセージを取り出すことができます。） `PQsetNoticeReceiver`に渡されたvoidポインタと同じものも渡されます。 （このポインタを使用して、必要に応じてアプリケーション特有の状態にアクセスすることができます。）

デフォルトの通知レシーバは単に（`PQresultErrorMessage`を使用して）メッセージを取り出し、それを通知プロセッサに渡すだけです。

通知プロセッサは、テキスト形式で与えられた注意/警告メッセージの取扱いに責任を持ちます。 メッセージは（最後改行を含む）文字列テキストで渡され、更に、`PQsetNoticeProcessor`に渡したものと同じvoidポインタも渡されます。 （このポインタを使用して、必要に応じてアプリケーション特有の状態にアクセスすることができます。）

デフォルトの通知プロセッサは以下のような単純なものです。

    static void
    defaultNoticeProcessor(void *arg, const char *message)
    {
        fprintf(stderr, "%s", message);
    }

一旦通知レシーバや通知プロセッサを設定したら、`PGconn`オブジェクトか、それから生成された`PGresult`オブジェクトが存在している間は、その関数が呼び出される可能性があると考えておくべきです。 `PGresult`の生成時には、`PGconn`の現在の警告処理用のポインタが、`PQgetvalue`のような関数で使用可能であるように、`PGresult`へコピーされます。

前のページ | ホーム | 次のページ
雑多な関数 | 上に戻る | イベントシステム