SQLSTATE

SQLSTATE は、警告やエラーの原因についての詳細情報を提供します。 このマニュアルの SQLSTATE は、ISO/IEF CLI 仕様に記載されているものに基づいていますが、IM で始まる SQLSTATE は ODBC に固有です。

リターン コードとは異なり、このマニュアルの SQLSTATE はガイドラインであり、ドライバーはそれらを返す必要はありません。 そのため、ドライバーは、検出可能なエラーまたは警告に対して適切な SQLSTATE を返す必要があり、アプリケーションで常に発生しているこの問題をカウントしないようにする必要があります。 この状況の理由は次の 2 つです。

• 不完全さ このマニュアルには、多数のエラーと警告、およびそれらのエラーと警告の考えられる原因が記載されていますが、完全なものではなく、ドライバーの実装は多様なため今後とも完全にはなりません。 特定のドライバーは、このマニュアルに記載されているすべての SQLSTATE を返さない可能性があり、このマニュアルに記載されていない SQLSTATE を返す可能性があります。

• 複雑さ データベース エンジン (特にリレーショナル データベース エンジン) によっては、文字通り何千ものエラーと警告が返されます。 このようなエンジンのドライバーは、関連する作業、マッピングの非正確さ、結果として得られるコードのサイズが大きく、結果のコードの値が小さいため、これらのエラーと警告をすべて SQLSTATE にマップする可能性は低く、実行時には発生しないプログラミング エラーを返すことがよくあります。 そのため、ドライバーは、妥当と思われる数のエラーと警告をマップし、SQLSTATE 01004 (データの切り捨て) など、アプリケーション ロジックの基になる可能性があるエラーと警告をマップする必要があります。

SQLSTATE は確実に返されないため、ほとんどのアプリケーションは SQLSTATE を、発生した特定のエラーや警告、およびネイティブ エラー コードに合わせて調整された関連する診断メッセージとともにユーザーに表示するだけです。 アプリケーションはほとんどの SQLSTATE に基づくプログラミング ロジックを使用できないため、この操作により機能が失われることはほとんどありません。 たとえば、SQLExecDirect が SQLSTATE 42000 (構文エラーまたはアクセス違反) を返したとします。 このエラーの原因となった SQL ステートメントがアプリケーションによってハードコーディングまたはビルドされている場合、これはプログラミング エラーであり、コードを修正する必要があります。 SQL ステートメントがユーザーによって入力された場合、これはユーザー エラーであり、アプリケーションはユーザーに問題を通知することで可能なすべてのことを行いました。

アプリケーションが SQLSTATE に対して基本プログラミング ロジックを実行する場合は、SQLSTATE が返されないか、別の SQLSTATE が返されるように準備する必要があります。 どの SQLSTATE が確実に返されるかは、多数のドライバーを使用した経験に基づいてのみ決定できます。 ただし、一般的なガイドラインでは、データ ソースではなく、ドライバーまたはドライバー マネージャーで発生するエラーの SQLSTATE が確実に返される可能性が高くなります。 たとえば、ほとんどのドライバーは SQLSTATE HYC00 を返す可能性があります (省略可能な機能は実装されていません)。一方、SQLSTATE 42021 を返すドライバーは少なくなります (列は既に存在します)。

次の SQLSTATE は、実行時エラーまたは警告を示しており、プログラミング ロジックの基礎となる適切な候補です。 ただし、すべてのドライバーがそれらを返す保証はありません。

• 01004 (データが切り捨て済み)

• 01S02 (オプション値が変更済み)

• HY008 (操作が取り消されました)

• HYC00 (省略可能な機能が実装されていない)

• HYT00 (タイムアウト期限切れ)

ドライバーが特定のステートメントまたは接続属性をサポートしているかどうかをアプリケーションが判断する唯一の方法であるため、SQLSTATE HYC00 (オプション機能は実装されていません) は特に重要です。

SQLSTATE の完全な一覧と、それらを返す関数については、「付録 A: ODBC エラー コード」を参照してください。 各関数が特定の SQLSTATE を返す条件の詳細については、その関数を参照してください。