SQLInstallDriverEx 函数

  • 项目

一致性
引入的版本：ODBC 3.0

摘要
SQLInstallDriverEx 将有关驱动程序的信息添加到系统信息中的Odbcinst.ini条目，并将驱动程序的 UsageCount 递增 1。 但是，如果驱动程序的版本已存在，但驱动程序的 UsageCount 值不存在，则新的 UsageCount 值将设置为 2。

此函数实际上不会复制任何文件。 调用程序负责将驱动程序的文件正确复制到目标目录。

也可以使用 ODBCCONF.EXE访问 SQLInstallDriverEx 的功能。

语法

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

参数

lpszDriver
[输入]驱动程序说明通常 (向用户显示的关联 DBMS) 的名称，而不是物理驱动程序名称。 lpszDriver 参数必须包含描述驱动程序的关键字值对的双 null 终止列表。 有关关键字值对的详细信息，请参阅 驱动程序规范子项。 有关双 null 终止字符串的详细信息，请参阅 ConfigDSN 函数。

lpszPathIn
[输入]安装的目标目录的完整路径或 null 指针。 如果 lpszPathIn 是空指针，驱动程序将安装在系统目录中。

lpszPathOut
[输出]应在其中安装驱动程序的目标目录的路径。 如果之前尚未安装驱动程序， lpszPathOut 应与 lpszPathIn 相同。 如果以前安装了驱动程序， 则 lpszPathOut 是以前安装的路径。

cbPathOutMax
[输入] lpszPathOut 的长度。

线路板路径Out
[输出] (排除在 lpszPathOut 中返回的 null 终止字符) 字节总数。 如果可返回的字节数大于或等于 cbPathOutMax， 则 lpszPathOut 中的输出路径将被截断为 cbPathOutMax 减去 null 终止字符。 “线路板路径”参数可以是 null 指针。

fRequest
[输入]请求的类型。 fRequest 参数必须包含以下值之一：

ODBC_INSTALL_INQUIRY：询问可以安装驱动程序的位置。

ODBC_INSTALL_COMPLETE：完成安装请求。

lpdwUsageCount
[输出]调用此函数后驱动程序的使用情况计数。

应用程序不应设置使用情况计数。 ODBC 将保留此计数。

返回

如果成功，函数将返回 TRUE;如果失败，则返回 FALSE。

诊断

当 SQLInstallDriverEx 返回 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 无效的关键字-值对 lpszDriver 参数包含语法错误。
ODBC_ERROR_INVALID_PATH 安装路径无效 lpszPathIn 参数包含无效路径。
ODBC_ERROR_LOAD_LIBRARY_FAILED 无法加载驱动程序或翻译器安装库 无法加载驱动程序设置库。
ODBC_ERROR_INVALID_PARAM_SEQUENCE 参数序列无效 lpszDriver 参数不包含关键字值对的列表。
ODBC_ERROR_USAGE_UPDATE_FAILED 无法递增或递减组件使用情况计数 安装程序未能递增驱动程序的使用情况计数。

注释

lpszDriver 参数是关键字值对形式的属性列表。 每个对都以 null 字节结尾，整个列表以 null 字节结尾。 (即，两个 null 字节标记 list 的末尾。) 此列表的格式如下所示：

driver-desc\0Driver=driver-DLL-filename\0[Setup=setup-DLL-filename\0]

[driver-attr-keyword1=value1\0][driver-attr-keyword2 value2=\0]...\0

其中 \0 是空字节， driver-attr-keywordn 是任何驱动程序属性关键字。 关键字必须按指定顺序显示。 例如，假设格式化文本文件的驱动程序具有单独的驱动程序和设置 DLL，并且可以使用具有.txt和.csv扩展名的文件。 此驱动程序的 lpszDriver 参数可能如下所示：

Text\0Driver=TEXT.DLL\0Setup=TXTSETUP.DLL\0FileUsage=1\0  
FileExtns=*.txt,*.csv\0\0

假设适用于 SQL Server 的驱动程序没有单独的安装 DLL，并且没有任何驱动程序属性关键字。 此驱动程序的 lpszDriver 参数可能如下所示：

SQL Server\0Driver=SQLSRVR.DLL\0\0

SQLInstallDriverEx 从 lpszDriver 参数检索有关驱动程序的信息后，它会将驱动程序说明添加到系统信息中Odbcinst.ini项的 [ODBC Drivers] 部分。 然后，它会创建一个标题为驱动程序说明的部分，并添加驱动程序 DLL 和设置 DLL 的完整路径。 最后，它返回安装的目标目录的路径，但不将驱动程序文件复制到其中。 调用程序必须实际将驱动程序文件复制到目标目录。

SQLInstallDriverEx 将已安装驱动程序的组件使用情况计数递增 1。 如果驱动程序的版本已存在，但驱动程序的组件使用情况计数不存在，则新的组件使用计数值设置为 2。

应用程序安装程序负责以物理方式复制驱动程序文件并维护文件使用情况计数。 如果之前尚未安装驱动程序文件，则应用程序安装程序必须复制 lpszPathIn 路径中的文件并创建文件使用情况计数。 如果之前已安装该文件，安装程序只会递增文件使用计数，并在 lpszPathOut 参数中返回先前安装的路径。

注意

有关组件使用情况计数和文件使用情况计数的详细信息，请参阅 使用情况计数。

如果应用程序以前安装了较旧版本的驱动程序文件，则应卸载驱动程序，然后重新安装，以便驱动程序组件使用情况计数有效。 应首先调用 fRequest 为 ODBC_REMOVE_DRIVER) 的 SQLConfigDriver (，然后调用 SQLRemoveDriver 以减少组件使用量计数。 然后，应调用 SQLInstallDriverEx 来重新安装驱动程序，从而递增组件使用情况计数。 应用程序安装程序必须将旧文件替换为新文件。 文件使用情况计数将保持不变，使用旧版本文件的任何其他应用程序现在都将使用较新版本。

注意

如果以前安装了驱动程序，并且调用 SQLInstallDriverEx 以在不同的目录中安装驱动程序，则函数将返回 TRUE，但 lpszPathOut 将包含已安装驱动程序的目录。 它不包括 在 lpszDriver 参数中输入的目录。

SQLInstallDriverEx 中 lpszPathOut 中的路径长度允许进行两阶段安装过程，因此应用程序可以通过调用具有ODBC_INSTALL_INQUIRY模式的 fRequest 的 SQLInstallDriverEx 来确定 cbPathOutMax 应是什么。 这将返回 在板PathOut 缓冲区中可用的总字节数。 然后，可以使用 fRequest ODBC_INSTALL_COMPLETE 调用 SQLInstallDriverEx，并将 cbPathOutMax 参数设置为该缓冲区中的值，以及 null 终止字符。

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

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

调用 SQLInstallDriverEx 后，应用程序安装程序已根据需要 (复制驱动程序文件) ，驱动程序安装 DLL 必须调用 SQLConfigDriver 来设置驱动程序的配置。

有关以下方面的信息 请参阅
安装驱动程序管理器 SQLInstallDriverManager