SQLGetDiagRec 関数

  • [アーティクル]

準拠
導入されたバージョン: ODBC 3.0 標準コンプライアンス: ISO 92

まとめ
SQLGetDiagRec は、エラー、警告、および状態情報を含む診断レコードの複数のフィールドの現在の値を返します。 呼び出しごとに 1 つの診断フィールドを返す SQLGetDiagField とは異なり、 SQLGetDiagRec は、SQLSTATE 、ネイティブ エラー コード、診断メッセージ テキストなど、診断レコードの一般的に使用されるいくつかのフィールドを返します。

構文

  
SQLRETURN SQLGetDiagRec(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLCHAR *       SQLState,  
     SQLINTEGER *    NativeErrorPtr,  
     SQLCHAR *       MessageText,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   TextLengthPtr);

引数

HandleType
[入力]診断が必要なハンドルの種類を表すハンドル型識別子。 次のいずれかである必要があります。

  • SQL_HANDLE_DBC

  • SQL_HANDLE_DBC_INFO_TOKEN

  • SQL_HANDLE_DESC

  • SQL_HANDLE_ENV

  • SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN ハンドルは、ドライバー マネージャーとドライバーでのみ使用されます。 アプリケーションでは、このハンドルの種類を使用しないでください。 SQL_HANDLE_DBC_INFO_TOKENの詳細については、「 ODBC ドライバーでのConnection-Pool認識の開発」を参照してください。

Handle
[入力] HandleType で示される型の診断データ構造のハンドル。 HandleType がSQL_HANDLE_ENVの場合、Handle は共有環境ハンドルまたは非共有環境ハンドルのいずれかになります。

RecNumber
[入力]アプリケーションが情報をシークする状態レコードを示します。 状態レコードには 1 から番号が付けされます。

SQLState
[出力]診断レコード RecNumber の 5 文字の SQLSTATE コード (および終了 NULL) を返すバッファーへのポインター。 最初の 2 文字は クラスを示します。次の 3 つが サブクラスを示します。 この情報は、SQL_DIAG_SQLSTATE診断フィールドに含まれています。 詳細については、「 SQLSTATEs」を参照してください。

NativeErrorPtr
[出力]データ ソースに固有のネイティブ エラー コードを返すバッファーへのポインター。 この情報は、SQL_DIAG_NATIVE診断フィールドに含まれています。

[MessageText]
[出力]診断メッセージテキスト文字列を返すバッファーへのポインター。 この情報は、SQL_DIAG_MESSAGE_TEXT診断フィールドに含まれています。 文字列の形式については、「 診断メッセージ」を参照してください。

MessageText が NULL の場合、TextLengthPtr は、MessageText が指すバッファーで返すために使用できる文字数 (文字データの null 終端文字を除く) を返します。

BufferLength
[入力]*MessageText バッファーの長さ (文字数)。 診断メッセージ テキストの最大長はありません。

TextLengthPtr
[出力] *MessageText で返すために使用できる文字数 (null 終了文字に必要な文字数を除く) を返すバッファーへのポインター。 返される文字数が BufferLength より大きい場合、 *MessageText の診断メッセージ テキストは BufferLength から null 終端文字の長さを引いた値に切り捨てられます。

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA、またはSQL_INVALID_HANDLE。

診断

SQLGetDiagRec は、それ自体の診断レコードをポストしません。 次の戻り値を使用して、独自の実行の結果を報告します。

  • SQL_SUCCESS: 関数は診断情報を正常に返しました。

  • SQL_SUCCESS_WITH_INFO: *MessageText バッファーが小さすぎて、要求された診断メッセージを保持できませんでした。 診断レコードは生成されませんでした。 切り捨てが発生したことを確認するには、アプリケーションは BufferLength を使用可能な実際のバイト数と比較する必要があります。これは *TextLengthPtr に書き込まれます。

  • SQL_INVALID_HANDLE: HandleType および Handle で示される ハンドル が有効なハンドルではありません。

  • SQL_ERROR: 次のいずれかが発生しました。

    • RecNumber が負または 0 でした。

    • BufferLength が 0 未満でした。

    • 非同期通知を使用する場合、ハンドルに対する非同期操作は完了していません。

  • SQL_NO_DATA: RecNumber が、Handle で指定されたハンドルに存在する診断レコードの数より大きかった 。 また、Handle の診断レコードがない場合は、正の RecNumber のSQL_NO_DATAも返 します。

説明

アプリケーションは通常、ODBC 関数の以前の呼び出しがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返したときに SQLGetDiagRec を呼び出します。 ただし、ODBC 関数は呼び出されるたびに 0 個以上の診断レコードをポストできるため、アプリケーションは ODBC 関数呼び出しの後に SQLGetDiagRec を呼び出すことができます。 アプリケーションは 、SQLGetDiagRec を 複数回呼び出して、診断データ構造のレコードの一部またはすべてを返すことができます。 ODBC では、一度に格納できる診断レコードの数に制限はありません。

SQLGetDiagRec を使用して、診断データ構造のヘッダーからフィールドを返すことはできません。 ( RecNumber 引数は 0 より大きくする必要があります)。この目的のために、アプリケーションは SQLGetDiagField を呼び出す必要があります。

SQLGetDiagRec は 、 Handle 引数で指定されたハンドルに最後に関連付けられた診断情報のみを取得します。 アプリケーションが SQLGetDiagRec、SQLGetDiagField、または SQLError を除く別の ODBC 関数を呼び出すと、同じハンドルに対する以前の呼び出しからの診断情報は失われます。

アプリケーションは、SQLGetDiagRec がSQL_SUCCESSを返す限り、RecNumber をインクリメントしてループ処理することで、すべての診断レコードをスキャンできます。 SQLGetDiagRec の呼び出しは、ヘッダー フィールドとレコード フィールドに対して非破壊的です。 SQLGetDiagRec、SQLGetDiagField、または SQLError を除く他の関数が中間で呼び出されていない限り、アプリケーションは後でもう一度 SQLGetDiagRec を呼び出してレコードからフィールドを取得できます。 アプリケーションでは、 SQLGetDiagField を呼び出してSQL_DIAG_NUMBER フィールドの値を取得し、 SQLGetDiagRec を何度も呼び出すことで、使用可能な診断レコードの合計数を取得することもできます。

診断データ構造のフィールドの説明については、「 SQLGetDiagField」を参照してください。 詳細については、「 SQLGetDiagRec と SQLGetDiagField の使用」および 「 SQLGetDiagRec と SQLGetDiagField の実装」を参照してください。

非同期で実行されている API 以外の API を呼び出すと、HY010 "関数シーケンス エラー" が生成されます。 ただし、非同期操作が完了する前にエラー レコードを取得することはできません。

HandleType 引数

各ハンドルの種類には、診断情報を関連付けることができます。 HandleType 引数は、Handle 引数のハンドル型を表します。

一部のヘッダーおよびレコード フィールドは、環境、接続、ステートメント、および記述子ハンドルに対して返すことができません。 フィールドが適用できないハンドルは、 SQLGetDiagField の "ヘッダー フィールド" セクションと "レコード フィールド" セクションに示されます。

HandleType がSQL_HANDLE_SENVの場合、SQLGetDiagRec の呼び出しはSQL_INVALID_HANDLEを返します。これは、共有環境ハンドルを示します。 ただし、 HandleType がSQL_HANDLE_ENVの場合、 Handle は共有環境ハンドルまたは非共有環境ハンドルのいずれかになります。

対象 解決方法については、
診断レコードのフィールドまたは診断ヘッダーのフィールドの取得 SQLGetDiagField 関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル
ODBC のサンプル プログラム