SQLDriverConnect 函数

一致性
推出版本：ODBC 1.0 标准合规：ODBC

总结
SQLDriverConnect 是 SQLConnect 的替代方案。 它支持需要比 SQLConnect 中三个参数更多的连接信息的数据源，提示用户提供所有连接信息的对话框，以及系统信息中未定义的数据源。 更多信息请参见 “与SQLDriverConnect连接”。

Syntax

  
SQLRETURN SQLDriverConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLHWND         WindowHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr,  
     SQLUSMALLINT    DriverCompletion);  

Arguments

ConnectionHandle
[输入] 连接句柄。

窗口柄
[输入]窗户把手。 应用程序可以传递父窗口的句柄（如适用），若窗口句柄不适用或 SQLDriverConnect 不显示任何对话框，则可传递空指针。

连接字符串
[输入]完整的 连接字符串（参见“注释”中的语法）、部分 连接字符串，或空字符串。

字符串长度1
[输入]*InConnectionString 的长度，如果字符串是 Unicode，则以字符为单位;如果字符串是 ANSI 或 DBCS，则以字节为单位。

连接外线
[输出]指向已完成连接字符串的缓冲区。 成功连接到目标数据源后，该缓冲区包含已完成的连接字符串。 应用程序应为该缓冲区分配至少1024个字符。

如果 OutConnectionString 是 NULL，StringLength2Ptr 仍然会返回 OutConnectionString 指向的缓冲区中可返回的字符总数（不含字符数据的空终止字符）。

BufferLength
[输入]*OutConnectionString 缓冲区的长度，以字符为单位。

弦长2Ptr
[输出]指向一个缓冲区，返回*OutConnectionString中可返回的字符总数（不含空终止字符）。 如果可返回的字符数大于或等于BufferLength，则*OutConnectionString中已完成的连接字符串将截断为BufferLength减去空终止字符的长度。

驱动完成
[输入]指示驱动程序管理器或驱动程序是否必须提示更多连接信息的标志：

SQL_DRIVER_PROMPT、SQL_DRIVER_COMPLETE、SQL_DRIVER_COMPLETE_REQUIRED或SQL_DRIVER_NOPROMPT。

（更多信息请参见“评论”。）

Returns

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR、SQL_INVALID_HANDLE或SQL_STILL_EXECUTING。

Diagnostics

当 SQLDriverConnect 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用 SQLGetDiagRec 获得关联的 SQLSTATE 值，fHandleType 为 SQL_HANDLE_DBC，hHandle 为 ConnectionHandle。 下表列出 了SQLDriverConnect 通常返回的SQLSTATE值，并在该函数的上下文中解释了每个值;“（DM）” 符号位于驱动程序管理器返回的 SQLSTATE 描述之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。

注释

连接字符串 具有以下语法：

连接字符串 ：：= 空字符串[;] | attribute[;] | 属性; 连接字符串

空字符串 ：：=属性 ：：= attribute-关键字=attribute-value |DRIVER=[{]attribute-value[}]

attribute-keyword ：：= DSN |UID |残疾人 | 驱动程序定义属性关键词

attribute-value ：：= 字符字符串

驱动程序定义属性关键词 ：：= 标识符

其中字符串为零个或多个字符;标识符包含一个或多个字符;attribute-keyword 不区分大小写;属性值可以区分大小写;DSN关键字的价值并非仅仅由空白组成。

由于连接字符串和初始化文件语法、关键词和包含字符[]{}（），;？）的属性值的限制*=！@ 未用支架包裹的物品应避免。 DSN 关键字的值不能仅包含空白，不应包含前导空白。 由于系统信息的语法，关键字和数据源名称不能包含反斜杠 （\） 字符。

应用程序无需在 DRIVER 关键字后为属性值加大括号，除非该属性包含分号（;)，此时需要大括号。 如果驱动程序接收的属性值包括大括号，则驱动程序不应删除它们，但它们应是返回的连接字符串的一部分。

一个用大括号（{}）包围的DSN或连接字符串值，包含任意字符[]{}（），;？*=！@ 完整传递给驾驶员。 然而，当在关键词中使用这些字符时，驱动程序管理器在处理文件DSN时会返回错误，但将连接字符串传递给驱动程序，用于常规连接字符串。 避免在关键字值中使用嵌入大括号。

