通过

SQLInstallTranslatorEx 函数

  • 项目

一致性
引入的版本：ODBC 3.0

摘要
SQLInstallTranslatorEx 将有关翻译器的信息添加到系统信息 (HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\ODBC Translators 注册表项) 的Odbcinst.ini部分。

也可以使用 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 字节标记 list.) lpszTranslator 的格式如下所示：

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

lpszPathIn
[输入]要安装翻译器的位置的完整路径或 null 指针。 如果 lpszPath 是空指针，则翻译器将安装在系统目录中。

lpszPathOut
[输出]应安装翻译器的目标目录的路径。 如果从未安装翻译器， 则 lpszPathOut 与 lpszPathIn 相同。 如果存在以前安装的翻译器， 则 lpszPathOut 是先前安装的路径。

cbPathOutMax
[输入] lpszPathOut 的长度。

2016 年 12 月
[输出] 可在 lpszPathOut 中返回的总字节数。 如果可返回的字节数大于或等于 cbPathOutMax， 则 lpszPathOut 中的 输出路径将被截断为 吃 空终止字符，减去 null 终止字符。 该参数可以为 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 应是什么。 这将返回 在PathOut 缓冲区中可用的总字节数。 然后，可以使用 fRequest ODBC_INSTALL_COMPLETE 调用 SQLInstallTranslatorEx，并将 cbPathOutMax 参数设置为该缓冲区中的值，以及 null 终止字符。

如果选择不使用 SQLInstallTranslatorEx 的两阶段模型，则必须将 cbPathOutMax（定义目标目录路径的存储大小）设置为 stdlib.h 中定义的值 _MAX_PATH，以防止截断。

ODBC_INSTALL_COMPLETE fRequest 时， SQLInstallTranslatorEx 不允许 lpszPathOut 为 NULL (或 cbPathOutMax 为 0) 。 如果 fRequest ODBC_INSTALL_COMPLETE，则当可返回的字节数大于或等于 cbPathOutMax 时返回 FALSE，结果为发生截断。

有关以下方面的信息 请参阅
返回默认翻译选项 ConfigTranslator
选择翻译器 SQLGetTranslator
删除翻译器 SQLRemoveTranslator