SQLError - エラー情報の検索
SQLError() は、特定のステートメント、接続、環境ハンドルに対して Db2 for i CLI 関数が最近呼び出された際の診断情報を返します。
この情報は、標準化された SQLSTATE、エラー・コード、およびテキスト・メッセージで構成されています。 詳細については、 Db2 for i CLIアプリケーションの診断を参照してください。
別の関数呼び出しからの SQL_ERROR または SQL_SUCCESS_WITH_INFO の戻りコードを受け取った後、
SQLError() を呼び出してください。
構文
SQLRETURN SQLError (SQLHENV henv,
SQLHDBC hdbc,
SQLHSTMT hstmt,
SQLCHAR *szSqlState,
SQLINTEGER *pfNativeError,
SQLCHAR *szErrorMsg,
SQLSMALLINT cbErrorMsgMax,
SQLSMALLINT *pcbErrorMsg);関数引数
| データ・タイプ | 引数 | Use | 説明 |
|---|---|---|---|
| SQLHENV | ハイフン (henv) | 入力 | 環境ハンドル。 環境に関連する診断情報を表示するには、 有効な環境ハンドルを渡します。 hdbc を SQL_NULL_HDBC に設定します。 hstmt を SQL_NULL_HSTMT に設定します。 |
| SQLHDBC | hdbc | 入力 | データベース接続ハンドル。 接続に関連する診断情報を表示するには、 有効なデータベース接続ハンドルを渡し、 hstmt を SQL_NULL_HSTMT に設定してください。 henv 引数は無視されます。 |
| SQLHSTMT | hstmt (hstmt) | 入力 | ステートメント・ハンドル。 ステートメントに関連する診断情報を表示するには、 有効なステートメント・ハンドルを渡してください。 henv および hdbc 引数は無視されます。 |
| SQLCHAR * | szSqlState | 出力 | NULL 文字で切り捨てられた 5 文字のストリングで構成される SQLSTATE。 先頭の 2 文字はエラー・クラスを、それに続く 3 文字はサブクラスを表します。 これらの値は、X/Open SQL CAE 仕様および ODBC 仕様で定義されている SQLSTATE 値に直接対応し、 IBM® 固有の SQLSTATE 値および製品固有の SQLSTATE 値で拡張されています。 |
| SQLINTEGER * | pfNativeError | 出力 | 固有のエラー・コード。 Db2 for i CLIでは、pfNativeError 引数には、データベース管理システム (DBMS) が返すSQLCODE値が含まれます。 エラーが DBMS ではなく Db2 for i CLI によって生成された場合、このフィールドは -99999 に設定されます。 |
| SQLCHAR * | szErrorMsg | 出力 | 実装定義のメッセージ・テキストを保管するバッファーへのポインター。 Db2 for i CLI では、DBMS 生成メッセージのみが返されます。 Db2 for i CLI 自体は、問題を説明するメッセージ・テキストを返しません。 |
| SQLSMALLINT | cbErrorMsgMax | 入力 | バッファー szErrorMsg の最大 (割り振りの) 長。 割り振る長さの推奨値は、SQL_MAX_MESSAGE_LENGTH + 1 です。 |
| SQLSMALLINT * | pcbErrorMsg | 出力 | szErrorMsg バッファーに戻せる合計バイト数を指すポインター。 |
使用法
SQLSTATE は、X/OPEN SQL CAE および X/Open SQL CLI スナップショットによって定義され、 IBM 固有の SQLSTATE 値および製品固有の SQLSTATE 値で拡張されたものです。
- 環境に関連する診断情報を表示するには、 有効な環境ハンドルを渡します。 hdbc を SQL_NULL_HDBC に設定します。 hstmt を SQL_NULL_HSTMT に設定します。
- 接続に関連する診断情報を表示するには、 有効なデータベース接続ハンドルを渡し、 hstmt を SQL_NULL_HSTMT に設定してください。 henv 引数は無視されます。
- ステートメントに関連する診断情報を表示するには、 有効なステートメント・ハンドルを渡してください。 henv および hdbc 引数は無視されます。
SQLError() 以外の関数が同じハンドルを使用して呼び出される前に、1 つの Db2 for i CLI 関数によって生成された診断情報が取得されない場合、前の関数呼び出しの情報は失われます。 これは、2 番目の Db2 for i CLI 関数呼び出しに対して診断情報が生成されるかどうかに関係なく当てはまります。
第 1 レベルのエラー・メッセージが切り捨てられないようにするには、SQL_MAX_MESSAGE_LENGTH + 1 のバッファー長を宣言します。 2 番目のレベルのエラー・メッセージが切り捨てられないようにするには、バッファーのサイズを SQL_MAX_MESSAGE_LENGTH より大きい値に設定してください。
戻りコード
- SQL_ERROR
- SQL_INVALID_HANDLE
- SQL_NO_DATA_FOUND
- SQL_SUCCESS
診断
SQLError() がそれ自体の診断情報を生成することはないので、
SQLSTATE は定義されません。 引数 szSqlState、pfNativeError、szErrorMsg、または pcbErrorMsg が NULL ポインターの場合、SQL_ERROR が戻されます。
例
/*************************************************************************
** file = typical.c
************************************************************************/
int print_error (SQLHENV henv,
SQLHDBC hdbc,
SQLHSTMT hstmt)
{
SQLCHAR buffer[SQL_MAX_MESSAGE_LENGTH + 1];
SQLCHAR sqlstate[SQL_SQLSTATE_SIZE + 1];
SQLINTEGER sqlcode;
SQLSMALLINT length;
while ( SQLError(henv, hdbc, hstmt, sqlstate, &sqlcode, buffer,
SQL_MAX_MESSAGE_LENGTH + 1, &length) == SQL_SUCCESS )
{
printf("\n **** ERROR *****\n");
printf(" SQLSTATE: %s\n", sqlstate);
printf("Native Error Code: %ld\n", sqlcode);
printf("%s \n", buffer);
};
return (0);
}