连接字符串可以包含任意数量的驱动程序定义的关键字。 由于DRIVER关键字不使用系统信息，驱动程序必须定义足够多的关键词，使驱动程序仅凭连接字符串中的信息连接数据源。 （更多信息请参见本节后文的“驾驶员指南”。）驱动程序定义连接数据源所需的关键词。

下表描述了DSN、FILEDSN、DRIVER、UID、PWD和SAVEFILE关键字的属性值。

有关应用程序如何选择数据源或驱动程序的信息，请参见 “选择数据源或驱动程序”。

如果连接字符串中出现任何关键词，驱动程序使用该关键词首次出现时的值。 如果DSN和DRIVER关键字包含在同一个连接字符串中，驱动程序管理器和驱动程序使用先出现的关键字。

FILEDSN和DSN这两个关键词互斥：先出现的那个被使用，第二个出现的则被忽略。 而 FILEDSN 和 DRIVER 关键词则不互斥。 如果任何关键词出现在带有 FILEDSN 的 连接字符串 中，则使用 连接字符串 中关键词的属性值，而不是 .dsn 文件中同一关键字的属性值。

如果使用FILEDSN关键字，则使用.dsn文件中指定的关键词来创建连接字符串。 （更多信息请参见本节后面的“文件数据源”。） UID 关键字为可选;.dsn 文件可以仅包含 DRIVER 关键字。 PWD 关键字不存储在 .dsn 文件中。 保存和加载.dsn文件的默认目录将是CommonFileDir在 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ Windows\CurrentVersion中指定的路径和“ODBC\DataSources”的组合。 （如果 CommonFileDir 是“C：\Program Files\Common Files”，默认目录将是“C：\Program Files\Common Files\ODBC\Data Sources”。）

如果使用 了 SAVEFILE 关键字，用于建立当前成功连接的关键词属性值将保存为带有 SAVEFILE 关键字属性值名称的 .dsn 文件。 SAVEFILE 关键字必须与 DRIVER 关键字、FILEDSN 关键字或两者同时使用，否则函数返回 SQL_SUCCESS_WITH_INFO SQLSTATE 01S09（无效关键字）。 SAVEFILE 关键字必须出现在 连接字符串 中 DRIVE 关键字之前，否则结果将未定义。

司机经理指南

驱动程序管理器构造一个传递给驱动程序的 SQLDriverConnect 函数 InConnectionString 参数的 连接字符串。 驱动程序管理器不会修改应用程序传递给它的 InConnectionString 参数。

驱动程序管理器的操作基于 DriverCompletion 参数的值：

• SQL_DRIVER_PROMPT：如果连接字符串中没有驱动程序、DSN或FILEDSN关键字，驱动程序管理器会显示数据源对话框。 它从对话框返回的数据源名称和应用程序传递给它的其他关键词构建一个连接字符串。 如果对话框返回的数据源名称为空，驱动程序管理器会指定关键词-值对 DSN=Default。 （此对话框不会显示名为“Default”的数据源。）

• SQL_DRIVER_COMPLETE或SQL_DRIVER_COMPLETE_REQUIRED：如果应用程序指定的连接字符串包含DSN关键字，驱动程序管理器会复制应用程序指定的连接字符串。 否则，它会采取与 DriverCompletion SQL_DRIVER_PROMPT时相同的操作。

• SQL_DRIVER_NOPROMPT：驱动程序管理器复制应用程序指定的连接字符串。

如果应用程序指定的 连接字符串 包含 DRIVER 关键字，驱动程序管理器会复制应用程序指定的 连接字符串。

驱动程序管理器利用它构建的 连接字符串，决定使用哪个驱动程序，连接到该驱动程序，并将构建的 连接字符串 传递给驱动程序;关于驱动程序管理器与驱动程序交互的更多信息，请参见 SQLConnect 函数中的“注释”部分。 如果 连接字符串 不包含 DRIVER 关键字，驱动程序管理器会根据以下方式决定使用哪个驱动程序：

1. 如果连接字符串包含DSN关键字，驱动程序管理器会从系统信息中检索与数据源相关的驱动程序。

2. 如果连接字符串中没有DSN关键字或找不到数据源，驱动程序管理器会从系统信息中检索与默认数据源相关的驱动程序。 （更多信息请参见默认子密钥。）驱动程序管理器将 连接字符串 中 DSN 关键字的值更改为“DEFAULT”。

