仕様: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLGetDiagField() は、診断データ構造フィールドの現行値を返します。これは特定ハンドルに関連し、エラー、警告、および状況情報を含んでいます。
構文
SQLRETURN SQLGetDiagField (SQLSMALLINT HandleType, SQLHANDLE Handle, SQLSMALLINT RecNumber, SQLSMALLINT DiagIdentifier, SQLPOINTER DiagInfoPtr, SQLSMALLINT BufferLength, SQLSMALLINT *StringLengthPtr);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLSMALLINT | HandleType | 入力 | 診断するハンドルのタイプを記述するハンドル・タイプ識別子。以下のうちの 1 つでなければなりません。
|
SQLHANDLE | Handle | 入力 | HandleType で示されるタイプの、診断データ構造のハンドル。 |
SQLSMALLINT | RecNumber | 入力 | アプリケーションが情報を求める状況レコード。状況レコードは 1 から番号が付けられます。 DiagIdentifier 引き数が診断ヘッダー・レコードのフィールドを示す場合、 RecNumber は 0 となります。そうでない場合、0 より大きい数になります。 |
SQLSMALLINT | DiagIdentifier | 入力 | 値を戻したい診断データ構造のフィールドを示します。詳細については、『DiagIdentifier 引き数』を参照してください。 |
SQLPOINTER | DiagInfoPtr | 出力 | 診断情報を返すバッファーへのポインター。データ・タイプは DiagIdentifier の値によります。 |
SQLINTEGER | BufferLength | 入力 | DiagInfoPtr が文字ストリングを指す場合、この引き数の長さは *ValuePtr です。 ValuePtr がポインターである (しかしストリングに対するものではない) 場合、 BufferLength の値は SQL_IS_POINTER となります。 ValuePtr がポインターでない場合には、 BufferLength の値は SQL_IS_NOT_POINTER となります。 *DiagInfoPtr の値が Unicode ストリングの場合、 BufferLength 引き数は偶数でなければなりません。 |
SQLSMALLINT | *StringLengthPtr | 出力 | *DiagInfoPtr に戻すために使用できる総バイト数 (ヌル終了文字に必要なバイト数を除く) を戻すバッファーを指すポインター (文字データ用)。戻りに使用できるバイト数が BufferLength より大きい場合、 *DiagInfoPtr 内のテキストは BufferLength からヌル終了文字の長さを引いた長さまで切り捨てられます。非文字データの場合、この引き数は無視されます。 |
使用法
一般にアプリケーションは SQLGetDiagField() を呼び出して、以下の 3 つの目標の 1 つを成し遂げます。
DB2 CLI 関数のどれかが呼び出されるたびに 0 個以上のエラーを通知できるので、アプリケーションは任意の関数呼び出しの後に 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 のハンドル・タイプを表します。
すべてのハンドル・タイプ (環境、接続、ステートメント、および記述子) のヘッダー・フィールドおよびレコード・フィールドが戻されるわけではありません。フィールドが適用されないそれらのハンドルは、ヘッダー・フィールドおよびレコード・フィールドのセクションの下に示されます。
DB2 CLI 特定のヘッダー診断フィールドは、環境ハンドルと関連することはありません。
この引き数は、診断データ構造にある希望するフィールドの識別子を示します。 RecNumber が 1 以上であれば、フィールド内のデータは関数で返される診断情報を記述します。 RecNumber が 0 であれば、フィールドは診断データ構造のヘッダー内にあります。そして、そのフィールドには診断情報 (特定情報ではない) を返した関数呼び出しに属するデータが入っています。
以下のヘッダー・フィールドを、 DiagIdentifier 引き数に組み込むことができます。記述子フィールドに定義されている唯一の診断ヘッダー・フィールドは、 SQL_DIAG_NUMBER および SQL_DIAG_RETURNCODE です。
表 103. DiagIdentifier 引き数のヘッダー・フィールド
SQL_DIAG_CURSOR_ROW_COUNT (戻りタイプ SQLINTEGER) | |
|
このフィールドは、カーソルにある行のカウントを含みます。そのセマンティクスは、SQLGetInfo() 情報タイプに依存しています。
これらは、それぞれのカーソル・タイプごとにどの行カウントが使用可能かを示しています (SQL_CA2_CRC_EXACT および SQL_CA2_CRC_APPROXIMATE ビットにおいて)。
このフィールドの内容は、ステートメント・ハンドルに対してのみ定義され、 SQLExecute()、SQLExecDirect()、または SQLMoreResults() が呼び出されてから定義されます。ステートメント・ハンドル以外で、 SQL_DIAG_CURSOR_ROW_COUNT の DiagIdentifier を指定して SQLGetDiagField() を呼び出すと、 SQL_ERROR が返されます。
|
SQL_DIAG_DYNAMIC_FUNCTION (戻りタイプ CHAR *) | |
|
これは基礎となる関数が実行した SQL ステートメントを記述する文字列です (DB2 CLI がサポートしている値については、 『動的関数フィールド』を参照してください)。このフィールドの内容は、ステートメント・ハンドルに対してのみ定義され、なおかつ SQLExecute() または SQLExecDirect() への呼び出しがなされた後に定義されます。このフィールドの値は、 SQLExecute() または SQLExecDirect() への呼び出し前には定義されていません。
|
SQL_DIAG_DYNAMIC_FUNCTION_CODE (戻りタイプ SQLINTEGER) | |
|
これは基礎となる関数が実行した SQL ステートメントを記述する数字コードです (DB2 CLI がサポートしている値については、 『動的関数フィールド』を参照してください)。このフィールドの内容は、ステートメント・ハンドルに対してのみ定義され、なおかつ SQLExecute() または SQLExecDirect() への呼び出しがなされた後に定義されます。このフィールドの値は、SQLExecute()、SQLExecDirect()、または SQLMoreResults() への呼び出し前には定義されていません。ステートメント・ハンドル以外で、 SQL_DIAG_DYNAMIC_FUNCTION_CODE の DiagIdentifier を指定して SQLGetDiagField() を呼び出すと、 SQL_ERROR が返されます。このフィールドの値は、 SQLExecute() または SQLExecDirect() への呼び出し前には定義されていません。
|
SQL_DIAG_NUMBER (戻りタイプ SQLINTEGER) | |
|
指定されたハンドルで使用可能な状況レコードの数です。
|
SQL_DIAG_RETURNCODE (戻りタイプ RETCODE) | |
|
指定されたハンドルに関連した、最後に実行された関数により返される戻りコード。戻りコードの一覧については、関数戻りコードを参照してください。 Handle でまだ何の関数も呼び出されていなければ、 SQL_DIAG_RETURNCODE には SQL_SUCCESS が返されます。
|
SQL_DIAG_ROW_COUNT (戻りタイプ SQLINTEGER) | |
|
SQLExecute()、SQLExecDirect()、または
SQLSetPos() により実行される、挿入、削除、または更新で影響を受ける行数。これはカーソル指定が実行された後で定義されます。このフィールドの内容は、ステートメント・ハンドルでのみ定義されます。フィールド内のデータは、SQLRowCount() の RowCountPtr 引き数に返されます。フィールド内のデータは毎回の関数呼び出し後にリセットされますが、
SQLRowCount() で返される行カウントは、ステートメントが準備済みまたは割り当てられた状態に戻されるまでは同じ状態に保たれます。
|
以下のレコード・フィールドを、DiagIdentifier 引き数に組み込むことができます。
表 104. DiagIdentifier 引き数のレコード・フィールド
SQL_DIAG_CLASS_ORIGIN (戻りタイプ CHAR *) | |
|
このレコードにある SQLSTATE 値のクラスおよびサブクラス部分を定義する文書を示すストリング。 DB2 CLI は常に SQL_DIAG_CLASS_ORIGIN に空ストリングを返します。
|
SQL_DIAG_COLUMN_NUMBER (戻りタイプ SQLINTEGER) | |
|
SQL_DIAG_ROW_NUMBER フィールドで、行セットまたはパラメーター・セットにある行数が有効である場合、そのフィールドには結果セット内の列番号を示す値が入ります。結果セットの列番号は常に 1 で始まります。この状況レコードがブックマーク列に関するものであれば、フィールドはゼロになる可能性があります。状況レコードが列番号に関連していない場合には、その値は SQL_NO_COLUMN_NUMBER となります。 DB2 CLI がこのレコードに関連している列番号を判別できなければ、フィールド値は SQL_COLUMN_NUMBER_UNKNOWN となります。このフィールドの内容は、ステートメント・ハンドルでのみ定義されます。
|
SQL_DIAG_CONNECTION_NAME (戻りタイプ CHAR *) | |
|
診断レコードが関連する接続の名前を示すストリング。 DB2 CLI は常に SQL_DIAG_CONNECTION_NAME に空ストリングを返します。
|
SQL_DIAG_MESSAGE_TEXT (戻りタイプ CHAR *) | |
|
エラーまたは警告に関する通知メッセージ。
|
SQL_DIAG_NATIVE (戻りタイプ SQLINTEGER) | |
|
ドライバー / データ・ソース指定の固有エラー・コード。固有のエラー・コードがなければ、ドライバーは 0 を返します。
|
SQL_DIAG_ROW_NUMBER (戻りタイプ SQLINTEGER) | |
|
このフィールドには、状況レコードに関連している、行セットにある行番号 (または、パラメーター・セットにあるパラメーター番号) が入ります。この状況レコードが行番号に関連していない場合には、フィールド値は SQL_NO_ROW_NUMBER となります。 DB2 CLI がこのレコードに関連している行番号を判別できなければ、フィールド値は SQL_ROW_NUMBER_UNKNOWN となります。このフィールドの内容は、ステートメント・ハンドルでのみ定義されます。
|
SQL_DIAG_SERVER_NAME (戻りタイプ CHAR *) | |
|
診断レコードが関連するサーバー名を示すストリング。これは、InfoType に SQL_DATA_SOURCE_NAME を指定した SQLGetInfo() 呼び出しで返される値と同じです。環境ハンドルに関連する診断データ構造の場合、およびどのサーバーにも関連しない診断の場合、このフィールドはゼロ長ストリングです。
|
SQL_DIAG_SQLSTATE (戻りタイプ CHAR *) | |
|
5 文字の SQLSTATE 診断コード。
|
SQL_DIAG_SUBCLASS_ORIGIN (戻りタイプ CHAR *) | |
|
SQL_DIAG_CLASS_ORIGIN と同じ形式および有効値のストリング。これは、SQLSTATE コードのサブクラスの定義部分を識別します。
DB2 CLI は常に SQL_DIAG_SUBCLASS_ORIGIN に空ストリングを返します。
|
以下の表は、 SQL_DIAG_DYNAMIC_FUNCTION と SQL_DIAG_DYNAMIC_FUNCTION_CODE の値を示しています。これらは、 SQLExecute() または SQLExecDirect() への呼び出しで実行される各タイプの SQL ステートメントに適用されます。これは DB2 CLI が使用するリストであり、ODBC では、その他の値も指定します。
実行される SQL ステートメント | SQL_DIAG_ DYNAMIC_FUNCTION の値 | SQL_DIAG_DYNAMIC_ FUNCTION_CODE の値 |
---|---|---|
alter-table-statement | "ALTER TABLE" | SQL_DIAG_ALTER_TABLE |
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 |
cursor-specification | "SELECT CURSOR" | SQL_DIAG_SELECT_CURSOR |
delete-statement-positioned | "DYNAMIC DELETE CURSOR" |
SQL_DIAG_DYNAMIC_DELETE_ CURSOR |
delete-statement-searched | "DELETE WHERE" | SQL_DIAG_DELETE_WHERE |
drop-index-statement | "DROP INDEX" | SQL_DIAG_DROP_INDEX |
drop-table-statement | "DROP TABLE" | SQL_DIAG_DROP_TABLE |
drop-view-statement | "DROP VIEW" | SQL_DIAG_DROP_VIEW |
grant-statement | "GRANT" | SQL_DIAG_GRANT |
insert-statement | "INSERT" | SQL_DIAG_INSERT |
ODBC-procedure-extension | "CALL" | SQL_DIAG_PROCEDURE_CALL |
revoke-statement | "REVOKE" | SQL_DIAG_REVOKE |
update-statement-positioned | "DYNAMIC UPDATE CURSOR" |
SQL_DIAG_DYNAMIC_UPDATE_ CURSOR |
update-statement-searched | "UPDATE WHERE" | SQL_DIAG_UPDATE_WHERE |
不明 | 空ストリング | SQL_DIAG_UNKNOWN_STATEMENT |
状況レコードは、行番号および診断のタイプに基づいた順序に並べられます。
2 つ以上の状況レコードがある場合、そのレコードの順序はまず行番号で決められます。以下の規則は、行によるエラーの順序を決めるのに適用されます。
各行の内部で、または 1 つの行に対応していないすべてのレコードの場合、または行番号が不明の場合には、リストされる最初のレコードは一連のソート規則を使用して決められます。最初のレコードの後、影響する他のレコードの順序は定義されていません。アプリケーションは、最初のレコードの後、エラーが警告に優先するとみなすことはできません。アプリケーションは、すべての診断データ構造を走査して、成功しなかった関数への呼び出しに関するすべての情報を得るようにしてください。
次の規則は、1 つの行の中で最初のレコードを決めるためのものです。一番高いランクのレコードは、最初のレコードです。
戻りコード
診断
SQLGetDiagField() は、自分自身のエラーの値を通知しません。次の戻り値を使用して、自身の実行結果を報告します。
制約
なし。
例
該当するサンプルの一覧については、 sqllib\samples\cli (または sqllib/samples/cli) サブディレクトリー内の README ファイルを参照してください。
参照