DB2 CLI バージョン 5 以降におけるこの関数の状況
注: |
ODBC バージョン 3 では、SQLError() 使用すべきではなく、代わりに SQLGetDiagRec() および SQLGetDiagField() に置き換えられています。詳細については、SQLGetDiagRec - 診断レコードの複数のフィールド設定を取得すると SQLGetDiagField - 診断データのフィールドの入手を参照してください。
このバージョンの DB2 CLI でも引き続き SQLError() をサポートしていますが、 SQLGetDiagRec() の使用を DB2 CLI プログラムから開始するなら最新の規格に適合できるため、この方法をお勧めします。
上記の関数と、その他の使用すべきでない関数の詳細については、 バージョン 5 で使用すべきでない DB2 CLI 関数を参照してください。 |
目的
仕様: | DB2 CLI 1.1 | ODBC 1.0 | ISO CLI |
SQLError() は、特定のステートメント、接続、または環境ハンドルについて呼び出された最新の DB2 CLI 関数に関連した診断情報 (エラーおよび警告) を返します。
この情報は、標準化された SQLSTATE、ネイティブのエラー・コード、テキスト・メッセージから構成されています。詳細については、診断 を参照してください。
別の関数呼び出しからの SQL_ERROR または SQL_SUCCESS_WITH_INFO の戻りコードを受け取った後で、 SQLError() を呼び出してください。
注: | データベース・サーバーの中には、ステートメントを実行した結果として SQL_NO_DATA_FOUND を返した後に製品特定の診断情報を表示するものがあります。 |
構文
SQLRETURN SQLError (SQLHENV henv, SQLHDBC hdbc, SQLHSTMT hstmt, SQLCHAR FAR *szSqlState, SQLINTEGER FAR *pfNativeError, SQLCHAR FAR *szErrorMsg, SQLSMALLINT cbErrorMsgMax, SQLSMALLINT FAR *pcbErrorMsg);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHENV | henv | 入力 | 環境ハンドル。環境に関連した診断情報を取得するには、有効な環境ハンドルを渡します。 hdbc を SQL_NULL_HDBC に設定し、hstmt を SQL_NULL_HSTMT に設定してください。 |
SQLHDBC | hdbc | 入力 | データベース接続ハンドル。接続に関連した診断情報を取得するには、有効なデータベース接続ハンドルを渡し、 hstmt を SQL_NULL_HSTMT に設定します。 henv 引き数は無視されます。 |
SQLHSTMT | hstmt | 入力 | ステートメント・ハンドル。ステートメントに関連した診断情報を取得するには、有効なステートメント・ハンドルを渡します。 henv 引き数と hdbc 引き数は無視されます。 |
SQLCHAR * | szSqlState | 出力 | ヌル文字で終了している 5 文字のストリングの SQLSTATE。最初の 2 文字はエラー・クラスを指示し、次の 3 文字はサブクラスを指示します。これらの値は、IBM 特定と製品特定の SQLSTATE 値が追加された、 X/Open SQL CAE 仕様と ODBC 仕様で定義されている SQLSTATE 値にそのまま対応しています。 |
SQLINTEGER * | pfNativeError | 出力 | ネイティブのエラー・コード。 DB2 CLI では、 pfNativeError 引き数には DBMS から返された SQLCODE 値が含まれています。エラーが DBMS でなく DB2 CLI で生成された場合、このフィールドは -99999 に設定されます。 |
SQLCHAR * | szErrorMsg | 出力 | 処理系定義メッセージ・テキストを入れるバッファーを指すポインター。エラーが DB2 CLI で検出されると、エラー・メッセージの前に次のものが付けられます。
[IBM][CLI Driver]これは、エラーを検出したのが DB2 CLI であり、まだデータベース接続がないことを示します。
エラーが検出されると、DBMS から返されたエラー・メッセージの前に次のものが付けられます。 [IBM][CLI Driver][DBMS-name] DBMS-name は、SQLGetInfo() に SQL_DBMS_NAME 情報タイプを指定して返される名前です。
たとえば、以下のようになります。
DBMS 名が認識されない場合、DB2 CLI はこれを DB2 ユニバーサル・データベース バージョン 5 データ・ソースとして扱います。
DBMS でエラーが生成されると、IBM 定義の SQLSTATE がテキスト・ストリングに付加されます。 |
SQLSMALLINT | cbErrorMsgMax | 入力 | バッファー szErrorMsg の最大 (つまり、割り振られた) 長さ。 SQL_MAX_MESSAGE_LENGTH + 1 の長さを割り振ることをお勧めします。 |
SQLSMALLINT * | pcbErrorMsg | 出力 | szErrorMsg バッファーに返すために使用できる総バイト数を指すポインター。これには、ヌル終了文字が含まれていません。 |
使用法
SQLSTATE は、IBM 特定と製品特定の SQLSTATE 値が追加された、 X/Open SQL CAE と X/Open SQL CLI CAE で定義されたものです。
以下のものに関連した診断情報を取得する場合は、以下のようにします。
ある DB2 CLI 関数で生成された診断情報が、同じハンドルを指定して SQLError() 以外の関数を呼び出す前に取り出されない場合、直前の関数呼び出しの情報が失われます。このことは、 2 番目の DB2 CLI 関数呼び出しに関する診断情報が生成されるかどうかにかかわらず当てはまります。
指定した DB2 CLI 関数呼び出しの後に、複数の診断メッセージが使用できる場合があります。 SQLError() を繰り返し呼び出すと、これらのメッセージを一度に 1 つずつ取り出すことができます。取り出されたメッセージごとに、SQLError() は SQL_SUCCESS を返し、利用可能なメッセージのリストからそれを除去します。取り出すメッセージがそれ以上ないと、SQL_NO_DATA_FOUND が返され、 SQLSTATE は「00000」に設定され、pfNativeError は 0 に設定され、 pcbErrorMsg と szErrorMsg は定義されません。
指定ハンドルに保管されている診断情報は、そのハンドルを指定して SQLError() 呼び出しが行われる場合、またはそのハンドルを指定して別の DB2 CLI 関数の呼び出しが行われる場合に、クリアされます。しかし、指定ハンドル・タイプに関連した情報は、関連しているが同じではないハンドル・タイプを指定した SQLError() 呼び出しではクリアされません。たとえば、接続ハンドルを指定して SQLError() を呼び出しても、その接続のステートメント・ハンドルに関連したエラーはクリアされません。
アプリケーションが SQLError() を再度呼び出して同じエラー・メッセージを取り出すことはないので、エラー・メッセージのバッファー (szErrorMsg) が短すぎる場合でも、 SQL_SUCCESS は返されます。メッセージ・テキストの実際の長さは、pcbErrorMsg 内に返されます。
エラー・メッセージが切り捨てられないようにするには、バッファー長として SQL_MAX_MESSAGE_LENGTH + 1 を宣言します。メッセージ・テキストがこれ以上長くなることは決してありません。
注: | SQL_MAX_MESSAGE_LENGTH に定義された値は、DB2 CLI バージョン 1 以降増えています。 |
戻りコード
SQL_NO_DATA_FOUND は、入力ハンドルに関する診断情報を使用できない場合、または SQLError() 呼び出しによってすべてのメッセージが取り出されている場合に返されます。
診断
SQLError() は独自の診断情報を生成しないので、SQLSTATE は定義されません。
制約
ODBC は X/Open SQL CAE SQLSTATE も返しますが、 DB2 CLI (および DB2 ODBC ドライバー) は IBM 定義の追加 SQLSTATE しか返しません。 ODBC ドライバー・マネージャーは、 IM という接頭部の付いた SQLSTATE 値も返します。これらの SQLSTATE は X/Open では定義されておらず、DB2 CLI からは返されません。 ODBC 特定の SQLSTATE については、 ODBC 3.0 Software Development Kit and Programmer's Reference を参照してください。
このため、標準 SQLSTATE に依存性を構築するだけで済みます。このことは、アプリケーション内の分岐論理が標準 SQLSTATE だけに基づいている必要があることを意味します。増補された SQLSTATE は、デバッグの場合に最も有効です。
注: | SQLSTATE のクラス (先頭 2 文字) に関する依存性を作成すると効果的な場合があります。 |
SQLGetDiagRec - 診断レコードの複数のフィールド設定を取得するを参照してください。
参照