SQLGetDiagフィールド関数 (CLI)-診断データのフィールドの取得

診断データ構造フィールドの現行値を返します。 これは特定ハンドルに関連し、エラー、警告、および状況情報を含んでいます。

仕様:

  • CLI 5.0
  • ODBC 3.0
  • ISO CLI
等価 Unicode: この関数は、Unicode 文字セットとともに使用することもできます。 これに対応する Unicode 関数は SQLGetDiagFieldW() です。 ANSI 関数から Unicode 関数へのマッピングについては、 Unicode 関数 (CLI) を参照してください。

構文

SQLRETURN   SQLGetDiagField (
               SQLSMALLINT       HandleType,         /* fHandleType */
               SQLHANDLE         Handle,             /* hHandle */
               SQLSMALLINT       RecNumber,          /* iRecNumber */
               SQLSMALLINT       DiagIdentifier,     /* fDiagIdentifier */
               SQLPOINTER        DiagInfoPtr,        /* pDiagInfo */
               SQLSMALLINT       BufferLength,       /* cbDiagInfoMax */
               SQLSMALLINT       *StringLengthPtr);  /* *pcgDiagInfo */

関数引数

表 1. SQLGetDiagField 引数
データ・タイプ 引数 使用 説明
SQLSMALLINT HandleType input 診断を必要とするハンドルのタイプを記述するハンドル・タイプ ID。 以下のハンドル・タイプ ID があります。
  • SQL_HANDLE_ENV
  • SQL_HANDLE_DBC
  • SQL_HANDLE_STMT
  • SQL_HANDLE_DESC
SQLHANDLE ハンドル input HandleType で示されるタイプの、診断データ構造のハンドル。
SQLSMALLINT RecNumber input アプリケーションによって検索される情報を収めた状況レコードを指定します。 状況レコードは、1 から数えます。 診断 ID 引数が診断ヘッダー・レコードのいずれかのフィールドを示す場合、 レコード番号 は 0 でなければなりません。 そうでない場合は、0 より大きくなければなりません。
SQLSMALLINT DiagIdentifier input 値を戻す診断データ構造のフィールドを示します。 詳しくは、 DiagIdentifier 引数を参照してください。
SQLPOINTER DiagInfoポインター 出力 診断情報を返すバッファーへのポインター。 データ・タイプは、DiagIdentifier の値により異なります。
SQLINTEGER BufferLength input DiagIdentifier が ODBC 定義の診断である場合、次のようになります。
  • DiagInfoPtr が文字ストリングまたはバイナリー・バッファーを指す場合、 BufferLength は *DiagInfoPtr の長さでなければなりません。
  • *DiagInfoPtr が整数の場合、BufferLength は無視されます。
  • *DiagInfoPtr が Unicode ストリングの場合、 BufferLength は偶数でなければなりません。
DiagIdentifier が CLI 診断の場合:
  • *DiagInfoPtr が文字ストリングを指すポインターの場合、BufferLength は、そのストリングを格納するのに必要なバイト数であるか、または SQL_NTS です。
  • *DiagInfoPtr がバイナリー・バッファーを指すポインターの場合、 アプリケーションは SQL_LEN_BINARY_ATTR(length) マクロの結果を BufferLength に入れます。 それによって BufferLength は負の値になります。
  • *DiagInfoPtr が文字ストリングまたはバイナリー・ストリング以外の値を指すポインターの場合、 BufferLength の値は SQL_IS_POINTER でなければなりません。
  • *DiagInfoPtr に固定長のデータ・タイプが入っている場合、 BufferLength は状況に応じて SQL_IS_INTEGER、SQL_IS_UINTEGER、 SQL_IS_SMALLINT、 または SQL_IS_USMALLINT になります。
SQLSMALLINT * StringLengthポインター 出力 文字データの場合、*DiagInfoPtr に返すために使用できる総バイト数 (NULL 終止符文字に必要なバイト数を除く) を返すバッファーを指すポインター。 戻り値として使用できるバイト数が BufferLength 以上である場合、*DiagInfoPtr 内のテキストは BufferLength から NULL 終止符文字の長さを減算した長さに切り捨てられます。 非文字データの場合、この引数は無視されます。

