CLI の手引きおよび解説書

SQLGetDiagField - 診断データのフィールドの入手

目的


仕様: 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);

関数引き数

表 102. SQLGetDiagField 引き数
データ・タイプ 引き数 使用法 説明
SQLSMALLINT HandleType 入力 診断するハンドルのタイプを記述するハンドル・タイプ識別子。以下のうちの 1 つでなければなりません。
  • SQL_HANDLE_ENV
  • SQL_HANDLE_DBC
  • SQL_HANDLE_STMT
  • SQL_HANDLE_DESC
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 つを成し遂げます。

  1. 関数呼び出しで SQL_ERROR または SQL_SUCCESS_WITH_INFO (あるいは、 SQLBrowseConnect() 関数の SQL_NEED_DATA) が戻されたとき、特定のエラーまたは警告情報を得る。
  2. SQLExecute() または SQLExecDirect() への呼び出しで、挿入、削除 (DEL)、または更新操作が行われた時点で影響を受けるデータ・ソースの行数を検出する (SQL_DIAG_ROW_COUNT ヘッダー・フィールドから)。あるいは、現在開いている静的なスクロール可能カーソルにある行数を検出する (SQL_DIAG_CURSOR_ROW_COUNT ヘッダー・フィールドから)。
  3. SQLExecDirect() または SQLExecute() への呼び出しでどの関数が実行されたかを判別する (SQL_DIAG_DYNAMIC_FUNCTION および SQL_DIAG_DYNAMIC_FUNCTION_CODE ヘッダー・フィールドから)。

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 特定のヘッダー診断フィールドは、環境ハンドルと関連することはありません。

DiagIdentifier 引き数

この引き数は、診断データ構造にある希望するフィールドの識別子を示します。 RecNumber が 1 以上であれば、フィールド内のデータは関数で返される診断情報を記述します。 RecNumber が 0 であれば、フィールドは診断データ構造のヘッダー内にあります。そして、そのフィールドには診断情報 (特定情報ではない) を返した関数呼び出しに属するデータが入っています。

ヘッダー・フィールド

以下のヘッダー・フィールドを、 DiagIdentifier 引き数に組み込むことができます。記述子フィールドに定義されている唯一の診断ヘッダー・フィールドは、 SQL_DIAG_NUMBER および SQL_DIAG_RETURNCODE です。


表 103. DiagIdentifier 引き数のヘッダー・フィールド
SQL_DIAG_CURSOR_ROW_COUNT (戻りタイプ SQLINTEGER)

このフィールドは、カーソルにある行のカウントを含みます。そのセマンティクスは、SQLGetInfo() 情報タイプに依存しています。

  • SQL_DYNAMIC_CURSOR_ATTRIBUTES2
  • SQL_FORWARD_ONLY_CURSOR_ATTRIBUTES2
  • SQL_KEYSET_CURSOR_ATTRIBUTES2
  • SQL_STATIC_CURSOR_ATTRIBUTES2

これらは、それぞれのカーソル・タイプごとにどの行カウントが使用可能かを示しています (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 では、その他の値も指定します。


表 105. 動的関数フィールドの値
実行される 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 ファイルを参照してください。

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]