SQLCreateDataSource 函数

一致性
引入的版本：ODBC 2.0

摘要
SQLCreateDataSource 显示一个对话框，用户可以使用该对话框添加数据源。

语法

  
BOOL SQLCreateDataSource(  
     HWND    hwnd,  
     LPSTR   lpszDS);  

参数

hwnd
[输入]父窗口句柄。

lpszDS
[输入]数据源名称。 lpszDS 可以是空指针或空字符串。

返回

如果创建了数据源，SQLCreateDataSource 将返回 TRUE。 否则，返回 FALSE。

诊断

当 SQLCreateDataSource 返回 FALSE 时，可以通过调用 SQLInstallerError 来获取关联的 *pfErrorCode 值。 下表列出了 SQLInstallerError 可返回的 *pfErrorCode 值，并说明了此函数上下文中的每个值。

*pfErrorCode	错误	说明
ODBC_ERROR_GENERAL_ERR	常规安装程序错误	发生错误，其中没有特定的安装程序错误。
ODBC_ERROR_INVALID_HWND	无效的窗口句柄	hwnd 参数无效或为 NULL。
ODBC_ERROR_INVALID_DSN	无效的 DSN	lpszDS 参数包含对 DSN 无效的字符串。
ODBC_ERROR_REQUEST_FAILED	请求 失败	使用 ODBC_ADD_DSN 选项调用 ConfigDSN 失败。
ODBC_ERROR_LOAD_LIBRARY_FAILED	无法加载驱动程序或翻译器安装库	无法加载驱动程序设置库。
ODBC_ERROR_USER_CANCELED	用户已取消操作	用户已取消创建新数据源。
ODBC_ERROR_CREATE_DSN_FAILED	无法创建请求的 DSN	无法连接到数据库;对文件 DSN 的 SQLDriverConnect 的调用未返回成功的连接。 无法写入文件。
ODBC_ERROR_OUT_OF_MEM	内存不足	由于内存不足，安装程序无法执行函数。

注释

如果 hwnd 为 null， SQLCreateDataSource 将 返回 FALSE。 否则，它将显示“ 创建新数据源 ”对话框，其中包含用于选择要设置的数据源类型的向导页，如下图所示。

类型”

默认选项为 “文件数据源”。 选择数据源并单击“ 下一步 ”后，将显示包含已安装驱动程序列表的以下向导页。

如果单击“ 取消 ”，对话框将消失， SQLCreateDataSource 返回 FALSE，错误代码为 ODBC_ERROR_USER_CANCELED。 如果选择了 “用户数据源 ”或“ 系统数据源” 选项，则“ 高级 ”按钮不可用。

单击“ 下一步 ”按钮时，将发生以下任一情况，具体取决于所选的数据源类型：

• 如果选择了 “文件数据源” ，则会显示一个向导页，供用户输入文件名。

• 如果选择了 “用户数据源” 或 “系统数据源” ，则会显示一个向导页，其中显示了数据源和驱动程序的类型以供查看，单击“ 完成 ”时，将设置数据源。

如果从“新建数据源”向导页单击“ 高级 ”，则会显示一个向导页，供用户输入特定于驱动程序的信息。 在此对话框的文本框中，键入以返回值分隔的驱动程序和关键字，如下图所示。

可以在 SQLDriverConnect 的说明下找到其他特定于驱动程序的关键字。 允许除 DSN 以外的所有服务。

“ 验证此连接” 选项的默认值为 TRUE。 无论此向导页是否已激活，此默认值都适用。 如果单击“ 确定” ，则会缓存文本框中指定的字符串和 “验证此连接” 选项值。 (如果单击“ 关闭 ”按钮或 “取消 ”，则会丢失任何新输入的特定于驱动程序的信息，因为文本框中指定的字符串和 “验证此连接 ”选项值未缓存。)

如果在第一个向导页中选择了 “文件数据源” ，则在选择了驱动程序并在“高级向导”页中输入关键字值后，系统会提示用户输入文件名。 单击“ 浏览 ”搜索文件名，在这种情况下， “浏览 ”框中的默认目录由 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion 中的 CommonFileDir 指定的路径和“ODBC\DataSources”的组合指定。 (如果 CommonFileDir 为“C：\Program Files\Common Files”，则默认目录为“C：\Program Files\Common Files\ODBC\Data Sources”。)

输入文件名并单击 “下一步” 时，系统会根据操作系统的标准文件命名规则检查输入的文件名的有效性。 如果文件名无效，则错误消息框会通知用户输入的文件名无效。 用户确认消息框后，焦点将返回到在其中输入文件名的向导页。 如果文件名有效，则会显示显示所选关键字值对的向导页以供审阅，如下图所示。

如果单击“完成”并将“文件数据源”选为数据源类型，并且“验证此连接”选项为 TRUE，则使用 SAVEFILE 和 DRIVER 关键字调用 SQLDriverConnect。 DriverCompletion 参数设置为 SQL_DRIVER_COMPLETE。 SAVEFILE 关键字的文件名是输入或选择的名称，DRIVER 关键字的驱动程序名称是所选的名称。 如果在“高级”向导页中指定了特定于驱动程序的连接字符串，则会在 DRIVER 关键字后面追加该字符串。

如果 SQLDriverConnect 返回SQL_SUCCESS，则驱动程序管理器已创建文件 DSN。 SQLCreateDataSource 返回 TRUE。 如果 SQLDriverConnect 未返回SQL_SUCCESS，则会显示一个警告消息框，指示无法与数据源建立连接。 仍然可以创建连接信息最少的 DSN。 此消息框允许用户取消或继续创建文件 DSN。

如果用户选择继续创建 DSN，此过程会继续，就像 “验证此连接 ”选项设置为 FALSE 一样。 如果用户选择取消，则 SQLCreateDataSource 返回 FALSE，错误代码为 ODBC_ERROR_CREATE_DSN_FAILED。

如果选择 了“文件数据源” 作为数据源类型，并且 “验证此连接 ”选项为 FALSE，则会使用 DRIVER 关键字和用户指定的连接字符串 (创建文件 DSN（如果“高级”向导页中有任何) ）。 如果文件创建成功，则为 SQLCreateDataSource 返回 TRUE。 如果文件创建不成功，错误消息框将通知用户从操作系统返回的任何错误。 SQLCreateDataSource 返回 FALSE，错误代码为 ODBC_ERROR_CREATE_DSN_FAILED。 有关文件数据源的详细信息，请参阅 使用文件数据源进行连接，或参阅 SQLDriverConnect。

如果选择用户或系统数据源作为数据源类型，则会使用 ODBC_ADD_DSN fRequest 调用驱动程序安装库中的 ConfigDSN。 有关详细信息，请参阅 ConfigDSN。

相关函数

有关以下方面的信息	请参阅
管理数据源	SQLManageDataSources