使用法

一般にアプリケーションは SQLGetDiagField() を呼び出して、 以下の 3 つの目標の 1 つを成し遂げます。
  1. 関数呼び出しが SQL_ERROR または SQL_SUCCESS_WITH_INFO (または SQLBrowseConnect() 関数の場合は SQL_NEED_DATA) 戻りコードを戻したときに、特定のエラーまたは警告情報を入手する。
  2. SQLExecute()、 SQLExecDirect()、 SQLBulkOperations()、または SQLSetPos() への呼び出し (SQL_DIAG_ROW_COUNT ヘッダー・フィールドから) で挿入操作、削除操作、または更新操作が実行されたときに影響を受けたデータ・ソース内の行数を調べるか、または現行のオープン静的スクロール可能カーソル (SQL_DIAG_CURSOR_ROW_COUNT フィールドから) に存在する行数を調べる。
  3. SQLExecDirect() または SQLExecute() への呼び出し (SQL_DIAG_DYNAMIC_FUNCTION および SQL_DIAG_DYNAMIC_FUNCTION_CODE ヘッダー・フィールドから) によって実行された関数を判別します。

どの CLI 関数も、呼び出されるたびにゼロ個以上のエラーを通知する可能性があるため、アプリケーションは任意の関数呼び出しの後に SQLGetDiagField() を呼び出すことができます。 SQLGetDiagField() は、 Handle 引数に指定された診断データ構造に 最後に関連付けられた診断情報だけを取り出します。 アプリケーションが別の関数を呼び出す場合、 同一ハンドルによる直前の呼び出しの診断情報は失われます。

アプリケーションは、 SQLGetDiagField() が SQL_SUCCESS を戻す限り、 RecNumberを増分することによってすべての診断レコードをスキャンすることができます。 状況記録の数は、SQL_DIAG_NUMBER ヘッダー・フィールドに示されます。 SQLGetDiagField() への呼び出しは、 ヘッダーおよび状況レコードに関する限り非破壊です。 アプリケーションは、 SQLGetDiagField()、 SQLGetDiagRec()、または SQLError() 以外の別の関数がその間に呼び出されていない限り、後で SQLGetDiagField() を再度呼び出して、レコードからフィールドを取得することができます。これにより、同じハンドルでレコードがポストされます。

アプリケーションはいつでも SQLGetDiagField() を呼び出して何らかの診断フィールドを返すことができます。 ただし SQL_DIAG_ROW_COUNT は例外であり、この場合、Handle が、 実行された SQL ステートメントの基盤となったステートメント・ハンドルでなかった場合、 SQL_ERROR が戻されます。 他の診断フィールドが未定義の場合、 SQLGetDiagField() への呼び出しで SQL_SUCCESS が戻されます (その他のエラーが生じなかった場合)。 それから、未定義値がフィールドに対して戻されます。

HandleType 引数

それぞれのハンドル・タイプに、関連する診断情報を付けることができます。 HandleType 引数は、Handle のハンドル・タイプを表します。

すべてのハンドル・タイプ (環境、接続、ステートメント、 および記述子) のヘッダー・フィールドおよびレコード・フィールドが戻されるわけではありません。 フィールドが適用されないそれらのハンドルは、ヘッダー・フィールドおよびレコード・フィールドのセクションに示されます。

CLI固有のヘッダー診断フィールドを環境ハンドルに関連付けることはできません。

DiagIdentifier 引数

この引数は、診断データ構造にある必須フィールドの ID を示します。 RecNumber が 1 以上であれば、 フィールド内のデータは関数で返される診断情報を記述します。 RecNumber が 0 であれば、フィールドは診断データ構造のヘッダー内にあるので、 そのフィールドには診断情報 (特定情報ではない) を返した関数呼び出しに属するデータが入っています。 詳細は、DiagIdentifier 引数のヘッダーおよびレコードのフィールドのリストを参照してください。

状況レコードの順序

状況レコードは、行番号および診断のタイプに基づいた順序に並べられます。