3. 如果连接字符串中的DSN关键字设置为“DEFAULT”，驱动程序管理器会从系统信息中检索与默认数据源相关的驱动程序。

4. 如果找不到数据源且未找到默认数据源，驱动程序管理器会返回SQL_ERROR SQLSTATE IM002（未找到数据源且未指定默认驱动）。

文件数据源

如果应用程序在调用 SQLDriverConnect 时指定的 连接字符串 包含 FILEDSN 关键字，且该关键字没有被 DSN 或 DRIVER 关键字取代，那么驱动程序管理器会利用 .dsn 文件中的信息和 InConnectionString 参数创建一个 连接字符串。 驾驶员经理的操作如下：

1. 检查.dsn文件名是否有效。 如果没有，则返回SQL_ERROR SQLSTATE IM014（文件 DSN 名称无效）。 如果文件名是空字符串（“”）且未指定SQL_DRIVER_NOPROMPT，则显示 文件打开 对话框。 如果文件名包含有效路径但没有文件名或文件名无效，且未指定SQL_DRIVER_NOPROMPT，则显示 文件打开 对话框，当前目录设置为文件名中指定的目录。 如果文件名是空字符串（“”），或者文件名包含有效路径但没有文件名或文件名无效，且指定了SQL_DRIVER_NOPROMPT，则SQL_ERROR返回时会返回SQLSTATE IM014（文件DSN无效名称）。

2. 读取.dsn文件[ODBC]部分中的所有关键词。 如果没有 DRIVER 关键字，则返回 SQL_ERROR，SQLSTATE IM012（Driver 关键字语法错误），除非 .dsn 文件不可共享，因此只包含 DSN 关键字。

   如果文件数据源不可共享，驱动管理器读取 DSN 关键字的值，并根据需要连接到不可共享文件源指向的用户或系统数据源。 第3到第5步不执行。

3. 为驱动程序构建一个连接字符串。 驱动程序的 连接字符串 是 .dsn 文件中指定的关键词与原始应用 连接字符串 中指定关键字的并集。 关键词重叠的驱动程序连接字符串的构建规则如下：

   • 如果 DRIVER 关键字存在于 Application 连接字符串 中，且 DRIVER 关键字指定的驱动程序在 .dsn 文件和应用 连接字符串 中不一致，则忽略 .dsn 文件中的驱动程序信息，改用应用 连接字符串 中的驱动程序信息。 如果 DRIVER 关键字指定的驱动程序在 .dsn 文件中与应用程序的 连接字符串 相同，那么在所有关键字重叠时，应用程序 连接字符串 中指定的驱动程序优先于 .dsn 文件中指定的。

   • 在新的连接字符串中，FILEDSN关键字被删除。

4. 通过查找 Driver Name>\Driver <注册表条目中 DRIVER 名称 HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\<DRIVER 关键字>来加载驱动。

5. 把新的连接线传递给驱动器。

关于 .dsn 文件的示例，请参见 使用文件数据源连接。

SAVEFILE 关键词

如果应用程序指定的 连接字符串 包含 SAVEFILE 关键字，则驱动程序管理器会将该 连接字符串 保存在 .dsn 文件中。 驾驶员经理的操作如下：

1. 检查作为 SAVEFILE 关键字属性值所包含的 .dsn 文件名是否有效。 如果没有，则返回SQL_ERROR SQLSTATE IM014（文件 DSN 名称无效）。 文件名的有效性由标准系统命名规则决定。 如果文件名是空字符串（“”）且 DriverCompletion 参数未被SQL_DRIVER_NOPROMPT，则该文件名有效。 如果文件名已经存在，那么如果 DriverCompletion SQL_DRIVER_NOPROMPT，文件就会被覆盖。 如果 DriverCompletion 是 SQL_DRIVER_PROMPT、SQL_DRIVER_COMPLETE 或 SQL_DRIVER_COMPLETE_REQUIRED，会提示对话框提示用户指定是否覆盖该文件。 如果输入“否”，则会出现 “保存文件 ”对话框。

2. 如果驱动程序返回SQL_SUCCESS且文件名不是空字符串，则驱动程序管理器会将 OutConnectionString 参数中返回的连接信息写入指定文件，格式为本节前述“连接字符串”部分中指定的格式。

