ConfigDSN 函数

一致性
引入的版本：ODBC 1.0

摘要
ConfigDSN 在系统信息中添加、修改或删除数据源。 它可能会提示用户输入连接信息。 它可以在驱动程序 DLL 或单独的安装 DLL 中。

语法

  
BOOL ConfigDSN(  
     HWND     hwndParent,  
     WORD     fRequest,  
     LPCSTR   lpszDriver,  
     LPCSTR   lpszAttributes);  

参数

hwndParent
[输入]父窗口句柄。 如果句柄为 null，函数将不会显示任何对话框。

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

ODBC_ADD_DSN：添加新数据源。

ODBC_CONFIG_DSN：配置 (修改现有数据源) 。

ODBC_REMOVE_DSN：删除现有数据源。

lpszDriver
[输入]驱动程序说明通常 (向用户显示的关联 DBMS) 的名称，而不是物理驱动程序名称。

lpszAttributes
[输入]以关键字-值对的形式以 null 结尾的属性列表。 有关详细信息，请参阅“注释”。

返回

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

诊断

当 ConfigDSN 返回 FALSE 时，关联的 *pfErrorCode 值将通过调用 SQLPostInstallerError 发布到安装程序错误缓冲区，并且可以通过调用 SQLInstallerError 获取。 下表列出了 SQLInstallerError 可返回的 *pfErrorCode 值，并说明了此函数上下文中的每个值。

*pfErrorCode	错误	说明
ODBC_ERROR_INVALID_HWND	无效的窗口句柄	hwndParent 参数无效。
ODBC_ERROR_INVALID_KEYWORD_VALUE	无效的关键字值对	lpszAttributes 参数包含语法错误。
ODBC_ERROR_INVALID_NAME	驱动程序或翻译器名称无效	lpszDriver 参数无效。 在注册表中找不到它。
ODBC_ERROR_INVALID_REQUEST_TYPE	请求类型无效	fRequest 参数不是下列参数之一： ODBC_ADD_DSN ODBC_CONFIG_DSN ODBC_REMOVE_DSN
ODBC_ERROR_REQUEST_FAILED	请求 失败	无法执行 fRequest 参数请求的操作。
ODBC_ERROR_DRIVER_SPECIFIC	特定于驱动程序或翻译器的错误	驱动程序特定的错误，其中没有定义的 ODBC 安装程序错误。 调用 SQLPostInstallerError 函数时，SzError 参数应包含特定于驱动程序的错误消息。

注释

ConfigDSN 从安装程序 DLL 接收连接信息，作为关键字值对形式的属性列表。 每对都以 null 字节结尾，整个列表以 null 字节终止。 (即，两个 null 字节标记 list 的末尾。) 不允许在关键字值对中的等号周围使用空格。 ConfigDSN 可以接受不是 SQLBrowseConnect 和 SQLDriverConnect 有效关键字 的关键字。 ConfigDSN 不一定支持是 SQLBrowseConnect 和 SQLDriverConnect 的有效关键字的所有关键字。 (ConfigDSN 不接受 DRIVER 关键字。) ConfigDSN 函数使用的关键字必须支持使用安装程序的 AUTO 设置功能重新创建数据源所需的所有选项。 当 ConfigDSN 值和连接字符串值的用法相同时，应使用相同的关键字。

与 SQLBrowseConnect 和 SQLDriverConnect 中一样，关键字及其值不应包含 []{} () ，;？*=！@ 字符， DSN 关键字的值不能只包含空白。 由于注册表语法的原因，关键字和数据源名称不能包含反斜杠 (\) 字符。

ConfigDSN 应调用 SQLValidDSN 来检查数据源名称的长度并验证名称中是否不包含无效字符。 如果数据源名称长于 SQL_MAX_DSN_LENGTH 或包含无效字符， 则 SQLValidDSN 将返回错误， ConfigDSN 返回错误。 SQLWriteDSNToIni 还会检查数据源名称的长度。

例如，若要配置需要用户 ID、密码和数据库名称的数据源，安装应用程序可能会传递以下关键字值对：

DSN=Personnel Data\0UID=Smith\0PWD=Sesame\0DATABASE=Personnel\0\0  

