診断レコードと診断フィールド
診断レコードは、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.xSQLError 関数に似ています。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 により、エラーの厳密な発生箇所がマイクロソフトのサポート エンジニアに報告されます。この情報は、問題の診断に役立つことがあります。