SQLInstallerError 関数

  • [アーティクル]

準拠
導入されたバージョン: ODBC 3.0

まとめ
SQLInstallerError は 、ODBC インストーラー関数のエラーまたは状態情報を返します。

構文

  
RETCODE SQLInstallerError(  
     WORD      iError,  
     DWORD *   pfErrorCode,  
     LPSTR     lpszErrorMsg,  
     WORD      cbErrorMsgMax,  
     WORD *    pcbErrorMsg);

引数

iError
[入力]エラー レコード番号。 有効な数値は 1 から 8 です。

pfErrorCode
[出力]インストーラーのエラー コード。 (詳細については、「コメント」を参照してください。)

lpszErrorMsg
[出力]エラー メッセージ テキストのストレージへのポインター。

cbErrorMsgMax
[入力] szErrorMsg バッファーの最大長。 これは、SQL_MAX_MESSAGE_LENGTHから null 終端文字を差し引いた値以下である必要があります。

cbErrorMsgMax
[入力] szErrorMsg バッファーの最大長。 これは、SQL_MAX_MESSAGE_LENGTHから null 終端文字を差し引いた値以下である必要があります。

pcbErrorMsg
[出力] lpszErrorMsg で返すために使用できる合計バイト数 (null 終端文字を除く) へのポインター。 返される使用可能なバイト数が cbErrorMsgMax 以上の場合、 lpszErrorMsg 内のエラー メッセージ テキストは cbErrorMsgMax から null 終端文字バイトを引いた値に切り捨てられます。 pcbErrorMsg 引数には null ポインターを指定できます。

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、またはSQL_ERROR。

診断

SQLInstallerError は、それ自体のエラー値をポストしません。 SQLInstallerError は、 エラー情報を取得できない場合にSQL_NO_DATAを返します (この場合 、pfErrorCode は未定義です)。 SQLInstallerError が通常SQL_ERRORを返す理由でエラー値にアクセスできない場合、SQLInstallerError はSQL_ERRORを返しますが、エラー値はポストしません。 警告文字列 (lpszErrorMsg) の長さが不明な場合は、 lpszErrorMsg を NULL に設定し、 SQLInstallerError を呼び出すことができます。 その後、SQLInstallerError は cbErrorMsgMax 内の警告文字列の長さを返します。 エラー メッセージのバッファーが短すぎる場合、SQLInstallerError は SQL_SUCCESS_WITH_INFOを返し、SQLInstallerError の正しい pfErrorCode 値を返します。

エラー メッセージで切り捨てが発生したかどうかを判断するために、アプリケーションは cbErrorMsgMax 引数の値を 、pcbErrorMsg 引数に書き込まれたメッセージ テキストの実際の長さと比較できます。 切り捨てが行われる場合は、lpszErrorMsg に正しいバッファー長を割り当て、対応する iError レコードを使用して SQLInstallerError を再度呼び出す必要があります。

説明

アプリケーションは、ODBC インストーラー関数の前回の呼び出しで FALSE が返されたときに SQLInstallerError を呼び出します。 ODBC インストーラーおよびドライバーまたはトランスレーターのセットアップ関数は、関数が失敗した場合にのみ 0 個以上のエラーを発生させます (FALSE を返します)。したがって、アプリケーションは、ODBC インストーラー関数が失敗した後にのみ SQLInstallerError を呼び出します。

ODBC インストーラー エラー キューは、新しいインストーラー関数が呼び出されるたびにフラッシュされます。 したがって、アプリケーションでは、最後のインストーラー関数呼び出しから以外の関数のエラーを取得することは想定できません。

関数呼び出しの複数のエラーを取得するために、アプリケーションは SQLInstallerError を 複数回呼び出します。

追加情報がない場合、 SQLInstallerError はSQL_NO_DATAを返し、 pfErrorCode 引数は未定義、 pcbErrorMsg 引数は 0、 lpszErrorMsg 引数には 1 つの null 終端文字が含まれます ( cbErrorMsgMax 引数が 0 の場合を除く)。