SQLGetDiagRec 関数

適合 性
導入バージョン:ODBC 3.0 規格準拠:ISO 92

Summary
SQLGetDiagRec はエラー、警告、ステータス情報を含む複数のフィールドの現在の値を返します。 SQLGetDiagFieldが1回の呼び出しにつき1つの診断フィールドを返すのに対し、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されている場合、ハンドル は共有環境ハンドルまたは非共有環境ハンドルにすることができます。

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

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

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

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

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

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

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

返品

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA、SQL_INVALID_HANDLE。

Diagnostics

SQLGetDiagRec は診断記録を自ら投稿しません。 次の戻り値を使用して、独自の実行の結果を報告します。

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

• SQL_SUCCESS_WITH_INFO: *MessageText バッファは要求された診断メッセージを格納するには小さすぎました。 診断記録は作成されませんでした。 切断が発生したかどうかを判定するために、アプリケーションは BufferLength と実際の利用可能なバイト数を比較し、そのビット数は*TextLengthPtrに書き込まれます。

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

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

  • RecNumberは マイナスまたは0でした。

  • BufferLength はゼロ未満でした。

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

• SQL_NO_DATA: RecNumber が、ハンドルに指定されたハンドルに存在する診断レコードの数を超えました。 この関数は、ハンドルの診断レコードがない場合に、正の RecNumber のSQL_NO_DATAも返します。

Comments

アプリケーションは通常、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 以外を呼び出すと、HY010 "関数シーケンス エラー" が生成されます。 ただし、非同期操作が完了する前にエラー レコードを取得することはできません。

HandleType 引数

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

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

SQLGetDiagRecへの呼び出しは、HandleTypeがSQL_HANDLE_SENV(共有環境ハンドルを示す)であればSQL_INVALID_HANDLEを返します。 しかし、 HandleType がSQL_HANDLE_ENVされている場合、 Handle は共有環境ハンドルまたは非共有ハンドルのいずれかにできます。

関連関数

関連するコンテンツ

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