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 終止字元位元組。 oemErrorMsg 引數可以是 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 引數中的 值與寫入 至 oemErrorMsg 引數之訊息文字的實際長度進行比較。 如果發生截斷，應該為 lpszErrorMsg 配置正確的緩衝區長度，而且 應該使用對應的 iError 記錄再次呼叫 SQLInstallerError 。

註解

當先前對 ODBC 安裝程式函式的呼叫傳回 FALSE 時，應用程式會呼叫 SQLInstallerError 。 只有在函式失敗時，ODBC 安裝程式和驅動程式或翻譯工具設定函式才會張貼零或多個錯誤（傳回 FALSE）：因此，只有在 ODBC 安裝程式函式失敗之後，應用程式才會呼叫 SQLInstallerError 。

每次呼叫新的安裝程式函式時，都會排清 ODBC 安裝程式錯誤佇列。 因此，應用程式無法預期會擷取最後一個安裝程式函式呼叫以外的函式錯誤。

若要擷取函式呼叫的多個錯誤，應用程式會多次呼叫 SQLInstallerError 。

當沒有任何其他資訊時， SQLInstallerError 會傳回SQL_NO_DATA、 未定義 pfErrorCode 引數、 對等 0 的 oemErrorMsg 引數，而 lpszErrorMsg 引數包含單一 null 終止字元（除非 cbErrorMsgMax 引數等於 0）。