有关这些关键字的详细信息，请参阅 SQLDriverConnect 和每个驱动程序的文档。

若要显示对话框， hwndParent 不得为 null。

添加数据源

如果在 lpszAttributes 中将数据源名称传递给 ConfigDSN，则 ConfigDSN 会检查该名称是否有效。 如果数据源名称与现有数据源名称匹配，并且 hwndParent 为 null， 则 ConfigDSN 将覆盖现有名称。 如果它与现有名称匹配，并且 hwndParent 不为 null， 则 ConfigDSN 将提示用户覆盖现有名称。

如果 lpszAttributes 包含足够的信息来连接到数据源， 则 ConfigDSN 可以添加数据源或显示一个对话框，用户可以使用该对话框更改连接信息。 如果 lpszAttributes 不包含足够的信息来连接到数据源， 则 ConfigDSN 必须确定必要的信息;如果 hwndParent 不为 null，则显示一个对话框，用于从用户检索信息。

如果 ConfigDSN 显示一个对话框，则必须在 lpszAttributes 中显示传递给它的任何连接信息。 具体而言，如果数据源名称已传递给它， ConfigDSN 将显示该名称，但不允许用户更改它。 ConfigDSN 可以为未在 lpszAttributes 中传递给它的连接信息提供默认值。

如果 ConfigDSN 无法获取数据源的完整连接信息，则返回 FALSE。

如果 ConfigDSN 可以获取数据源的完整连接信息，它会在安装程序 DLL 中调用 SQLWriteDSNToIni ，将新的数据源规范添加到Odbc.ini文件 (或注册表) 。 SQLWriteDSNToIni 将数据源名称添加到 [ODBC 数据源] 节，创建数据源规范部分，并添加 DRIVER 关键字以及驱动程序说明作为其值。 ConfigDSN 在安装程序 DLL 中调用 SQLWritePrivateProfileString ，以添加驱动程序使用的任何其他关键字和值。

修改数据源

若要修改数据源，必须将数据源名称传递给 lpszAttributes 中的 ConfigDSN。 ConfigDSN 检查数据源名称是否位于Odbc.ini文件 (或注册表) 中。

如果 hwndParent 为 null， ConfigDSN 将使用 lpszAttributes 中的信息修改Odbc.ini文件 (或注册表) 中的信息。 如果 hwndParent 不为 null， 则 ConfigDSN 使用 lpszAttributes 中的信息显示一个对话框;对于不在 lpszAttributes 中的信息，它使用系统信息中的信息。 在 ConfigDSN 将信息存储在系统信息中之前，用户可以对其进行修改。

如果数据源名称已更改， ConfigDSN 首先在安装程序 DLL 中调用 SQLRemoveDSNFromIni ，以从Odbc.ini文件 (或注册表) 中删除现有数据源规范。 然后，它按照上一部分中的步骤添加新的数据源规范。 如果未更改数据源名称， ConfigDSN 将在安装程序 DLL 中调用 SQLWritePrivateProfileString 进行任何其他更改。 ConfigDSN 不得删除或更改 Driver 关键字的值。

删除数据源

若要删除数据源，必须将数据源名称传递给 lpszAttributes 中的 ConfigDSN。 ConfigDSN 检查数据源名称是否位于Odbc.ini文件 (或注册表) 中。 然后，它会在安装程序 DLL 中调用 SQLRemoveDSNFromIni 以删除数据源。

注意

如果编写此例程的 Unicode 版本，则必须使用 LPCWSTR 参数而不是 LPCSTR 调用 ConfigDSNW。

相关函数

有关以下方面的信息	请参阅
添加、修改或删除数据源	SQLConfigDataSource
从Odbc.ini文件或注册表获取值	SQLGetPrivateProfileString
删除默认数据源	SQLRemoveDefaultDataSource
从Odbc.ini (或注册表) 中删除数据源名称	SQLRemoveDSNFromIni
将数据源名称添加到Odbc.ini (或注册表)	SQLWriteDSNToIni
将值写入Odbc.ini文件或注册表	SQLWritePrivateProfileString