SQLGetDiagField 関数

準拠
導入されたバージョン: ODBC 3.0 Standards Compliance: ISO 92

まとめ
SQLGetDiagField は、エラー、警告、および状態情報を含む診断データ構造 (指定されたハンドルに関連付けられている) のレコードのフィールドの現在の値を返します。

構文

SQLRETURN SQLGetDiagField(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     DiagIdentifier,  
     SQLPOINTER      DiagInfoPtr,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLengthPtr);  

引数

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 から番号が付されます。 DiagIdentifier 引数が診断ヘッダーのフィールドを示す場合、RecNumber は無視されます。 そうでない場合は、0 を超える必要があります。

DiagIdentifier
[入力]値が返される診断のフィールドを示します。 詳細については、「コメント」の「DiagIdentifier Argument」セクションを参照してください。

DiagInfoPtr
[出力]診断情報を返すバッファーへのポインター。 データ型は 、DiagIdentifier の値によって異なります。 DiagInfoPtr が整数型の場合、アプリケーションでは SQLULEN のバッファーを使用し、この関数を呼び出す前に値を 0 に初期化する必要があります。一部のドライバーは、バッファーの下位 32 ビットまたは 16 ビットのみを書き込み、上位ビットを変更せずに残す可能性があるためです。

DiagInfoPtr が NULL の場合でも、StringLengthPtr は、DiagInfoPtr が指すバッファーで返すことができる合計バイト数 (文字データの null 終端文字を除く) を返します。

BufferLength
[入力] DiagIdentifier が ODBC 定義の診断であり、 DiagInfoPtr が 文字列またはバイナリ バッファーを指している場合、この引数は *DiagInfoPtr の長さである必要があります。 DiagIdentifier が ODBC 定義フィールドで、*DiagInfoPtr が整数の場合、BufferLength は無視されます。 *DiagInfoPtr の値が Unicode 文字列の場合 (SQLGetDiagFieldW を呼び出すとき)、BufferLength 引数は偶数である必要があります。

DiagIdentifier がドライバー定義フィールドの場合、アプリケーションは BufferLength 引数を設定することによって、ドライバー マネージャーにフィールドの性質を示します。 BufferLength には、次の値を指定できます。

• 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です。

StringLengthPtr
[出力]*DiagInfoPtr で返される文字データの合計バイト数 (null 終端文字に必要なバイト数を除く) を返すバッファーへのポインター。 返すことができるバイト数が BufferLength 以上の場合、*DiagInfoPtr 内のテキストは BufferLength から null 終端文字の長さを引いた値に切り捨てられます。

戻り値

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 は 0 未満でした。

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

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

説明

通常、アプリケーションは SQLGetDiagField を呼び出して、次の 3 つの目標のいずれかを達成します。

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 ヘッダー フィールドから)。

ODBC 関数は、呼び出されるたびに 0 個以上の診断レコードをポストできるため、アプリケーションは ODBC 関数呼び出しの後に SQLGetDiagField を呼び出すことができます。 一度に格納できる診断レコードの数に制限はありません。 SQLGetDiagField は、 Handle 引数で指定された診断データ構造に最後に関連付けられた診断情報のみを取得します。 アプリケーションが SQLGetDiagField または SQLGetDiagRec 以外の ODBC 関数を呼び出すと、同じハンドルを持つ以前の呼び出しからの診断情報は失われます。

アプリケーションは、SQLGetDiagField がSQL_SUCCESSを返す限り、RecNumber をインクリメントすることですべての診断レコードをスキャンできます。 ステータス レコードの数は、SQL_DIAG_NUMBER ヘッダー フィールドに示されます。 SQLGetDiagField の呼び出しは、ヘッダー フィールドとレコード フィールドに対して非破壊的です。 診断関数以外の関数が同じハンドルにレコードをポストする中間で呼び出されていない限り、アプリケーションは後で SQLGetDiagField を再度呼び出してレコードからフィールドを取得できます。

アプリケーションは SQLGetDiagField を呼び出して、SQL_DIAG_CURSOR_ROW_COUNTまたはSQL_DIAG_ROW_COUNTを除き、いつでも任意の診断フィールドを返すことができます。 Handle がステートメント ハンドルでない場合は、SQL_ERRORが返されます。 他の診断フィールドが未定義の場合、 SQLGetDiagField の呼び出しはSQL_SUCCESSを返し (他の診断が検出されない場合)、フィールドに対して未定義の値が返されます。

詳細については、「 SQLGetDiagRec と SQLGetDiagField の使用 」および 「SQLGetDiagRec と SQLGetDiagField の実装」を参照してください。

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

HandleType 引数

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

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

HandleType がSQL_HANDLE_ENVの場合、Handle は共有環境ハンドルまたは非共有環境ハンドルのいずれかになります。

ドライバー固有のヘッダー診断フィールドを環境ハンドルに関連付ける必要はありません。

