SQL エラー マッピング

SQL エラー マッピング ファイル

エラー マッピングは、エラー マッピング ファイルを使用して制御します。これは、マップするエラー状態、SQLCODE と SQLSTATE の置換値、およびオプションでエラー メッセージの置換値 (エラー メッセージの完全な抑制を含む) を指定する単純なテキスト ファイルです。SQLCODE の戻り値、SQLSTATE の戻り値、または返されたエラー メッセージ内のサブストリング、あるいはこれらの任意の組み合わせに基づいて、マッピングを指定できます。

場所

マッピング ファイルのデフォルトの場所は次のとおりです。 %ProgramData%\Micro Focus\sqlcodes

注: MF_ERRORMAP_PATH システム環境変数を使用して、デフォルトの場所をオーバーライドできます。

ファイル名

任意のプレフィックスを使用して、SQL エラー マッピング ファイルの名前を指定できます。ただし、すべてのエラー マッピング ファイルは拡張子が .emap である必要があります。

内容

マッピング ファイルの各レコードには、カンマで区切られた次の値がこの順序で含まれます。

{SC-ret-val|0},{SS-ret-val|0},[msg-substr],SC-repl-val,SS-repl-val,[msg-substr-repl-val]

詳細は次のとおりです。

SC-ret-val|0

データベースからの SQLCODE の戻り値。SQLCODE の戻り値を置換条件として使用しない場合は 0 (ゼロ)。

SS-ret-val|0

データベースからの SQLSTATE の戻り値。SQLSTATE の戻り値を置換条件として使用しない場合は 00000 (すべてゼロ)。

msg-substr

データベースから返されるエラー メッセージに含まれる文字列を指定します (該当する場合)。このサブストリングがエラー メッセージ内に存在する場合に、SQLCODE および SQLSTATE の条件も満たされていると、エラーがマップされます。サブストリングの指定では、次の構文規則が適用されます。

• サブストリングにカンマが含まれている場合は、サブストリング全体を一重引用符 (') または二重引用符 (') で囲みます。
• メッセージのサブストリングでは大文字と小文字が区別されます。

注: サブストリングの検索では、SQLERRMC で返される 70 バイトのサブセットではなく、エラー メッセージ全体が使用されます。

サブストリングを指定する以外に、次のような 2 つのオプションもあります。

• 次のカンマ区切り文字の前にスペースを含めて、値を省略する。この場合、元のメッセージが返されるため、実質的にサブストリングのエラー メッセージ置換がオフになります。
• 1 つのチルダ (~) 文字を指定する。この場合、SQLERRMC、MFSQLMESSAGETEXT (または GET DIAGNOSTICS での MESSAGE_TEXT のホスト変数) で構成されるメッセージ受信フィールドにスペースが入力されます。SQLCA の SQLERRML も、SQLERRMC で返される文字数ではなくゼロに設定されます。

SC-repl-val

元のデータベースの SQLCODE の置換値。

SS-repl-val

元のデータベースの SQLSTATE の置換値。

msg-substr-repl-val

エラー メッセージの置換値 (該当する場合)。msg-substr の構文規則は、msg-substr-repl-val にも適用されます。省略した場合、元のエラー メッセージは置き換えられません。メッセージを完全に抑制するには、1 つのチルダ (~) 文字を指定します。

SQL エラー マッピング レコードの例

例 1

この例は、DB/2 for z/OS から PostgreSQL への移行に基づいています。このマッピング ファイル レコードでは、シングルトン SELECT が 1 から -811 の行を複数返す場合に返される SQLCODE を変更しますが、エラー メッセージはそのままにします。一致は、SQLCODE および SQLSTATE に基づきます。

1, 21000, ,-811, 21000

例 2

この例は、DB/2 for z/OS から PostgreSQL への移行に基づいています。このレコードでは、主キーまたは一意制約のエラーが発生した場合に文字列「duplicate」を含むエラーをマップし、エラー メッセージを「Unique constraint violation」に変更します。SQLCODE についても SQLSTATE についても PostgreSQL が提供する戻り値は重要でないことに注意してください。検索条件は、返された PostgreSQL エラー メッセージのみに基づいています。

0, 00000,"duplicate", -803, 22002, Unique constraint violation

例 3

ODBC では、ホスト変数が戻り値より小さい場合、警告を生成します。アプリケーションで SQLCODE が負ではなくゼロ以外であることを検証すると、予想とは異なる結果が生じる場合があります。エラー メッセージを含め、警告状態を完全に抑制するには、次のレコードを定義して、SQLSTATE の値が 01004 である警告を従来同様に 00000 を戻すようにします。

0, 01004, , 0, 00000, ~

例 4

例 3 に代わる方法として、UTF-8 を使用する環境へのレガシー アプリケーションの移行時、ホスト変数が十分に大きいかどうかをテストする場合に、次のレコードはこの警告を SQLCODE -55 および SQLSTATE "22XYZ" のエラーに変更します。

0, 01004, , -55, 22XYZ, Host variable too small

SQL エラー マッピングの有効化

エラー マッピングを有効にするには、ERRORMAP SQL コンパイラ指令オプションを使用します。詳細については、「ERRORMAP」を参照してください。

1 つのプログラムで複数のエラー マッピング ファイルを使用する場合、詳細については、「SET ERRORMAP」リファレンス トピックを参照してください。