SQLDriverConnect 函数
一致性
引入的版本：ODBC 1.0 标准合规性：ODBC
摘要
SQLDriverConnect 是 SQLConnect 的替代方法。 它支持需要比 SQLConnect 中的三个参数更多的连接信息的数据源、提示用户输入所有连接信息的对话框，以及系统信息中未定义的数据源。 有关详细信息，请参阅 使用 SQLDriverConnect 进行连接。
语法
SQLRETURN SQLDriverConnect(
SQLHDBC ConnectionHandle,
SQLHWND WindowHandle,
SQLCHAR * InConnectionString,
SQLSMALLINT StringLength1,
SQLCHAR * OutConnectionString,
SQLSMALLINT BufferLength,
SQLSMALLINT * StringLength2Ptr,
SQLUSMALLINT DriverCompletion);
参数
ConnectionHandle
[输入] 连接句柄。
WindowHandle
[输入]窗口句柄。 应用程序可以传递父窗口的句柄（如果适用），如果窗口句柄不适用，或者 SQLDriverConnect 不会显示任何对话框，则传递 null 指针。
InConnectionString
[输入]完整的连接字符串 (查看“注释”) 、部分连接字符串或空字符串中的语法。
StringLength1
[输入]*InConnectionString 的长度，如果字符串为 Unicode，则以字符为单位;如果字符串为 ANSI 或 DBCS，则以字节为单位。
OutConnectionString
[输出]指向已完成连接字符串的缓冲区的指针。 成功连接到目标数据源后，此缓冲区包含已完成的连接字符串。 应用程序应为此缓冲区分配至少 1，024 个字符。
如果 OutConnectionString 为 NULL， StringLength2Ptr 仍将返回字符总数， (不包括字符数据的 null 终止字符，) OutConnectionString 指向的缓冲区中返回。
BufferLength
[输入]*OutConnectionString 缓冲区的 长度（以字符为单位）。
StringLength2Ptr
[输出]指向缓冲区的指针，该缓冲区将返回总字符数 (不包括 null 终止字符) 可在 *OutConnectionString 中返回。 如果可返回的字符数大于或等于 BufferLength，则 *OutConnectionString 中完成的连接字符串将被截断为 BufferLength 减去 null 终止字符的长度。
DriverCompletion
[输入]指示驱动程序管理器还是驱动程序必须提示输入更多连接信息的标志：
SQL_DRIVER_PROMPT、SQL_DRIVER_COMPLETE、SQL_DRIVER_COMPLETE_REQUIRED 或 SQL_DRIVER_NOPROMPT。
(有关其他信息，请参阅“注释”。)
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR、SQL_INVALID_HANDLE 或 SQL_STILL_EXECUTING。
诊断
当 SQLDriverConnect 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过使用 fHandleType 的 fHandleType 和 connectionHandle SQL_HANDLE_DBC 的 hHandle 调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLDriverConnect 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值：表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATE 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 01004 | 字符串数据，右截断 | 缓冲区 *OutConnectionString 不够大，无法返回整个连接字符串，因此连接字符串被截断。 非结构化连接字符串的长度在 *StringLength2Ptr 中返回。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 01S00 | 连接字符串属性无效 | 在 InConnectionString) 连接字符串 (指定了无效的 attribute 关键字，但驱动程序仍然能够连接到数据源。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 01S02 | 选项值已更改 | 驱动程序不支持 SQLSetConnectAttr 中的 ValuePtr 参数指向的指定值，并替换了类似的值。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 01S08 | 保存文件 DSN 时出错 | *InConnectionString 中的字符串包含一个 FILEDSN 关键字，但未保存 .dsn 文件。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 01S09 | 无效的关键字 | (DM) InConnectionString 中的字符串包含 SAVEFILE 关键字，但不包含 DRIVER 或 FILEDSN 关键字。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 08001 | 客户端无法建立连接 | 驱动程序无法与数据源建立连接。 |
| 08002 | 正在使用的连接名称 | (DM) 指定的 ConnectionHandle 已用于与数据源建立连接，并且连接仍处于打开状态。 |
| 08004 | 服务器拒绝连接 | 数据源出于实现定义的原因拒绝建立连接。 |
| 08S01 | 通信链接失败 | 在 SQLDriverConnect 函数完成处理之前，驱动程序与尝试连接的数据源之间的通信链接失败。 |
| 28000 | 授权规范无效 | 用户标识符或授权字符串或两者（如 InConnectionString) (连接字符串中指定的）违反了数据源定义的限制。 |
| HY000 | 常规错误 | 发生错误，其中没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec 在 *szMessageText 缓冲区中返回的错误消息描述了错误及其原因。 |
| HY000 | 常规错误：文件 dsn 无效 | (DM) InConnectionString 中的字符串包含一个 FILEDSN 关键字，但找不到 .dsn 文件的名称。 |
| HY000 | 常规错误：无法创建文件缓冲区 | (DM) InConnectionString 中的字符串包含一个 FILEDSN 关键字，但 .dsn 文件不可读。 |
| HY001 | 内存分配错误 | 驱动程序管理器无法分配支持执行或完成 SQLDriverConnect 函数所需的内存。 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY008 | 操作已取消 | 已为 ConnectionHandle 启用异步处理。 调用了函数，在它完成执行之前，在 ConnectionHandle 上调用了 SQLCancelHandle 函数，然后在 ConnectionHandle 上再次调用了 SQLDriverConnect 函数。 或者，调用了 SQLDriverConnect 函数，在它完成执行之前，在 ConnectionHandle 上从多线程应用程序中的其他线程调用了 SQLCancelHandle。 |
| HY010 | 函数序列错误 | (DM) 另一个异步执行的函数 (不是 SQLDriverConnect) 已为 ConnectionHandle 调用，并在调用 SQLDriverConnect 函数时仍在执行。 |
| HY013 | 内存管理错误 | 无法处理 SQLDriverConnect 函数调用，因为基础内存对象无法访问，可能是由于内存不足。 |
| HY090 | 无效的字符串或缓冲区长度 | (DM) 为参数 StringLength1 指定的值小于 0 且不等于 SQL_NTS。 (DM) 为参数 BufferLength 指定的值小于 0。 |
| HY092 | 无效的属性/选项标识符 | (DM) DriverCompletion 参数SQL_DRIVER_PROMPT， WindowHandle 参数为空指针。 |
| HY110 | 驱动程序完成无效 | (DM) 为参数 DriverCompletion 指定的值不等于 SQL_DRIVER_PROMPT、SQL_DRIVER_COMPLETE、SQL_DRIVER_COMPLETE_REQUIRED 或 SQL_DRIVER_NOPROMPT。 (DM) 连接池已启用，并且为参数 DriverCompletion 指定的值不等于SQL_DRIVER_NOPROMPT。 |
| HYC00 | 未实现可选功能 | 驱动程序不支持应用程序请求的 ODBC 行为的版本。 |
| HYT00 | 超时时间已到 | 与数据源的连接完成之前，登录超时期限已过期。 超时期限通过 SQLSetConnectAttr 设置，SQL_ATTR_LOGIN_TIMEOUT。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限是通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置的。 |
| IM001 | 驱动程序不支持此函数 | (DM) 与指定数据源名称对应的驱动程序不支持 函数。 |
| IM002 | 找不到数据源且未指定默认驱动程序 | (DM) 在系统信息中找不到 连接字符串 (InConnectionString) 中指定的数据源名称，也没有默认驱动程序规范。 在系统信息中找不到 (DM) ODBC 数据源和默认驱动程序信息。 |
| IM003 | 无法加载指定的驱动程序 | (DM) 系统信息中的数据源规范中列出的驱动程序或 DRIVER 关键字指定的驱动程序未找到或由于某种其他原因无法加载。 |
| IM004 | SQL_HANDLE_ENV 上的驱动程序的 SQLAllocHandle 失败 | (DM) SQLDriverConnect 期间，驱动程序管理器调用了驱动程序的 SQLAllocHandle 函数， fHandleType 为 SQL_HANDLE_ENV，驱动程序返回了错误。 |
| IM005 | SQL_HANDLE_DBC上的驱动程序的 SQLAllocHandle 失败。 | (DM) SQLDriverConnect 期间，驱动程序管理器使用 fHandleType SQL_HANDLE_DBC 调用驱动程序的 SQLAllocHandle 函数，驱动程序返回错误。 |
| IM006 | 驱动程序的 SQLSetConnectAttr 失败 | (DM) SQLDriverConnect 期间，驱动程序管理器调用了驱动程序的 SQLSetConnectAttr 函数，驱动程序返回了错误。 |
| IM007 | 未指定数据源或驱动程序;禁止对话 | 连接字符串中未指定数据源名称或驱动程序，并且SQL_DRIVER_NOPROMPT DriverCompletion 。 |
| IM008 | 对话框失败 | 驱动程序尝试显示其登录对话框，但失败。 WindowHandle 是一个 null 指针，并且 DriverCompletion 未SQL_DRIVER_NO_PROMPT。 |
| IM009 | 无法加载转换 DLL | 驱动程序无法加载为数据源或连接指定的转换 DLL。 |
| IM010 | 数据源名称太长 | (DM) DSN 关键字的属性值超过SQL_MAX_DSN_LENGTH个字符。 |
| IM011 | 驱动程序名称太长 | (DM) DRIVER 关键字的属性值超过 255 个字符。 |
| IM012 | DRIVER 关键字语法错误 | (DM) DRIVER 关键字的关键字值对包含语法错误。 (DM) InConnectionString 中的字符串包含 一个 FILEDSN 关键字，但 .dsn 文件不包含 DRIVER 关键字或 DSN 关键字。 |
| IM014 | 指定的 DSN 包含驱动程序和应用程序之间的体系结构不匹配 | (DM) 32 位应用程序使用连接到 64 位驱动程序的 DSN;反之亦然。 |
| IM015 | SQL_HANDLE_DBC_INFO_HANDLE上的驱动程序的 SQLDriverConnect 失败 | 如果驱动程序返回SQL_ERROR，驱动程序管理器将向应用程序返回SQL_ERROR，连接将失败。 有关SQL_HANDLE_DBC_INFO_TOKEN的详细信息，请参阅 在 ODBC 驱动程序中开发Connection-Pool感知。 |
| IM017 | 在异步通知模式下禁用轮询 | 每当使用通知模型时，轮询都将被禁用。 |
| IM018 | 尚未调用 SQLCompleteAsync 来完成此句柄上的上一个异步操作。 | 如果句柄上的上一个函数调用返回SQL_STILL_EXECUTING并且启用了通知模式，则必须在句柄上调用 SQLCompleteAsync 以执行后期处理并完成操作。 |
| S1118 | 驱动程序不支持异步通知 | 如果驱动程序不支持异步通知，则无法设置SQL_ATTR_ASYNC_DBC_EVENT或SQL_ATTR_ASYNC_DBC_RETCODE_PTR。 |
注释
连接字符串具有以下语法：
connection-string ：：= empty-string[;] | attribute[;] | attribute; connection-string
empty-string ：：=attribute ：：= attribute-keyword=attribute-value |DRIVER=[{]attribute-value[}]
attribute-keyword ：：= DSN |UID |PWD | driver-defined-attribute-keyword
attribute-value ：：= character-string
driver-defined-attribute-keyword ：：= identifier
其中 ，字符串 包含零个或多个字符; 标识符 包含一个或多个字符; attribute-keyword 不区分大小写; attribute-value 可能区分大小写;和 DSN 关键字的值不只包含空白。
由于连接字符串和初始化文件语法、关键字和属性值包含字符 []{} () ，;？ 应避免使用不带大括号的 *=！@ 。 DSN 关键字的值不能只包含空白，不应包含前导空格。 由于系统信息的语法，关键字和数据源名称不能包含反斜杠 (\) 字符。
应用程序不必在 DRIVER 关键字后添加属性值的大括号，除非属性包含分号 (;) ，在这种情况下需要大括号。 如果驱动程序接收的属性值包含大括号，则驱动程序不应删除它们，但它们应是返回的连接字符串的一部分。
用大括号括起来的 DSN 或连接字符串值 ({}) 包含任何字符 []{} () ，;？*=！@ 将原封不动地传递给驱动程序。 但是，在关键字中使用这些字符时，驱动程序管理器在使用文件 DSN 时会返回错误，但会将连接字符串传递给驱动程序以获取常规连接字符串。 避免在关键字值中使用嵌入的大括号。
连接字符串可能包含任意数量的驱动程序定义的关键字。 由于 DRIVER 关键字不使用系统信息中的信息，因此驱动程序必须定义足够的关键字，以便驱动程序只能使用连接字符串中的信息连接到数据源。 (有关详细信息，请参阅本节后面的“驱动程序指南”。) 驱动程序定义连接到数据源所需的关键字。
下表描述了 DSN、 FILEDSN、 DRIVER、 UID、 PWD 和 SAVEFILE 关键字的属性值。
| 关键字 | 属性值说明 |
|---|---|
| DSN | 由 SQLDataSources 或 SQLDriverConnect 的数据源对话框返回的数据源的名称。 |
| FILEDSN | 将从中为数据源生成连接字符串的 .dsn 文件的名称。 这些数据源称为文件数据源。 |
| 司机 | SQLDrivers 函数返回的驱动程序的说明。 例如，Rdb 或 SQL Server。 |
| UID | 用户 ID。 |
| PWD | 与用户 ID 对应的密码;如果没有用户 ID (PWD=;) 的密码，则为空字符串。 |
| SAVEFILE | .dsn 文件的文件名，其中应保存用于建立现有成功连接的关键字的属性值。 |
有关应用程序如何选择数据源或驱动程序的信息，请参阅 选择数据源或驱动程序。
如果在连接字符串中重复任何关键字，驱动程序将使用与关键字的第一个匹配项关联的值。 如果 DSN 和 DRIVER 关键字包含在同一连接字符串中，驱动程序管理器和驱动程序将使用最先显示的关键字。
FILEDSN 和 DSN 关键字互斥：使用第一个出现的关键字，忽略第二个出现的关键字。 另一方面， FILEDSN 和 DRIVER 关键字不是互斥的。 如果任何关键字出现在带 FILEDSN 的连接字符串中，则使用连接字符串中关键字的属性值，而不是 .dsn 文件中同一关键字的属性值。
如果使用 了 FILEDSN 关键字，则 .dsn 文件中指定的关键字将用于创建连接字符串。 (有关详细信息，请参阅本节后面的“文件数据源”。) UID 关键字是可选的;只能使用 DRIVER 关键字创建 .dsn 文件。 PWD 关键字不存储在 .dsn 文件中。 保存和加载 .dsn 文件的默认目录将是 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ Windows\CurrentVersion 和“ODBC\DataSources”中 CommonFileDir 指定的路径的组合。 (如果 CommonFileDir 为“C：\Program Files\Common Files”，则默认目录为“C：\Program Files\Common Files\ODBC\Data Sources”。)
注意
可以通过在安装程序 DLL 中调用 SQLReadFileDSN 和 SQLWriteFileDSN 函数直接操作 .dsn 文件。
如果使用 SAVEFILE 关键字，则用于建立现有成功连接的关键字的属性值将另存为具有 SAVEFILE 关键字属性值名称的 .dsn 文件。 SAVEFILE 关键字必须与 DRIVER 关键字和/或 FILEDSN 关键字结合使用，否则函数返回SQL_SUCCESS_WITH_INFO与 SQLSTATE 01S09 (无效关键字) 。 SAVEFILE 关键字必须显示在连接字符串中的 DRIVER 关键字之前，否则结果将未定义。
驱动程序管理器指南
驱动程序管理器构造一个连接字符串，以在驱动程序的 SQLDriverConnect 函数的 InConnectionString 参数中传递给驱动程序。 驱动程序管理器不会修改应用程序传递给它的 InConnectionString 参数。
驱动程序管理器的操作基于 DriverCompletion 参数的值：
SQL_DRIVER_PROMPT：如果连接字符串不包含 DRIVER、 DSN 或 FILEDSN 关键字，驱动程序管理器将显示“数据源”对话框。 它根据对话框返回的数据源名称以及应用程序传递给它的任何其他关键字构造连接字符串。 如果对话框返回的数据源名称为空，驱动程序管理器将指定关键字-值对 DSN=Default。 (此对话框不会显示名称为“Default”的数据源。)
SQL_DRIVER_COMPLETE或SQL_DRIVER_COMPLETE_REQUIRED：如果应用程序指定的连接字符串包含 DSN 关键字，驱动程序管理器将复制应用程序指定的连接字符串。 否则，它将执行与SQL_DRIVER_PROMPT DriverCompletion 时相同的操作。
SQL_DRIVER_NOPROMPT：驱动程序管理器复制应用程序指定的连接字符串。
如果应用程序指定的连接字符串包含 DRIVER 关键字，驱动程序管理器将复制应用程序指定的连接字符串。
使用已构造的连接字符串，驱动程序管理器确定要使用的驱动程序，连接到该驱动程序，并将已构造的连接字符串传递给驱动程序;有关驱动程序管理器与驱动程序交互的详细信息，请参阅 SQLConnect 函数中的“注释”部分。 如果连接字符串不包含 DRIVER 关键字，驱动程序管理器将确定要使用的驱动程序，如下所示：
如果连接字符串包含 DSN 关键字，驱动程序管理器将从系统信息中检索与数据源关联的驱动程序。
如果连接字符串不包含 DSN 关键字或找不到数据源，驱动程序管理器将从系统信息中检索与默认数据源关联的驱动程序。 (有关详细信息，请参阅 Default Subkey.) 驱动程序管理器将连接字符串中 DSN 关键字的值更改为“DEFAULT”。
如果连接字符串中的 DSN 关键字设置为“DEFAULT”，驱动程序管理器将从系统信息中检索与默认数据源关联的驱动程序。
如果未找到数据源且找不到默认数据源，驱动程序管理器将返回SQL_ERROR，其中 SQLSTATE IM002 (找不到数据源，并且未) 指定默认驱动程序。
文件数据源
如果应用程序在调用 SQLDriverConnect 时指定的连接字符串包含 FILEDSN 关键字，并且此关键字未由 DSN 或 DRIVER 关键字取代，则驱动程序管理器将使用 .dsn 文件和 InConnectionString 参数中的信息创建连接字符串。 驱动程序管理器按如下所示进行：
检查 .dsn 文件的文件名是否有效。 否则，它将返回 SQLSTATE IM014 (DSN) 文件名无效的SQL_ERROR。 如果文件名是空字符串 (“”) 且未指定SQL_DRIVER_NOPROMPT，则显示“ 文件打开 ”对话框。 如果文件名包含有效路径，但没有文件名或无效的文件名，并且未指定SQL_DRIVER_NOPROMPT，则显示“ 文件打开 ”对话框，并将当前目录设置为文件名中指定的目录。 如果文件名是空字符串 (“”) 或文件名包含有效路径，但没有文件名或无效文件名，并且指定了SQL_DRIVER_NOPROMPT，则返回SQL_ERROR与 SQLSTATE IM014 (无效的文件 DSN) 名称无效。
读取 .dsn 文件的 [ODBC] 节中的所有关键字。 如果 DRIVER 关键字不存在，则返回SQL_ERROR SQLSTATE IM012 (Driver 关键字语法错误) ，除非 .dsn 文件不可共享，因此仅包含 DSN 关键字。
如果文件数据源不可共享，驱动程序管理器将读取 DSN 关键字的值，并根据需要连接到不可共享文件数据源指向的用户或系统数据源。 不执行步骤 3 到步骤 5。
构造驱动程序的连接字符串。 驱动程序连接字符串是 .dsn 文件中指定的关键字与原始应用程序连接字符串中指定的关键字的并集。 关键字重叠的驱动程序连接字符串的构造规则如下所示：
如果应用程序连接字符串中存在 DRIVER 关键字，并且 DRIVER 关键字指定的驱动程序在 .dsn 文件和应用程序连接字符串中不相同，则忽略 .dsn 文件中的驱动程序信息，并使用应用程序连接字符串中的驱动程序信息。 如果 DRIVER 关键字指定的驱动程序在 .dsn 文件和应用程序的连接字符串中相同，则当所有关键字都重叠时，应用程序连接字符串中指定的驱动程序优先于 .dsn 文件中指定的关键字。
在新连接字符串中，将消除 FILEDSN 关键字。
通过查找注册表项HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\Driver Name>\<Driver，在其中<驱动程序名称>由 DRIVER 关键字指定来加载驱动程序。
向驱动程序传递新的连接字符串。
有关 .dsn 文件的示例，请参阅 使用文件数据源进行连接。
SAVEFILE 关键字
如果应用程序指定的连接字符串包含 SAVEFILE 关键字，驱动程序管理器会将连接字符串保存在 .dsn 文件中。 驱动程序管理器按如下所示进行：
检查作为 SAVEFILE 关键字的属性值包含的 .dsn 文件的文件名是否有效。 否则，它将返回 SQLSTATE IM014 (DSN) 文件名无效的SQL_ERROR。 文件名的有效性由标准系统命名规则确定。 如果文件名是空字符串 (“”) 且 DriverCompletion 参数未SQL_DRIVER_NOPROMPT，则文件名有效。 如果文件名已存在，则如果 SQL_DRIVER_NOPROMPT DriverCompletion ，则会覆盖该文件。 如果 DriverCompletion 是SQL_DRIVER_PROMPT、SQL_DRIVER_COMPLETE或SQL_DRIVER_COMPLETE_REQUIRED，则对话框将提示用户指定是否应覆盖该文件。 如果输入“否”，将显示“ 文件保存 ”对话框。
如果驱动程序返回SQL_SUCCESS且文件名不是空字符串，则驱动程序管理器会将 OutConnectionString 参数中返回的连接信息写入指定文件，并采用本节前面“连接字符串”部分中指定的格式。
如果驱动程序返回SQL_SUCCESS并且文件名是空字符串 (“”) ，则驱动程序管理器将使用指定的 hwnd 调用“文件保存”通用对话框，并将 OutConnectionString 中返回的连接信息写入到File-Save通用对话框中指定的文件，并使用本节前面“连接字符串”部分中指定的格式。
如果驱动程序返回SQL_SUCCESS，它将返回包含应用程序的连接字符串的 OutConnectionString 参数。
如果驱动程序返回SQL_SUCCESS_WITH_INFO或SQL_ERROR，则驱动程序管理器会将 SQLSTATE 返回到应用程序。
驱动程序指导原则
驱动程序检查驱动程序管理器传递给它的连接字符串是否包含 DSN 或 DRIVER 关键字。 如果连接字符串包含 DRIVER 关键字，则驱动程序无法从系统信息中检索有关数据源的信息。 如果连接字符串包含 DSN 关键字或不包含 DSN 或 DRIVER 关键字，则驱动程序可以从系统信息中检索有关数据源的信息，如下所示：
如果连接字符串包含 DSN 关键字，驱动程序将检索指定数据源的信息。
如果连接字符串不包含 DSN 关键字、找不到指定的数据源，或者 DSN 关键字设置为“DEFAULT”，驱动程序将检索默认数据源的信息。
驱动程序使用从系统信息中检索的任何信息来扩充在连接字符串中传递给它的信息。 如果系统信息中的信息与连接字符串中的信息重复，驱动程序将使用连接字符串中的信息。
根据 DriverCompletion 的值，驱动程序会提示用户输入连接信息（如用户 ID 和密码），并连接到数据源：
SQL_DRIVER_PROMPT：驱动程序显示一个对话框，使用连接字符串中的值和系统信息 (是否有任何) 作为初始值。 当用户退出对话框时，驱动程序将连接到数据源。 它还基于 *InConnectionString 中 DSN 或 DRIVER 关键字的值以及从对话框返回的信息构造连接字符串。 它将此连接字符串置于 *OutConnectionString 缓冲区中。
SQL_DRIVER_COMPLETE或SQL_DRIVER_COMPLETE_REQUIRED：如果连接字符串包含足够的信息，并且该信息正确，驱动程序将连接到数据源并将 *InConnectionString 复制到 *OutConnectionString。 如果任何信息缺失或不正确，驱动程序将采取与SQL_DRIVER_PROMPT DriverCompletion 时相同的操作，不同之处在于，如果SQL_DRIVER_COMPLETE_REQUIRED DriverCompletion ，驱动程序将禁用控件以获取连接到数据源不需要的任何信息。
SQL_DRIVER_NOPROMPT：如果连接字符串包含足够的信息，驱动程序将连接到数据源，并将 *InConnectionString 复制到 *OutConnectionString。 否则，驱动程序将返回 SQLDriverConnect 的SQL_ERROR。
成功连接到数据源后，驱动程序还会将 *StringLength2Ptr 设置为可在 *OutConnectionString 中返回的输出连接字符串的长度。
如果用户取消驱动程序管理器或驱动程序显示的对话框， SQLDriverConnect 将返回SQL_NO_DATA。
有关驱动程序管理器和驱动程序在连接过程中如何交互的信息，请参阅 SQLConnect 函数。
如果驱动程序支持 SQLDriverConnect，则驱动程序的系统信息的驱动程序关键字部分必须包含 ConnectFunctions 关键字，并将第二个字符设置为“Y”。
启用连接池时连接
连接池允许应用程序重复使用已创建的连接。 调用 SQLDriverConnect 时，驱动程序管理器会尝试使用已指定用于连接池的环境中的连接池中的连接来建立连接。 有关连接池的详细信息，请参阅 SQLConnect 函数。
在启用了池的连接上调用 SQLDisconnect 之前，应用程序可以设置SQL_ATTR_RESET_CONNECTION。 有关详细信息，请参阅 SQLSetConnectAttr 函数。
当应用程序调用 SQLDriverConnect 连接到共用连接时，以下限制适用：
在连接字符串中指定 SAVEFILE 关键字时，不会执行连接池处理。
如果启用了连接池，则只能使用 driverCompletion 参数 SQL_DRIVER_NOPROMPT 调用 SQLDriverConnect;如果使用任何其他 DriverCompletion 调用 SQLDriverConnect，则 SQLSTATE HY110 (将返回无效的驱动程序完成) 。
连接属性
SQL_ATTR_LOGIN_TIMEOUT连接属性（使用 SQLSetConnectAttr 设置）定义在返回应用程序之前，等待登录请求完成并成功由驱动程序完成的秒数。 如果提示用户完成连接字符串，则驱动程序启动连接过程时，将开始等待每个登录请求的等待期。
默认情况下，驱动程序以SQL_MODE_READ_WRITE访问模式打开连接。 若要将访问模式设置为 SQL_MODE_READ_ONLY，应用程序必须在调用 SQLDriverConnect 之前使用 SQL_ATTR_ACCESS_MODE 属性调用 SQLSetConnectAttr。
如果在数据源的系统信息中指定了默认转换库，驱动程序将加载该库。 可以通过使用 SQL_ATTR_TRANSLATE_LIB 属性调用 SQLSetConnectAttr 来加载不同的翻译库。 可以通过使用 SQL_ATTR_TRANSLATE_OPTION 选项调用 SQLSetConnectAttr 来指定转换选项。
有关详细信息，请参阅 使用 SQLDriverConnect 进行连接。
// SQLDriverConnect_ref.cpp
// compile with: odbc32.lib user32.lib
#include <windows.h>
#include <sqlext.h>
int main() {
SQLHENV henv;
SQLHDBC hdbc;
SQLHSTMT hstmt;
SQLRETURN retcode;
SQLCHAR OutConnStr[255];
SQLSMALLINT OutConnStrLen;
HWND desktopHandle = GetDesktopWindow(); // desktop's window handle
// Allocate environment handle
retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
// Set the ODBC version environment attribute
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);
// Allocate connection handle
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
// Set login timeout to 5 seconds
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);
retcode = SQLDriverConnect( // SQL_NULL_HDBC
hdbc,
desktopHandle,
(SQLCHAR*)"driver=SQL Server",
_countof("driver=SQL Server"),
OutConnStr,
255,
&OutConnStrLen,
SQL_DRIVER_PROMPT );
// Allocate statement handle
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
// Process data
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
}
SQLDisconnect(hdbc);
}
SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
}
}
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
}
另请参阅 示例 ODBC 程序。
相关函数
| 有关以下方面的信息 | 请参阅 |
|---|---|
| 分配句柄 | SQLAllocHandle 函数 |
| 发现和枚举连接到数据源所需的值 | SQLBrowseConnect 函数 |
| 连接到数据源 | SQLConnect 函数 |
| 断开与数据源的连接 | SQLDisconnect 函数 |
| 返回驱动程序说明和属性 | SQLDrivers 函数 |
| 释放句柄 | SQLFreeHandle 函数 |
| 设置连接属性 | SQLSetConnectAttr 函数 |