SQLGetDiagField 関数
準拠
導入されたバージョン: ODBC 3.0 標準コンプライアンス: 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 認識の開発
ハンドル
[入力]HandleTypeで示される型の診断データ構造のハンドル。 HandleType
RecNumber
[入力]アプリケーションが情報をシークする状態レコードを示します。 状態レコードには 1 から番号が付けられます。
DiagIdentifier
[入力]値が返される診断のフィールドを示します。 詳細については、「コメント」の「DiagIdentifier 引数」セクションを参照してください。
DiagInfoPtr
[出力]診断情報を返すバッファーへのポインター。 データ型は、DiagIdentifierの値によって異なります。 DiagInfoPtr
DiagInfoPtr
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
収益
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 が、ハンドルに指定されたハンドルに存在する診断レコードの数を超えました。 この関数は、ハンドルの診断レコードがない場合に、正の RecNumber のSQL_NO_DATAも返します。
コメント
アプリケーションは、通常、SQLGetDiagField を呼び出して、次の 3 つの目標のいずれかを達成します。
関数呼び出しがSQL_ERRORまたはSQL_SUCCESS_WITH_INFO (または SQLBrowseConnect 関数のSQL_NEED_DATA) を返したときに、特定のエラーまたは警告情報を取得します。
SQLExecute、
SQLExecDirect 、SQLBulkOperations 、または (SQL_DIAG_ROW_COUNT ヘッダー フィールドから) SQLSetPos を する呼び出しで、挿入、削除、または更新操作が実行されたときに影響を受けたデータ ソース内の行数を確認したり、現在開いているカーソルに存在する行数を決定したりするには、 ドライバーがこの情報を提供できる場合は (SQL_DIAG_CURSOR_ROW_COUNT ヘッダー フィールドから)。 SQLExecDirect または (SQL_DIAG_DYNAMIC_FUNCTION および SQL_DIAG_DYNAMIC_FUNCTION_CODE ヘッダー フィールドから) SQLExecute を
呼び出しによって実行された関数を特定します。
ODBC 関数は、呼び出されるたびに 0 個以上の診断レコードをポストできるため、アプリケーションは ODBC 関数呼び出し後に SQLGetDiagField
アプリケーションは、SQL_SUCCESSを返す SQLGetDiagField
アプリケーション
詳細については、「
非同期で実行されている API 以外を呼び出すと、HY010 "関数シーケンス エラー" が生成されます。 ただし、非同期操作が完了する前にエラー レコードを取得することはできません。
HandleType 引数
各ハンドルの種類には、診断情報を関連付けることができます。
一部のヘッダーおよびレコード フィールドは、環境、接続、ステートメント、および記述子ハンドルに対して返すことができません。 フィールドが適用できないハンドルは、後の「ヘッダーフィールド」および「レコードフィールド」セクションに示されています。
HandleType がSQL_HANDLE_ENVされている場合、ハンドル は、共有環境ハンドルまたは非共有環境ハンドルにすることができます。
ドライバー固有のヘッダー診断フィールドを環境ハンドルに関連付ける必要はありません。
記述子ハンドルに対して定義されている診断ヘッダー フィールドは、SQL_DIAG_NUMBERとSQL_DIAG_RETURNCODEのみです。
DiagIdentifier 引数
この引数は、診断データ構造に必要なフィールドの識別子を示します。 RecNumber
ドライバーは、ドライバー固有のヘッダーフィールドとレコード フィールドを診断データ構造で定義できます。
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の DiagIdentifier 引数でのみ、SQLGetDiagField を呼び出すことが可能です。 またはSQL_DIAG_SQLSTATE。 その他のすべての診断フィールドは、SQL_ERRORを返します。
ヘッダー フィールド
次の表に示すヘッダー フィールドは、DiagIdentifier 引数に含めることができます。
| DiagIdentifier | 戻り値の型 | 収益 |
|---|---|---|
| SQL_DIAG_CURSOR_ROW_COUNT | SQLLEN | このフィールドには、カーソル内の行数が含まれます。 そのセマンティクスは、SQL_DYNAMIC_CURSOR_ATTRIBUTES2、SQL_FORWARD_ONLY_CURSOR_ATTRIBUTES2、SQL_KEYSET_CURSOR_ATTRIBUTES2、およびSQL_STATIC_CURSOR_ATTRIBUTES2の SQLGetInfo 情報の種類によって異なります。これは、カーソルの種類 (SQL_CA2_CRC_EXACT ビットとSQL_CA2_CRC_APPROXIMATE ビット) ごとに使用できる行数を示します。 このフィールドの内容は、ステートメント ハンドルに対してのみ定義され、SQLExecute |
| SQL_DIAG_DYNAMIC_FUNCTION | SQLCHAR * | これは、基になる関数が実行した SQL ステートメントを記述する文字列です。 (特定の値については、このセクションで後述する「動的関数フィールドの値」を参照してください)。このフィールドの内容は、ステートメント ハンドルに対してのみ定義され、SQLExecute、 |
| SQL_DIAG_DYNAMIC_FUNCTION_CODE | SQLINTEGER | これは、基になる関数によって実行された SQL ステートメントを記述する数値コードです。 (特定の値については、このセクションで後述する「動的関数フィールドの値」を参照してください)。このフィールドの内容は、ステートメント ハンドルに対してのみ定義され、SQLExecute、 |
| SQL_DIAG_NUMBER | SQLINTEGER | 指定したハンドルで使用できる状態レコードの数。 |
| SQL_DIAG_RETURNCODE | SQLRETURN | 関数によって返されるコードを返します。 リターン コードの一覧については、「リターン コード |
| SQL_DIAG_ROW_COUNT | SQLLEN | SQLExecute、 |
レコード フィールド
次の表に示すレコード フィールドは、DiagIdentifier 引数に含めることができます。
| DiagIdentifier | 戻り値の型 | 収益 |
|---|---|---|
| SQL_DIAG_CLASS_ORIGIN | SQLCHAR * | このレコードの SQLSTATE 値のクラス部分を定義するドキュメントを示す文字列。 その値は、Open Group および ISO 呼び出しレベル のインターフェイスで定義されているすべての SQLSTATEs に対して "ISO 9075" です。 ODBC 固有の SQLSTATEs (SQLSTATE クラスが "IM" であるすべてのユーザー) の場合、その値は "ODBC 3.0" です。 |
| SQL_DIAG_COLUMN_NUMBER | SQLINTEGER | SQL_DIAG_ROW_NUMBERフィールドが行セットまたはパラメーターのセット内の有効な行番号である場合、このフィールドには、結果セット内の列番号またはパラメーターのセット内のパラメーター番号を表す値が含まれます。 結果セットの列番号は常に 1 から始まります。この状態レコードがブックマーク列に関連する場合は、フィールドを 0 にすることができます。 パラメーター番号は 1 から始まります。 状態レコードが列番号またはパラメーター番号に関連付けられていない場合は、SQL_NO_COLUMN_NUMBER値が含まれます。 このレコードが関連付けられている列番号またはパラメーター番号をドライバーが判断できない場合、このフィールドの値はSQL_COLUMN_NUMBER_UNKNOWN。 このフィールドの内容は、ステートメント ハンドルに対してのみ定義されます。 |
| SQL_DIAG_CONNECTION_NAME | SQLCHAR * | 診断レコードが関連付けられている接続の名前を示す文字列。 このフィールドはドライバー定義です。 環境ハンドルに関連付けられている診断データ構造と、接続に関連しない診断の場合、このフィールドは長さ 0 の文字列です。 |
| SQL_DIAG_MESSAGE_TEXT | SQLCHAR * | エラーまたは警告に関する情報メッセージ。 このフィールドは、「診断メッセージの |
| SQL_DIAG_NATIVE | SQLINTEGER | ドライバー/データ ソース固有のネイティブ エラー コード。 ネイティブ エラー コードがない場合、ドライバーは 0 を返します。 |
| SQL_DIAG_ROW_NUMBER | SQLLEN | このフィールドには、行セット内の行番号、または状態レコードが関連付けられているパラメーターのセット内のパラメーター番号が含まれます。 行番号とパラメーター番号は 1 から始まります。 このフィールドには、この状態レコードが行番号またはパラメーター番号に関連付けられていない場合にSQL_NO_ROW_NUMBER値があります。 このレコードが関連付けられている行番号またはパラメーター番号をドライバーが判断できない場合、このフィールドには値SQL_ROW_NUMBER_UNKNOWN。 このフィールドの内容は、ステートメント ハンドルに対してのみ定義されます。 |
| SQL_DIAG_SERVER_NAME | SQLCHAR * | 診断レコードが関連するサーバー名を示す文字列。 これは、SQL_DATA_SOURCE_NAME オプションを使用して SQLGetInfo |
| SQL_DIAG_SQLSTATE | SQLCHAR * | 5 文字の SQLSTATE 診断コード。 詳細については、「SQLSTATEs」を参照してください。 |
| SQL_DIAG_SUBCLASS_ORIGIN | SQLCHAR * | SQLSTATE コードのサブクラス部分の定義部分を識別する、SQL_DIAG_CLASS_ORIGINと同じ形式および有効な値を持つ文字列。 "ODBC 3.0" が返される ODBC 固有の SQLSTATES には、次のものが含まれます。 01S00、01S01、01S02、01S06、01S07、07S01、 08S01、21S01、21S02、25S01、25S02、25S03、42S01、42S02、42S11、42S12、42S21、42S22、HY095、HY097、HY098、HY0999、HY099 HY100、HY101、HY105、HY107、HY109、HY110、HY111、HYT00、HYT01、IM001、IM002、IM003、IM004、IM005、IM006、IM007、IM008、IM010、IM011、IM012。 |
動的関数フィールドの値
次の表では、SQLExecute または SQLExecDirectの呼び出しによって実行される各種類の SQL ステートメントに適用される
| SQL ステートメント 実行 |
の値 SQL_DIAG_DYNAMIC_FUNCTION |
の値 SQL_DIAG_DYNAMIC_FUNCTION_CODE |
|---|---|---|
| alter-domain-statement を |
"ALTER DOMAIN" | SQL_DIAG_ALTER_DOMAIN |
| alter-table-statement を |
"ALTER TABLE" | SQL_DIAG_ALTER_TABLE |
| アサーション定義 を |
"CREATE ASSERTION" | SQL_DIAG_CREATE_ASSERTION |
| 文字セット定義 を |
"CREATE CHARACTER SET" | SQL_DIAG_CREATE_CHARACTER_SET |
| 照合順序定義 を |
"照合順序の作成" | SQL_DIAG_CREATE_COLLATION |
| ドメイン定義 を |
"CREATE DOMAIN" | SQL_DIAG_CREATE_DOMAIN |
| create-index-statement を |
"CREATE INDEX" | SQL_DIAG_CREATE_INDEX |
| create-table-statement を |
"CREATE TABLE" | SQL_DIAG_CREATE_TABLE |
| create-view-statement を |
"CREATE VIEW" | SQL_DIAG_CREATE_VIEW |
| カーソル指定 | "SELECT CURSOR" | SQL_DIAG_SELECT_CURSOR |
| delete-statement 位置指定 を |
"DYNAMIC DELETE CURSOR" | SQL_DIAG_DYNAMIC_DELETE_CURSOR |
| delete-statement-searched を |
"DELETE WHERE" | SQL_DIAG_DELETE_WHERE |
| drop-assertion-statement を |
"DROP ASSERTION" | SQL_DIAG_DROP_ASSERTION |
| drop-character-set-stmt の |
"DROP CHARACTER SET" | SQL_DIAG_DROP_CHARACTER_SET |
| drop-collation-statement を |
"DROP COLLATION" | SQL_DIAG_DROP_COLLATION |
| drop-domain-statement を |
"DROP DOMAIN" | SQL_DIAG_DROP_DOMAIN |
| drop-index-statement を |
"DROP INDEX" | SQL_DIAG_DROP_INDEX |
| drop-schema-statement を |
"DROP SCHEMA" | SQL_DIAG_DROP_SCHEMA |
| drop-table-statement を |
"DROP TABLE" | SQL_DIAG_DROP_TABLE |
| drop-translation-statement を |
"DROP TRANSLATION" | SQL_DIAG_DROP_TRANSLATION |
| drop-view-statement を |
"DROP VIEW" | SQL_DIAG_DROP_VIEW |
| grantstatement を |
"GRANT" | SQL_DIAG_GRANT |
| insert-statement を |
"INSERT" | SQL_DIAG_INSERT |
| ODBC-procedure-extension の |
"CALL" | SQL_DIAG_呼び出し |
| revoke-statement | "REVOKE" | SQL_DIAG_REVOKE |
| スキーマ定義 を |
"CREATE SCHEMA" | SQL_DIAG_CREATE_SCHEMA |
| 翻訳定義 を |
"CREATE TRANSLATION" | SQL_DIAG_CREATE_TRANSLATION |
| update-statement で配置された を |
"DYNAMIC UPDATE CURSOR" | SQL_DIAG_DYNAMIC_UPDATE_CURSOR |
| update-statement で検索された を |
"UPDATE WHERE" | SQL_DIAG_UPDATE_WHERE |
| 不明 | 空の文字列 を |
SQL_DIAG_UNKNOWN_STATEMENT |
状態レコードのシーケンス
状態レコードは、行番号と診断の種類に基づいてシーケンスに配置されます。 ドライバー マネージャーは、生成された状態レコードを返す最終的な順序を決定します。 ドライバーは、生成された状態レコードを返す最終的な順序を決定します。
ドライバー マネージャーとドライバーの両方によって診断レコードが投稿された場合、ドライバー マネージャーはそれらを並べ替える役割を担います。
2 つ以上の状態レコードがある場合、レコードのシーケンスは最初に行番号によって決定されます。 次の規則は、行ごとの診断レコードのシーケンスの決定に適用されます。
SQL_NO_ROW_NUMBERは -1 と定義されているため、どの行にも対応しないレコードは、特定の行に対応するレコードの前に表示されます。
行番号が不明なレコードは、SQL_ROW_NUMBER_UNKNOWNが -2 として定義されているため、他のすべてのレコードの前に表示されます。
特定の行に関連するすべてのレコードについて、レコードは SQL_DIAG_ROW_NUMBER フィールドの値で並べ替えられます。 影響を受ける最初の行のすべてのエラーと警告が一覧表示され、次に影響を受ける次の行のすべてのエラーと警告が表示されます。
手記
ODBC 3*.x* ドライバー マネージャーは、ODBC 2*.x* ドライバーから SQLSTATE 01S01 (行内エラー) が返された場合、または SQLSTATE 01S01 (行内エラー) が返された場合、診断キューの状態レコードを並べ替えません SQLExtendedFetch
各行内、または行番号が不明な行に対応していないすべてのレコード、または行番号がSQL_NO_ROW_NUMBERと等しいすべてのレコードの場合、一連の並べ替えルールを使用して、最初に一覧表示されるレコードが決定されます。 最初のレコードの後、行に影響を与える他のレコードの順序は未定義です。 アプリケーションでは、最初のレコードの後にエラーが警告の前にあると見なすことはできません。 アプリケーションは、完全な診断データ構造をスキャンして、関数の呼び出しが失敗した場合に関する完全な情報を取得する必要があります。
次のルールは、行内の最初のレコードを決定するために使用されます。 ランクが最も高いレコードが最初のレコードです。 レコードのソース (ドライバー マネージャー、ドライバー、ゲートウェイなど) は、レコードのランク付け時には考慮されません。
エラー 状態レコード。エラーを記述するレコードのランクが最も高くなります。 並べ替えエラーには、次の規則が適用されます。
トランザクションエラーまたはトランザクションエラーの可能性を示すレコードは、他のすべてのレコードを上回る。
2 つ以上のレコードで同じエラー条件が記述されている場合、Open Group CLI 仕様 (クラス 03 から HZ) によって定義された SQLSTATEs は、ODBC とドライバー定義の SQLSTATEs を上回っています。
ドライバー定義の No Data 値 (クラス 02) を記述する実装定義のデータ値なし 状態レコードは、2 番目に高いランクを持ちます。
警告 警告を記述する状態レコード (クラス 01) のランクが最も低い。 2 つ以上のレコードで同じ警告条件が記述されている場合は、Open Group CLI 仕様で定義された警告 SQLSTATEs が、ODBC で定義された SQLSTATEs とドライバー定義の SQLSTATEs を上回っています。
関連関数
| 詳細については、次の情報を参照してください。 | 見る |
|---|---|
| 診断データ構造の複数のフィールドの取得 | SQLGetDiagRec 関数 の |
関連項目
ODBC API リファレンス
ODBC ヘッダー ファイル の