SQLGetDiagRec() - 診断レコードの複数のフィールド設定値を取得する

SQLGetDiagRec() は、診断レコードの複数のフィールドの現行値を戻します。この診断レコードには エラー、警告、および状況情報が含まれています。SQLGetDiagRec() は、SQLSTATE、ネイティブなエラー・コード、およびエラー・メッセージ・テキストを含む、一般に使用される診断レコードのフィールドをいくつか戻します。

SQLGetDiagRec() の ODBC 仕様

表 1. SQLGetDiagRec() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
3.0 あり あり

構文

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

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLGetDiagRec() の引数
データ・タイプ 引数 使用法 説明
SQLSMALLINT HandleType 入力 診断するハンドルのタイプを示すハンドル・タイプ ID を指定します。 この引数では、次のいずれかの値を指定する必要があります。
  • SQL_HANDLE_ENV -- 環境ハンドルの場合
  • SQL_HANDLE_DBC -- 接続ハンドルの場合
  • SQL_HANDLE_STMT -- ステートメント・ハンドルの場合
SQLHANDLE Handle 入力 診断データ構造のハンドルを指定します。 このハンドルは、引数 HandleType が示すハンドルのタイプでなければなりません。
SQLSMALLINT RecNumber 入力 アプリケーションがそこから情報を求める状況レコードを示します。 状況レコードは 1 から番号が付けられます。
SQLCHAR * SQLState 出力 バッファーへのポインターで、そのバッファーには 5 文字の SQLSTATE が戻されます。この SQLSTATE は引数 RecNumber に指定された診断レコードに対応します。この SQLSTATE の最初の 2 文字は クラスを示し、次の 3 文字はサブクラスを示しています。
SQLINTEGER * NativeErrorPtr 出力 データ・ソース固有のネイティブ・エラー・コードを戻すバッファーを指しています。
SQLCHAR * MessageText 出力 エラー・メッセージ・テキストを戻す先のバッファーを指しています。SQLGetDiagRec() により 戻されたフィールドは、テキスト・ストリング内に含まれます。
SQLSMALLINT BufferLength 入力 引数 MessageText が指定するバッファーの長さ (バイト)。
SQLSMALLINT * TextLengthPtr 出力 MessageText 引数によって指示されるバッファー内の、使用可能な合計バイト数を格納するバッファーへのポインター。使用可能な合計バイト数には、NUL 終了文字のバイト数は含まれません。戻すのに使用可能なバイト数が引数 BufferLength で指定する値より大きい場合、 そのバッファー内のエラー・メッセージ・テキストは、引数 BufferLength から NUL 終了文字 の長さを引いたものに切り捨てられます。

使用法

直前に呼び出された Db2® ODBC 関数が SQL_SUCCESS 以外を戻した場合、 アプリケーションは、通常は、SQLGetDiagRec() を呼び出します。 ただし、どの関数も呼び出されるたびにエラーなし、または 1 つ以上のエラーを通知する 可能性があるため、アプリケーションはどの関数呼び出し後でも SQLGetDiagRec() を呼び出すことができます。アプリケーションは SQLGetDiagRec() を複数回呼び出して、 診断データ構造の一部のレコードまたは全レコードを戻すことができます。

SQLGetDiagRec() は、上記の引数 Handle に指定されたハンドルに 関連した最新の診断情報のみを取り出します。アプリケーションが、SQLGetDiagRec() (または ODBC 2.0 の SQLGetDiagRec() 関数) を除くいずれの 他関数を呼び出しても、同じハンドルにある直前の呼び出しからの診断情報はすべて失われてしまいます。

アプリケーションは、SQLGetDiagRec() が SQL_SUCCESS を戻す間、RecNumber を増やしながら スキャンを繰り返すことによって、すべての診断レコードをスキャンできます。

SQLGetDiagRec() への呼び出しにより、診断レコード・フィールドが損なわれることはありません。アプリケーションは、SQLGetDiagRec() (または ODBC 2.0 の SQLGetDiagRec() 関数) を除く他の関数 がその間で呼び出されない限り、後でもう一度 SQLGetDiagRec() を呼び出して、レコードからフィールドを取り出すことができます。

戻りコード

SQLGetDiagRec() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_INVALID_HANDLE
  • SQL_ERROR
それぞれの戻りコード値の説明については、診断を 参照してください。

診断

SQLGetDiagRec() は、エラー値を通知しません。関数の戻りコードを使用して、 診断情報を報告します。SQLGetDiagRec() を呼び出した場合、 以下の戻りコードが診断情報を表しています。
  • SQL_SUCCESS: 関数は正常に診断情報を戻しました。
  • SQL_SUCCESS_WITH_INFO: 引数 MessageText が指しているバッファーは、 必要な診断メッセージを収容するには小さすぎます。診断レコードは生成されません。 切り捨てが起こったかどうかを判断するには、引数 BufferLength に 指定した値と実際に使用可能なバイト数 (引数 TextLengthPtr の指す バッファーに書き込まれている) とを比較します。
  • SQL_INVALID_HANDLE: HandleType および Handle によって示されたハンドルは 有効ではありません。
  • SQL_ERROR: 次のいずれかが起こりました。
    • 引数 RecNumber が負、または 0 です。
    • 引数 BufferLength がゼロより小です。
  • SQL_NO_DATA: 引数 RecNumber は、引数 Handle で指定されたハンドル に存在する診断レコード数よりも大きい値です。 また、引数 Handle が指定するハンドルに対して診断レコードが生成されない場合は、 この関数はどの正の引数 RecNumber に対しても SQL_NO_DATA を戻します。

例

サンプル・アプリケーション DSN8O3VP、あるいはデータ・セット DSN1110.SDSNSAMP のオンラインを参照してください。