SQLInstallTranslatorEx 函式

一致性
引進的版本：ODBC 3.0

摘要
SQLInstallTranslatorEx 會將翻譯工具的相關資訊新增至系統資訊 #HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST 的 Odbcinst.ini 區段。INI\ODBC Translators 登錄機碼。

您也可以使用 ODBCCONF.EXE 存取 SQLInstallTranslatorEx 的功能 。

語法

  
BOOL SQLInstallTranslatorEx(  
     LPCSTR    lpszTranslator,  
     LPCSTR    lpszPathIn,  
     LPSTR     lpszPathOut,  
     WORD      cbPathOutMax,  
     WORD *    pcbPathOut,  
     WORD      fRequest,  
     LPDWORD   lpdwUsageCount);  

引數

lpszTranslator
[輸入]這必須包含描述翻譯工具之關鍵字/值組的以 Null 結尾的雙倍清單。 如需關鍵字/值組語法的詳細資訊，請參閱 翻譯工具規格子機碼 。

翻譯工具 與 Setup 關鍵字必須包含在 lpszTranslator 字串中 。 翻譯 DLL 會以 Translator 關鍵字列出，而翻譯工具設定 DLL 會以 Setup 關鍵字列出 。 每個配對都會以 Null 位元組終止，而整個清單會以 Null 位元組終止。 （也就是說，兩個 Null 位元組會標示清單的結尾。lpszTranslator 的格式 如下所示：

\0Translator=translator-DLL-filename\0[Setup= setup-DLL-filename \0]\0

lpszPathIn
[輸入]要安裝翻譯工具的完整路徑或 Null 指標。 如果 lpszPath 是 Null 指標，翻譯工具將會安裝在系統目錄中。

lpszPathOut
[輸出]應安裝翻譯工具的目標目錄路徑。 如果從未安裝翻譯工具， lpszPathOut 會與 lpszPathIn 相同。 如果先前有翻譯工具的安裝， lpszPathOut 是先前安裝的路徑。

cbPathOutMax
[輸入]lpszPathOut 的 長度。

pcpathOut
[輸出]可在 lpszPathOut 中 傳回的位元組總數。 如果可用傳回的位元組數目大於或等於 cbPathOutMax ，則 lpszPathOut 中的 輸出路徑會截斷為 低於 null 終止字元。 對pcspcPathOut 引數可以是 Null 指標。

fRequest
[輸入]要求的類型。 fRequest 必須包含下列其中一個值：

ODBC_INSTALL_INQUIRY：詢問可以安裝翻譯工具的位置。

ODBC_INSTALL_COMPLETE：完成安裝要求。

lpdwUsageCount
[輸出]呼叫此函式之後翻譯工具的使用計數。

應用程式不應設定使用量計數。 ODBC 會維護此計數。

傳回

如果函式成功，則傳回 TRUE，如果失敗，則傳回 FALSE。

診斷

當 SQLInstallTranslatorEx 傳回 FALSE 時 ，可以呼叫 SQLInstallerError 來取得相關聯的 *pfErrorCode 值。 下表列出 SQLInstallerError 可傳 回的 *pfErrorCode 值，並說明此函式內容中的每個值。

*pfErrorCode	錯誤	描述
ODBC_ERROR_GENERAL_ERR	一般安裝程式錯誤	發生錯誤，沒有特定的安裝程式錯誤。
ODBC_ERROR_INVALID_BUFF_LEN	不正確緩衝區長度	lpszPathOut 引數不夠大，無法包含輸出路徑。 緩衝區包含截斷的路徑。 cbPathOutMax 引數為 0，且 fRequest 引數ODBC_INSTALL_COMPLETE。
ODBC_ERROR_INVALID_REQUEST_TYPE	要求類型無效	fRequest 引數不是下列其中一項： ODBC_INSTALL_INQUIRY ODBC_INSTALL_COMPLETE
ODBC_ERROR_INVALID_KEYWORD_VALUE	不正確關鍵字/值組	lpszTranslator 引數包含語法錯誤。
ODBC_ERROR_INVALID_PATH	安裝路徑無效	lpszPathIn 引數包含不正確路徑。
ODBC_ERROR_INVALID_PARAM_SEQUENCE	不正確參數序列	lpszTranslator 引數未包含關鍵字/值組的清單。
ODBC_ERROR_USAGE_UPDATE_FAILED	無法遞增或遞減登錄的元件使用量計數	安裝程式無法遞增翻譯工具的使用計數。

註解

SQLInstallTranslatorEx 提供只安裝翻譯工具的機制。 此函式實際上不會複製任何檔案。 呼叫程式負責複製翻譯工具檔案。

SQLInstallTranslatorEx 會將已安裝翻譯工具的元件使用量計數遞增 1。 如果翻譯工具的版本已經存在，但翻譯工具的元件使用計數不存在，新的元件使用計數值會設定為 2。

應用程式安裝程式負責實際複製翻譯工具檔案，並維護檔案使用計數。 如果先前尚未安裝翻譯工具檔案，應用程式安裝程式必須複製檔案或檔案，並建立檔案或檔案使用量計數。 如果先前已安裝檔案，安裝程式只會遞增檔案使用量計數。

如果應用程式先前已安裝舊版的翻譯工具，則應該卸載翻譯工具，然後重新安裝，讓翻譯工具元件使用計數有效。 應該呼叫 SQLRemoveTranslator 以遞減元件使用量計數，然後 呼叫 SQLInstallTranslatorEx 以遞增元件使用量計數。 應用程式安裝程式必須將舊檔案或檔案取代為新檔案。 檔案使用計數會維持不變，而使用舊版檔案的其他應用程式現在會使用較新版本。

SQLInstallTranslatorEx 中 lpszPathOut 中路徑的長度允許兩階段安裝程式，因此應用程式可以呼叫 具有 fRequest ODBC_INSTALL_INQUIRY 模式的 sqlInstallTranslatorEx 來判斷 什麼是 cbPathOutMax。 這將會傳回在pcerpathOut 緩衝區中 可用的位元組總數。 SQLInstallTranslatorEx 接著可以使用 fRequest ODBC_INSTALL_COMPLETE 呼叫，並將 cbPathOutMax 引數設定為 ODBC_INSTALL_COMPLETE的值，加上 null 終止字元。

如果您選擇不使用 SQLInstallTranslatorEx 的兩階段模型 ，則必須將 cbPathOutMax 設定為目標目錄路徑的儲存體大小，將值_MAX_PATH，如 Stdlib.h 中所定義，以避免截斷。

當 fRequest ODBC_INSTALL_COMPLETE時 ， SQLInstallTranslatorEx 不允許 lpszPathOut 為 Null（或 cbPathOutMax 為 0）。 如果 fRequest 是ODBC_INSTALL_COMPLETE，當可用的位元組數目大於或等於 cbPathOutMax 時，就會傳回 FALSE，並產生截斷的結果。

相關函數

如需下列資訊	請參閱
傳回預設翻譯選項	ConfigTranslator
選取翻譯工具	SQLGetTranslator
移除翻譯工具	SQLRemoveTranslator