記述子ハンドルに対して定義されている診断ヘッダー フィールドは、SQL_DIAG_NUMBERとSQL_DIAG_RETURNCODEのみです。

DiagIdentifier 引数

この引数は、診断データ構造に必要なフィールドの識別子を示します。 RecNumber が 1 以上の場合、フィールドのデータは関数によって返される診断情報を記述します。 RecNumber が 0 の場合、フィールドは診断データ構造のヘッダー内にあるため、特定の情報ではなく、診断情報を返した関数呼び出しに関連するデータが含まれます。

ドライバーは、ドライバー固有のヘッダーフィールドとレコード フィールドを診断データ構造で定義できます。

ODBC 2*.x* ドライバーを使用する ODBC 3*.x* アプリケーションは、SQL_DIAG_CLASS_ORIGIN、SQL_DIAG_CLASS_SUBCLASS_ORIGIN、SQL_DIAG_CONNECTION_NAME、SQL_DIAG_MESSAGE_TEXT、SQL_DIAG_NATIVE、SQL_DIAG_NUMBER、SQL_DIAG_RETURNCODE、SQL_DIAG_SERVER_NAME、またはSQL_DIAG_SQLSTATEの DiagIdentifier 引数でのみ SQLGetDiagField を呼び出すことができるようになります。 その他のすべての診断フィールドは、SQL_ERRORを返します。

ヘッダー フィールド

次の表に示すヘッダー フィールドは、 DiagIdentifier 引数に含めることができます。

レコード フィールド

次の表に示すレコード フィールドは、 DiagIdentifier 引数に含めることができます。

動的関数フィールドの値

次の表では、 SQLExecute または SQLExecDirect の呼び出しによって実行される SQL ステートメントの各種類に適用されるSQL_DIAG_DYNAMIC_FUNCTIONとSQL_DIAG_DYNAMIC_FUNCTION_CODEの値について説明します。 ドライバーは、一覧表示されている値にドライバー定義の値を追加できます。

状態レコードのシーケンス

状態レコードは、行番号と診断の種類に基づいてシーケンスに配置されます。 ドライバー マネージャーは、生成された状態レコードを返す最終的な順序を決定します。 ドライバーは、生成された状態レコードを返す最終的な順序を決定します。

ドライバー マネージャーとドライバーの両方によって診断レコードが投稿された場合、ドライバー マネージャーはそれらを並べ替える責任があります。

2 つ以上の状態レコードがある場合、レコードのシーケンスは最初に行番号によって決定されます。 診断レコードのシーケンスを行ごとに決定するには、次の規則が適用されます。

• 行に対応しないレコードは、特定の行に対応するレコードの前に表示されます。これは、SQL_NO_ROW_NUMBERが -1 として定義されているためです。

• 行番号が不明なレコードは、SQL_ROW_NUMBER_UNKNOWNが -2 として定義されているため、他のすべてのレコードの前に表示されます。

• 特定の行に関連するすべてのレコードについて、レコードは SQL_DIAG_ROW_NUMBER フィールドの値で並べ替えられます。 影響を受ける最初の行のすべてのエラーと警告が一覧表示され、次に影響を受ける次の行のすべてのエラーと警告が表示されます。

各行内、または行番号が不明な行番号に対応しないすべてのレコード、または行番号がSQL_NO_ROW_NUMBERと等しいすべてのレコードに対して、一連の並べ替えルールを使用して最初に一覧表示されるレコードが決定されます。 最初のレコードの後、行に影響を与える他のレコードの順序は未定義です。 アプリケーションでは、最初のレコードの後にエラーが警告の前にあると見なすことはできません。 アプリケーションは、完全な診断データ構造をスキャンして、関数の呼び出しが失敗した場合に関する完全な情報を取得する必要があります。

次のルールは、行内の最初のレコードを決定するために使用されます。 ランクが最も高いレコードが最初のレコードです。 レコードのランク付け時に、レコードのソース (ドライバー マネージャー、ドライバー、ゲートウェイなど) は考慮されません。

• エラー エラーを記述する状態レコードのランクが最も高くなります。 並べ替えエラーには、次の規則が適用されます。

  • トランザクションエラーまたは可能性のあるトランザクションエラーを示すレコードは、他のすべてのレコードを上回る。

  • 2 つ以上のレコードで同じエラー条件が記述されている場合、Open Group CLI 仕様 (クラス 03 から HZ) で定義された SQLSTATE は、ODBC とドライバー定義の SQLSTATE を上回ります。

• 実装で定義されたデータ値なし ドライバー定義の No Data 値 (クラス 02) を記述する状態レコードは、2 番目に高いランクを持ちます。

• 警告 警告を記述する状態レコード (クラス 01) のランクは最も低くなります。 2 つ以上のレコードで同じ警告条件が記述されている場合、Open Group CLI 仕様で定義された警告 SQLSTATE は、ODBC 定義とドライバー定義の SQLSTATE を上回ります。

関連する関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル