診断レコードと診断フィールド
診断レコードは、ODBC 環境、接続、ステートメント、または記述子ハンドルに関連付けられています。 ODBC 関数から SQL_SUCCESS または SQL_INVALID_HANDLE 以外のリターン コードが返されるときは、その関数で呼び出されたハンドルに、情報メッセージまたはエラー メッセージが格納された診断レコードが関連付けられます。 これらの診断レコードは、同じハンドルを使用して別の関数が呼び出されるまで保持され、別の呼び出しが行われた時点で破棄されます。 1 つのハンドルに同時に関連付けることができる診断レコードの数に制限はありません。
診断レコードには、ヘッダー レコードと状態レコードの 2 種類があります。 ヘッダー レコードはレコード 0 です。状態レコードが存在する場合は、レコード 1 以降が状態レコードになります。 診断レコードのヘッダー レコードと状態レコードには、それぞれ異なるフィールドが含まれています。 また、ODBC コンポーネントでは、診断レコードに独自のフィールドを定義することもできます。
ヘッダー レコード内のフィールドには、リターン コード、行数、状態レコードの数、実行したステートメントの種類など、関数の実行に関する一般的な情報が保存されます。 ヘッダー レコードは、ODBC 関数から SQL_INVALID_HANDLE が返されない限り、常に作成されます。 ヘッダー レコード内のフィールドの完全な一覧については、「SQLGetDiagField」を参照してください。
状態レコード内のフィールドには、SQLSTATE、ネイティブ エラー番号、診断メッセージ、列番号、行番号など、ODBC ドライバー マネージャー、ドライバー、またはデータ ソースから返される特定のエラーや警告に関する情報が保存されます。 状態レコードは、関数から SQL_ERROR、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_NEED_DATA、または SQL_STILL_EXECUTING が返された場合のみ作成されます。 状態レコード内のフィールドの完全な一覧については、「SQLGetDiagField」を参照してください。
SQLGetDiagRec では、1 つの診断レコードが、ODBC SQLSTATE、ネイティブ エラー番号、および診断メッセージ フィールドと共に取得されます。 この機能は、ODBC 2.x SQLError 関数に似ています。 ODBC 3.x での最も単純なエラー処理は、まず、RecNumber パラメーターを 1 に設定し、その後 RecNumber を 1 ずつ増やしながら、SQLGetDiagRec から SQL_NO_DATA が返されるまで SQLGetDiagRec を繰り返し呼び出すことです。 ODBC 2.x アプリケーションで、SQL_NO_DATA_FOUND が返されるまで SQLError を呼び出すことと同じです。
ODBC 3.x では、ODBC 2.x よりも多くの診断情報がサポートされます。 この情報は、SQLGetDiagField を使用して取得する診断レコードの追加フィールドに格納されます。
SQL Server Native Client ODBC ドライバーには、SQLGetDiagField を使用して取得できるドライバー固有の診断フィールドが用意されています。 これらのドライバー固有のフィールドのラベルは、sqlncli.h で定義されています。 これらのラベルを使用して、各診断レコードに関連付けられた SQL Server の状態、重大度レベル、サーバー名、プロシージャ名、および行番号を取得します。 また、アプリケーションで DiagIdentifier を SQL_DIAG_DYNAMIC_FUNCTION_CODE に設定して SQLGetDiagField を呼び出した場合に、ドライバーが Transact-SQL ステートメントを識別するために使用するコードの定義も sqlncli.h に含まれています。
SQLGetDiagField は、基になるドライバーからキャッシュされるエラー情報を使用して、ODBC ドライバー マネージャーで処理されます。 ODBC ドライバー マネージャーでは、接続が正しく確立されるまでドライバー固有の診断フィールドをキャッシュしません。 接続が確立される前に、ドライバー固有の診断フィールドを取得するために SQLGetDiagField を呼び出すと、SQL_ERROR が返されます。 ODBC 接続関数から SQL_SUCCESS_WITH_INFO が返されても、その接続関数のドライバー固有の診断フィールドはまだ使用できません。 SQLGetDiagField を呼び出してドライバー固有の診断フィールドの取得を開始できるのは、接続関数の後に別の ODBC 関数を呼び出した後だけです。
SQL Server Native Client ODBC ドライバーから報告されるほとんどのエラーは、SQLGetDiagRec から返される情報のみを使用して効率的に診断できます。 ただし、ドライバー固有の診断フィールドから返される情報がエラーを診断するうえで重要になることもあります。 SQL Server Native Client ODBC ドライバーを使用してアプリケーションの ODBC エラー ハンドラーをコーディングする際は、SQLGetDiagField も使用して、少なくともドライバー固有のフィールドの SQL_DIAG_SS_MSGSTATE と SQL_DIAG_SS_SEVERITY は取得するようにすることをお勧めします。 SQL Server コード内の複数の箇所で特定のエラーが発生した可能性がある場合は、SQL_DIAG_SS_MSGSTATE により、エラーの厳密な発生箇所がマイクロソフトのサポート エンジニアに報告されます。この情報は、問題の診断に役立つことがあります。