45.2. サーバ内部からのエラーの報告

サーバコード内から生成されるエラー、警告、ログメッセージは、ereport、もしくはこれに似た古いelogを使用して作成してください。 この関数の使用は、いくつか説明が必要なほど複雑です。

すべてのメッセージには、深刻度レベル(DEBUGからPANICまでの範囲)と主メッセージテキストという、2つの必須要素があります。 更に、省略可能な要素があります。 その中で最も良く使用されるのは、SQL仕様のSQLSTATE規則に従うエラー識別コードです。 ereport自身はシェル関数で、主に、メッセージ生成をCソースコード内の関数呼出しのように行なわせる、構文の便宜上存在します。 ereportで直接受け付けられる唯一のパラメータは深刻度レベルです。 主メッセージテキストと任意の省略可能なメッセージ要素は、ereport呼出し内でerrmsgなどの補助関数を呼び出すことで生成されます。

典型的なereportの呼出しは以下のようなものです。

    ereport(ERROR,
            (errcode(ERRCODE_DIVISION_BY_ZERO),
             errmsg("division by zero")));

これは、エラー深刻度レベルERROR(普通のエラー)を指定します。 errcode呼出しは、src/include/utils/errcodes.hで定義されたマクロを使用してSQLSTATEエラーコードを指定します。 errmsg呼出しは、主メッセージテキストを提供します。 補助関数呼出しを囲む余計な括弧群に注意してください。 これらはいらいらさせられますが、構文上必要です。

以下により複雑な例を示します。

    ereport(ERROR,
            (errcode(ERRCODE_AMBIGUOUS_FUNCTION),
             errmsg("function %s is not unique",
                    func_signature_string(funcname, nargs,
                                          actual_arg_types)),
             errhint("Unable to choose a best candidate function. "
                     "You may need to add explicit typecasts.")));

これは、実行時の値をメッセージテキスト内に埋め込むための整形用コードの使用を示します。 また、省略可能な"ヒント"メッセージも提供されています。

ereportで使用可能な補助ルーチンを以下に示します。

まだ頻繁に使用されている、古めのelog関数があります。 以下のelog呼出しは、

    elog(level, "format string", ...);

以下と全く同じです。

    ereport(level, (errmsg_internal("format string", ...)));

SQLSTATEエラーコードが常にデフォルトになること、メッセージ文字列内に国際化メッセージ辞書を含めることができないことに注意してください。 従って、elogは、内部エラーと低レベル名デバッグ用ログにのみに使用すべきです。 一般ユーザを対象とする任意のメッセージはereportを使用すべきです。 それでもなお、システム内の"発生できなかった"内部エラーの検査にelogがまだ多く使用されています。 これは、こうした単純な表記のメッセージに適しています。

項45.3に推奨するエラーメッセージの作成についての提言を示します。

注意

[1]

つまり、ereport呼出しに達した時を現在とした値です。 補助報告ルーチン内でerrnoを変更しても効果はありません。 errmsg内でstrerror(errno)を明示的に記述したとしても正確なものにはなりません。 従って、このようにはしないでください。