3. 如果驱动程序返回SQL_SUCCESS且文件名为空字符串（“”），则驱动程序管理器调用指定hwnd的文件保存公共对话框，并将OutConnectionString中返回的连接信息写入 File-Save 通用对话框中指定的文件，格式为本节前述“连接字符串”部分中指定的格式。

4. 如果驱动程序返回SQL_SUCCESS，则返回包含连接字符串的 OutConnectionString 参数给应用程序。

5. 如果驱动程序返回SQL_SUCCESS_WITH_INFO或 SQL_ERROR，驱动程序管理器会将 SQLSTATE 返回给应用程序。

驾驶员指南

驱动程序检查驱动程序管理器传递给它的连接字符串是否包含DSN或DRIVER关键字。 如果连接字符串包含DRIVER关键字，驱动程序无法从系统信息中获取数据源信息。 如果连接字符串包含DSN关键字，或者不包含DSN或DRIVER关键字，驱动程序可以从系统信息中检索数据源信息，方法如下：

1. 如果连接字符串包含DSN关键字，驱动程序会检索指定数据源的信息。

2. 如果连接字符串中没有DSN关键字，找不到指定的数据源，或DSN关键字被设置为“DEFAULT”，驱动程序会获取默认数据源的信息。

驱动程序利用从系统信息中获取的任何信息来增强连接连接字符串中传递给它的信息。 如果系统信息中的信息与连接字符串中的信息重复，驱动程序会使用该连接字符串中的信息。

基于 DriverCompletion的值，驱动会提示用户输入连接信息，如用户ID和密码，并连接到数据源：

• SQL_DRIVER_PROMPT：驱动程序显示一个对话框，使用来自连接字符串和系统信息（如有）的值作为初始值。 当用户退出对话框时，驱动程序连接到数据源。 它还会根据 *InConnectionString 中的 DSN 或 DRIVER 关键字值和对话框返回的信息构建一个 连接字符串。 它将该 连接字符串 放置在 *OutConnectionString 缓冲区中。

• SQL_DRIVER_COMPLETE或SQL_DRIVER_COMPLETE_REQUIRED：如果连接字符串包含足够信息且信息正确，驱动程序连接到数据源，并将 *InConnectionString 复制到 *OutConnectionString。 如果有缺失或错误的信息，驱动程序采取与SQL_DRIVER_PROMPT驱动 完成 时相同的操作， 但如果SQL_DRIVER_COMPLETE_REQUIRED 驱动完成，驱动会禁用所有非连接数据源所需的信息控制。

• SQL_DRIVER_NOPROMPT：如果连接字符串包含足够信息，驱动连接到数据源，并将 *InConnectionString 复制到 *OutConnectionString。 否则，驱动返回SQL_ERROR SQLDriverConnect。

成功连接数据源后，驱动程序还将 *StringLength2Ptr 设置为输出 连接字符串 的长度，该 [连接字符串 可返回于 *OutConnectionString 中]。

如果用户取消驱动程序管理器或驱动程序显示的对话框， SQLDriverConnect 会返回SQL_NO_DATA。

有关驱动管理器与驱动在连接过程中如何交互的信息，请参见 SQLConnect 函数。

如果驱动程序支持 SQLDriverConnect，驱动程序系统信息中的驱动程序关键字部分必须包含 ConnectFunctions 关键字，第二个字符设置为“Y”。

启用连接池时的连接

连接池允许应用程序重用已创建的连接。 当调用 SQLDriverConnect 时，驱动程序管理器尝试使用一个连接池中的连接，该连接池被指定为连接池。 有关连接池的更多信息，请参见 SQLConnect 函数。

应用程序可以在启用池化连接前设置SQL_ATTR_RESET_CONNECTION，然后调用 SQLDisconnect。 有关详细信息，请参阅 SQLSetConnectAttr 函数。

当应用程序调用 SQLDriverConnect 连接池连接时，以下限制适用：

• 当 连接字符串 中指定 SAVEFILE 关键字时，不进行连接池处理。

• 如果启用了连接池， SQLDriverConnect 只能用 DriverCompletion 参数 SQL_DRIVER_NOPROMPT 来调用;如果调用 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项目示例。

相关函数

另请参阅

ODBC API 参考
ODBC 头文件