仕様: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLGetDiagRec() は、エラー、警告、および状況情報が入っている診断レコードの複数のフィールドの現行値を戻します。 1 回の呼び出しに対して 1 つの診断フィールドを戻す SQLGetDiagField() とは異なり、 SQLGetDiagRec() は、SQLSTATE、ネイティブなエラー・コード、およびエラー・メッセージ・テキストなど、診断レコードで共通に使用されている複数のフィールドを戻します。
構文
SQLRETURN SQLGetDiagRec (SQLSMALLINT HandleType, SQLHANDLE Handle, SQLSMALLINT RecNumber, SQLCHAR *SQLState, SQLINTEGER *NativeErrorPtr, SQLCHAR *MessageText, SQLSMALLINT BufferLength, SQLSMALLINT *TextLengthPtr);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLSMALLINT | HandleType | 入力 | 診断するハンドルのタイプを記述するハンドル・タイプ識別子。以下のうちの 1 つでなければなりません。
|
SQLHANDLE | Handle | 入力 | HandleType で示されるタイプの、診断データ構造のハンドル。 |
SQLSMALLINT | RecNumber | 入力 | アプリケーションが情報を求める状況レコード。状況レコードは、1 から数えます。 |
SQLCHAR | SQLState | 出力 | 診断レコード RecNumber に関する 5 文字の SQLSTATE コードを戻すバッファーを指すポインター。先頭の 2 文字はクラス、続く 3 文字はサブクラスを表します。 |
SQLINTEGER | NativeErrorPtr | 出力 | データ・ソースに特定のネイティブなエラー・コードを戻すバッファーを指すポインター。 |
SQLCHAR | MessageText | 出力 | エラー・メッセージ・テキストを戻すバッファーを指すポインター。 SQLGetDiagRec() が戻すフィールドは、テキスト・ストリングに入ります。 |
SQLINTEGER | BufferLength | 入力 | *MessageText バッファーの長さ (バイト単位)。 |
SQLSMALLINT | TextLengthPtr | 出力 | *MessageText に戻すために使用できる総バイト数 (ヌル終了文字に必要なバイト数を除く) を戻すバッファーを指すポインター。戻りに使用できるバイト数が BufferLength より大きい場合、 *MessageText のエラー・メッセージ・テキストは BufferLength からヌル終了文字の長さを引いたものに切り捨てられます。 |
使用法
DB2 CLI 関数への直前の呼び出しで SQL_SUCCESS 以外の値が戻されると、アプリケーションは通常 SQLGetDiagRec() を呼び出します。しかし、どの関数でも呼び出されるたびに 0 個以上のエラーを通知できるので、アプリケーションは任意の関数呼び出しの後に SQLGetDiagRec() を呼び出すことができます。アプリケーションは、SQLGetDiagRec() を何回も呼び出して、診断データ構造のレコードの一部またはすべてを戻すことができます。
SQLGetDiagRec() は、診断データ構造レコードの複数のフィールドが含まれている文字ストリングを戻します。戻りデータの詳細については、SQLGetDiagField - 診断データのフィールドの入手に記載されています。
SQLGetDiagRec() は、診断データ構造のヘッダーからフィールドを戻すことはできません (RecNumber 引き数が 0 より大きい値でなければならない)。これを行うには、アプリケーションは SQLGetDiagField() を呼び出す必要があります。
SQLGetDiagRec() は、 Handle 引き数で指定されているハンドルに関連する最新の診断情報だけを取り出します。アプリケーションが SQLGetDiagRec() または SQLGetDiagField() 以外の別の関数を呼び出すと、直前の呼び出しで同じハンドルで検索した診断情報は失われます。
SQLGetDiagRec() が SQL_SUCCESS を戻す場合、ループ、つまり RecNumber を増分すればすべての診断レコードを走査できます。 SQLGetDiagRec() を呼び出しても、ヘッダーとレコード・フィールドは破壊されません。 SQLGetDiagRec() または SQLGetDiagField() 以外の関数を一時的に呼び出している場合、アプリケーションは、あとでもう一度 SQLGetDiagRec() を呼び出し、レコードからフィールドを検索できます。また、SQLGetDiagField() を呼び出して SQL_DIAG_NUMBER フィールドの値を検索し、その回数分だけ SQLGetDiagRec() を呼び出せば、使用可能な診断レコードの合計数を取り出せます。
診断データ構造のフィールドの説明については、SQLGetDiagField - 診断データのフィールドの入手を参照してください。
HandleType 引き数
それぞれのハンドル・タイプに、関連する診断情報を付けることができます。 HandleType 引き数は、Handle のハンドル・タイプを表します。
すべてのハンドル・タイプ (環境、接続、ステートメント、および記述子) のヘッダー・フィールドおよびレコード・フィールドが戻されるわけではありません。フィールドが適用されないこれらのハンドルは、『ヘッダー・フィールド』、 『レコード・フィールド』、および SQLGetDescField() の説明に記載されています。
戻りコード
診断
SQLGetDiagRec() は、自分でエラー値を通知することはできません。次の戻り値を使用して、自身の実行結果を報告します。
(ここで完全サンプル utilcli.c を使用することもできます 。)
/* From the CLI sample utilcli.c */ /* ... */ while ( SQLGetDiagRec( htype, hndl, i, sqlstate, &sqlcode, message, SQL_MAX_MESSAGE_LENGTH + 1, &length ) == SQL_SUCCESS ) { printf( "\n SQLSTATE = %s\n", sqlstate ) ; printf( " Native Error Code = %ld\n", sqlcode ) ; printf( "%s\n", message ) ; i++ ; } &fileOption, 14, &fileInd);
参照