31.11. エラーの扱い

31.11.1. コールバックの設定

エラーや警告を受け取る簡単な手法の1つは、特定の条件が発生する度に特定の動作を実行するように設定することです。 一般的には以下のようになります。

EXEC SQL WHENEVER condition action;

conditionは以下のいずれかを取ることができます。

actionは以下のいずれかを取ることができます。

標準SQLではCONTINUEとGOTO（とGO TO）のみを提供しています。

簡単なプログラムで使用してみたくなるような例を以下に示します。 警告が発生した場合に簡単なメッセージを表示し、エラーが発生した場合にプログラムを中断します。

EXEC SQL WHENEVER SQLWARNING SQLPRINT;
EXEC SQL WHENEVER SQLERROR STOP;

EXEC SQL WHENEVER文はCの文ではなく、SQLプリプロセッサのディレクティブです。 設定したエラーもしくは警告動作は、最初のEXEC SQL WHENEVERと条件を発生させたSQL文の間で、同一条件に異なる動作が設定されない限り、ハンドラを設定した箇所より後にある、全ての埋め込みSQL文に適用されます。 Cプログラムの制御フローは関係しません。 ですので、以下の2つのCプログラムの抜粋はどちらも望み通りの動作を行いません。

/*
 * WRONG
 */
int main(int argc, char *argv[])
{
    ...
    if (verbose) {
        EXEC SQL WHENEVER SQLWARNING SQLPRINT;
    }
    ...
    EXEC SQL SELECT ...;
    ...
}

/*
 * WRONG
 */
int main(int argc, char *argv[])
{
    ...
    set_error_handler();
    ...
    EXEC SQL SELECT ...;
    ...
}

static void set_error_handler(void)
{
    EXEC SQL WHENEVER SQLERROR STOP;
}

31.11.2. sqlca

より強力にエラーを扱うために、埋め込みSQLインタフェースは以下の構造体を持つsqlcaという名前のグローバル変数を提供します。

struct
{
    char sqlcaid[8];
    long sqlabc;
    long sqlcode;
    struct
    {
        int sqlerrml;
        char sqlerrmc[70];
    } sqlerrm;
    char sqlerrp[8];
    long sqlerrd[6];
    char sqlwarn[8];
    char sqlstate[5];
} sqlca;

（マルチスレッド化されたプログラムでは、各スレッドは自動的にsqlcaのコピーを独自に持ちます。 これは標準Cのerrnoグローバル変数の扱いと同様に動作します。）

sqlcaは警告とエラーの両方を対象としています。 1つの文の実行時に複数の警告やエラーが発生した場合、sqlcaは最後のものに関した情報のみを含みます。

直前のSQL文でエラーがなければ、sqlca.sqlcodeは0に、sqlca.sqlstateは"00000"になります。 警告やエラーが発生した場合は、sqlca.sqlcodeは負の値に、sqlca.sqlstateは"00000"以外になります。 正のsqlca.sqlcodeは、直前の問い合わせが0行を返したなどの無害な条件を示します。 sqlca.sqlcodeとsqlca.sqlstateは2つの異なるエラーコードスキーマです。 後で詳細に説明します。

直前のSQL文が成功すると、sqlca.sqlerrd[1]は処理された行のOIDが、もしあれば、格納されます。 また、もしそのコマンドで適切ならば、sqlca.sqlerrd[2]は処理された、もしくは返された行数が格納されます。

エラーもしくは警告の場合、sqlca.sqlerrm.sqlerrmcには、そのエラーを説明する文字列が格納されます。 sqlca.sqlerrm.sqlerrml フィールドにはsqlca.sqlerrm.sqlerrmcに格納されたエラーメッセージ長が格納されます （strlen()の結果です。おそらくCプログラマは必要としないでしょう）。 一部のメッセージは固定長のsqlerrmc配列には長過ぎることに注意してください。 この場合は切り詰められます。

警告の場合、sqlca.sqlwarn[2]はWに設定されます （他の全ての場合では、これはW以外の何かに設定されます）。 sqlca.sqlwarn[1]がWに設定された場合、ホスト変数に代入する際に値が切り詰められています。 他の要素が警告を示すように設定された場合、sqlca.sqlwarn[0]はWに設定されます。

今のところ、sqlcaid、sqlcabc、sqlerrp、ならびにsqlerrdとsqlwarnの上記以外の要素は有用な情報を持ちません。

sqlcaは標準SQLでは定義されていません。 しかし、複数の他のSQLデータベースシステムで実装されています。 その定義は基本部分は似ていますが、移植性を持つアプリケーションを作成する場合は実装の違いを注意して調査しなければなりません。

31.11.3. SQLSTATE対SQLCODE

sqlca.sqlstateとsqlca.sqlcodeはエラーコードを提供する異なる2つのスキーマです。共に標準SQLから派生されたものですが、SQLCODEはSQL-92版では廃れたものとされ、以降の版から削除されました。 したがって、新規アプリケーションではSQLSTATEを使用することを強く勧めます。

SQLSTATEは5要素の文字配列です。 この5文字は、各種のエラー条件、警告条件のコードを表現する数字、大文字から構成されます。 SQLSTATEは階層を持ったスキーマです。 最初の2文字は条件を汎化したクラスを示し、残り3文字は汎化クラスの副クラスを示します。 成功状態は00000というコードで示されます。 SQLSTATEコードのほとんどは標準SQLで定義されています。 PostgreSQLサーバは本質的にSQLSTATEエラーコードをサポートしています。 したがって、全てのアプリケーションでこのエラーコードを使用することで、高度な一貫性を達成することができます。 詳細については付録Aを参照してください。

廃止されたエラーコードスキーマであるSQLCODEは単なる整数です。 0という値は成功を意味し、正の値は追加情報を持った成功を、負の値はエラーを示します。 標準SQLでは、直前のコマンドが0行を返す、もしくは0行に影響したことを示す100という値までの正の値のみを定義しています。 負の値は規定されていません。 したがって、このスキーマでは低い移植性しか達成できず、また、コード体系も階層を持っていません。 歴史的に、PostgreSQLの埋め込みSQLプロセッサには、いくつかの特殊なSQLCODEの値が専用に割り当てられていました。 以下に、その数値とそのシンボル名の一覧を示します。 これらは他のSQL実装への移植性がないことを忘れないでください。 アプリケーションのSQLSTATEスキーマへの移行を簡易化するために、対応するSQLSTATEも示しています。 しかし、2つのスキーマ間の関係は1対1ではなく1対多です （実際は多対多です）。 ですので、場合ごとに付録Aに示したグローバルな各SQLSTATEを参照しなければなりません。

割り当て済みのSQLCODEです。