2 つ以上の状況レコードがある場合、そのレコードの順序はまず行番号で決められます。 以下の規則は、行によるエラーの順序を決めるのに適用されます。
  • どの行にも対応していないレコードは、SQL_NO_ROW_NUMBER が -1 に定義されているので、 特定の行に対応しているレコードの前に表示されます。
  • 行番号が不明のレコードは、SQL_ROW_NUMBER_UNKNOWN が -2 に定義されているので、 他のすべてのレコードの前に表示されます。
  • 特定の行に属するすべてのレコードの場合、レコードは SQL_DIAG_ROW_NUMBER フィールドにある値でソートされます。 影響を受けた最初の行のすべてのエラーおよび警告がリストされ、それから、 影響を受けた次の行のすべてのエラーおよび警告、以下同様に示されていきます。

各行の内部で、または 1 つの行に対応していないすべてのレコードの場合、 または行番号が不明の場合には、 リストされる最初のレコードは一連のソート規則を使用して決められます。 最初のレコードの後、行に影響する他のレコードの順序は定義されていません。 アプリケーションは、最初のレコードの後、エラーが警告に優先するとみなすことはできません。 アプリケーションは、すべての診断データ構造をスキャンして、成功しなかった関数への呼び出しに関するすべての情報を得るようにしてください。

次の規則は、1 つの行の中で最初のレコードを決めるためのものです。 一番高いランクのレコードは、最初のレコードです。
  • エラー。 エラーを記述する状況レコードは、一番高いランクです。 次の規則は、エラーをソートするためのものです。
    • トランザクション障害、 または他のすべてのレコードよりランクが高いトランザクション障害の疑いを示すレコード。
    • 2 つ以上のレコードが同じエラー条件を記述している場合、X/Open CLI 仕様 (クラス 03 から HZ) で定義されている SQLSTATE は、 ODBCおよびドライバー定義の SQLSTATE よりもランクが高くなります。
  • インプリメンテーション定義の No Data 値。 CLI No Data 値 (クラス 02) を記述する状況レコードは、2 番目に高いランクを持ちます。
  • 警告。 警告 (クラス 01) を記述する状況レコードは最も低いランクです。 2 つ以上のレコードが同じ警告条件を記述している場合は、X/Open CLI 仕様で定義されている警告 SQLSTATE が、 ODBCの SQLSTATE およびドライバー定義の SQLSTATE よりも大きくなります。

戻りコード

  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE
  • SQL_NO_DATA

診断

SQLGetDiagField() は、自分自身のエラーの値を通知しません。 次の戻り値を使用して、自身の実行結果を報告します。
  • SQL_SUCCESS: 関数により、診断情報が正常に戻されました。
  • SQL_SUCCESS_WITH_INFO: *DiagInfoPtr は小さすぎて要求された診断フィールドを保持できなかったので、 診断フィールド内のデータは切り捨てられました。 切り捨てられたかどうかを判別するには、アプリケーションで、BufferLength と、*StringLengthPtr に書き込まれる、実際に使用できるバイト数を比較する必要があります。
  • SQL_INVALID_HANDLE: HandleType と Handle で示されたハンドルは有効なハンドルではありません。
  • SQL_ERROR: 考えられる原因は、以下のとおりです。
    • DiagIdentifier 引数は、有効な値の 1 つではありませんでした。
    • DiagIdentifier 引数は SQL_DIAG_CURSOR_ROW_COUNT、SQL_DIAG_DYNAMIC_FUNCTION、SQL_DIAG_DYNAMIC_FUNCTION_CODE、または SQL_DIAG_ROW_COUNT でしたが、 Handle はステートメント・ハンドルではありませんでした。
    • DiagIdentifier が診断レコードからのフィールドを示したとき、 RecNumber 引数が負か 0 でした。 RecNumber はヘッダー・フィールドには無視されました。
    • 要求された値は文字ストリングで、BufferLength はゼロ未満でした。
  • SQL_NO_DATA: RecNumber が Handle で指定されたハンドル用の診断レコード数より大きな値になっていました。 また、Handle で示されるハンドルの診断レコードがない場合は、 この関数はすべての正の RecNumber に対しても SQL_NO_DATA を戻します。

制約事項

None.