診断レコードと診断フィールド
適用対象: 
SQL Server Azure SQL データベース Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)
診断レコードは、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 は、ODBC SQLSTATE、ネイティブ エラー番号、診断メッセージ フィールドと共に 1 つの診断レコードを取得します。 この機能は ODBC 2. に似ていますxSQLError 関数。 ODBC 3. の最も単純なエラー処理関数x は、RecNumber パラメーターを 1 に設定し、SQLGetDiagRec がSQL_NO_DATAを返すまで、RecNumber を 1 ずつインクリメントして、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 の状態、重大度レベル、サーバー名、プロシージャ名、および行番号を取得します。 また、sqlncli.h には、アプリケーションが DiagIdentifier をSQL_DIAG_DYNAMIC_FUNCTION_CODEに設定して SQLGetDiagField を呼び出す場合に、ドライバーが Transact-SQL ステートメントを識別するために使用するコードの定義が含まれています。
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は、エラーが発生した場所を Microsoft サポート エンジニアに示します。これは、問題の診断に役立つ場合があります。