SQLBrowseConnect 函数

项目
07/04/2024

一致性
引入的版本：ODBC 1.0 标准符合性：ODBC

总结
SQLBrowseConnect 支持一种迭代方法，用于发现和枚举连接到数据源所需的特性和属性值。每次调用 SQLBrowseConnect 都会返回属性和属性值的连续级别。枚举所有级别后，将完成与数据源的连接，SQLBrowseConnect 将返回完整的连接字符串。 SQL_SUCCESS或SQL_SUCCESS_WITH_INFO的返回代码指示已指定所有连接信息，并且应用程序现在已连接到数据源。

语法

  
SQLRETURN SQLBrowseConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr);

参数

ConnectionHandle
[输入] 连接句柄。

InConnectionString
[输入]浏览请求连接字符串（请参阅“注释”中的“InConnectionString 参数”）。

StringLength1
[输入]字符中 *InConnectionString 的长度。

OutConnectionString
[输出]指向要返回浏览结果的字符缓冲区的指针连接字符串（请参阅“注释”中的“OutConnectionString 参数”）。

如果 OutConnectionString 为 NULL，StringLength2Ptr 仍将返回可用于在 OutConnectionString 指向的缓冲区中返回的字符总数（不包括字符数据的 null 终止字符）。

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

StringLength2Ptr
[输出]可用于在 *OutConnectionString 中返回的字符总数（不包括 null 终止）。如果可用于返回的字符数大于或等于 BufferLength，则 *OutConnectionString 中的连接字符串将被截断为 BufferLength 减去 null 终止字符的长度。

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

诊断

当 SQLBrowseConnect 返回SQL_ERROR、SQL_SUCCESS_WITH_INFO或SQL_NEED_DATA时，可以通过使用 handleType of SQL_HANDLE_STMT 和 ConnectionHandle 句柄调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。下表列出了 SQLBrowseConnect 通常返回的 SQLSTATE 值，并解释此函数上下文中的每个值;表示法“（DM）”位于驱动程序管理器返回的 SQLSTATE 说明之前。除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。

SQLSTATE	错误	说明
01000	常规警告	特定于驱动程序的信息性消息。（函数返回SQL_SUCCESS_WITH_INFO。）
01004	字符串数据，右截断	缓冲区 *OutConnectionString 不足以返回整个浏览结果连接字符串，因此字符串被截断。缓冲区 *StringLength2Ptr 包含未构造的浏览结果连接字符串的长度。（函数返回SQL_NEED_DATA。）
01S00	无效连接字符串属性	在浏览请求连接字符串（InConnectionString）中指定了无效的属性关键字。（函数返回SQL_NEED_DATA。）在浏览请求连接字符串（InConnectionString）中指定了一个不适用于当前连接级别的属性关键字。（函数返回SQL_NEED_DATA。）
01S02	值已更改	驱动程序不支持 SQLSetConnectAttr 中 ValuePtr 参数的指定值，并替换了类似的值。（函数返回SQL_SUCCESS_WITH_INFO。）
08001	客户端无法建立连接	驱动程序无法与数据源建立连接。
08002	正在使用的连接名称	（DM）指定的连接已用于与数据源建立连接，并且连接已打开。
08004	服务器拒绝了连接	数据源拒绝为实现定义的原因建立连接。
08S01	通信链接失败	驱动程序和驱动程序尝试连接到的数据源之间的通信链接在函数完成处理之前失败。
28000	授权规范无效	用户标识符或授权字符串或两者（如浏览请求连接字符串（InConnectionString）中指定的两者都违反了数据源定义的限制。
HY000	常规错误	发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。
HY001	内存分配错误	（DM）驱动程序管理器无法分配支持执行或完成函数所需的内存。驱动程序无法分配支持执行或完成函数所需的内存。
HY008	操作已取消	通过调用 SQLCancelHandle 函数取消了异步操作。然后，在 ConnectionHandle 上再次调用原始函数。通过在 ConnectionHandle 上从多线程应用程序中的不同线程调用 SQLCancelHandle 来取消操作。
HY010	函数序列错误	（DM）为 ConnectionHandle 调用异步执行函数（而不是此函数），并在调用此函数时仍在执行。
HY013	内存管理错误	无法处理函数调用，因为基础内存对象无法访问，可能是因为内存条件低。
HY090	字符串或缓冲区长度无效	（DM）为参数 StringLength1 指定的值小于 0，且不等于SQL_NTS。（DM）为参数 BufferLength 指定的值小于 0。
HY114	驱动程序不支持连接级别异步函数执行	（DM）应用程序在建立连接之前在连接句柄上启用了异步操作。但是，驱动程序不支持对连接句柄执行异步操作。
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）在 SQLBrowseConnect 期间，驱动程序管理器使用 handleType SQL_HANDLE_ENV调用驱动程序的 SQLAllocHandle 函数，驱动程序返回了错误。
IM005	SQL_HANDLE_DBC上的驱动程序 SQLAllocHandle 失败	（DM）在 SQLBrowseConnect 期间，驱动程序管理器使用 handleType 为 SQL_HANDLE_DBC 调用驱动程序的 SQLAllocHandle 函数，驱动程序返回了错误。
IM006	驱动程序的 SQLSetConnectAttr 失败	（DM）在 SQLBrowseConnect 期间，驱动程序管理器称为驱动程序的 SQLSetConnectAttr 函数，驱动程序返回了错误。
IM009	无法加载翻译 DLL	驱动程序无法加载为数据源或连接指定的转换 DLL。
IM010	数据源名称太长	（DM） DSN 关键字的属性值超过SQL_MAX_DSN_LENGTH个字符。
IM011	驱动程序名称太长	（DM） DRIVER 关键字的属性值超过 255 个字符。
IM012	DRIVER 关键字语法错误	（DM） DRIVER 关键字的关键字值对包含语法错误。
IM014	指定的 DSN 包含驱动程序与应用程序之间的体系结构不匹配	（DM） 32 位应用程序使用连接到 64 位驱动程序的 DSN;反之亦然。
IM017	在异步通知模式下禁用轮询	每当使用通知模型时，轮询将被禁用。
IM018	尚未调用 SQLCompleteAsync 来完成此句柄上的上一个异步操作。	如果句柄上的上一个函数调用返回SQL_STILL_EXECUTING并且启用通知模式，则必须在句柄上调用 SQLCompleteAsync 才能执行后期处理并完成操作。
S1118	驱动程序不支持异步通知	当驱动程序不支持异步通知时，无法设置SQL_ATTR_ASYNC_DBC_EVENT或SQL_ATTR_ASYNC_DBC_RETCODE_PTR。

InConnectionString 参数

浏览请求连接字符串具有以下语法：

connection-string ：：= attribute[;] | 属性 ; 连接字符串;
attribute ：：= attribute-keyword=attribute-value[{]attribute-value | DRIVER=[]}
attribute-keyword ：：= DSNPWD | UID | | driver-defined-attribute-keyword
attribute-value ：：= character-string
driver-defined-attribute-keyword ：：= identifier

其中，字符串包含零个或多个字符; 标识符有一个或多个字符; attribute-keyword 不区分大小写; 特性值可能区分大小写;DSN 关键字的值不只包含空白。由于连接字符串和初始化文件语法、包含字符 []{}（），;的关键字和属性值？应避免 *=！@ 。由于系统信息中的语法，关键字和数据源名称不能包含反斜杠（\）字符。对于 ODBC 2。x 驱动程序，在 DRIVER 关键字的属性值周围需要大括号。

如果在浏览请求连接字符串中重复任何关键字，驱动程序将使用与关键字的第一个匹配项关联的值。 如果 DSN 和 DRIVER 关键字包含在相同的浏览请求连接字符串中，驱动程序管理器和驱动程序会首先使用哪个关键字。

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

OutConnectionString 参数

浏览结果连接字符串是连接属性的列表。连接属性由属性关键字和相应的属性值组成。浏览结果连接字符串具有以下语法：

connection-string ：：= attribute[;] | attribute ; connection-string
attribute ：：= [*]attribute-keyword=attribute-value
attribute-keyword ：：= ODBC-attribute-keyword | driver-defined-attribute-keyword
ODBC-attribute-keyword = {UIDPWD | }[:localized-identifier] driver-defined-attribute-keyword ：：= identifier[:localized-identifier] attribute-value ：：= { attribute-value-list? } | （大括号是文本;它们由驱动程序返回）。
attribute-value-list ：：= character-string [:localized-character string] | character-string [:localized-character string] , attribute-value-list

其中 ，字符串 和 本地化字符字符串 包含零个或多个字符; 标识符 和 本地化标识符 具有一个或多个字符; attribute-keyword 不区分大小写;属性值可能区分大小写。由于连接字符串和初始化文件语法、关键字、本地化标识符和包含字符 []{}（），; 的属性值？应避免 *=！@ 。由于系统信息中的语法，关键字和数据源名称不能包含反斜杠（\）字符。

浏览结果连接字符串语法根据以下语义规则使用：

如果星号 \ 在 attribute-keyword 前面，则属性是可选的，可以在下一次调用 SQLBrowseConnect 时省略该属性。
属性关键字 UID 和 PWD 的含义与在 SQLDriverConnect 中定义的含义相同。
driver-defined-attribute-keyword 为可能为其提供属性值的属性类型命名。例如，它可能是 SERVER、 DATABASE、 HOST 或 DBMS。
ODBC-attribute-keywords 和 driver-defined-attribute-keywords 包含关键字的本地化版本或用户友好版本。应用程序可能将其用作对话框中的标签。但是， 将浏览请求字符串传递给驱动程序时，必须单独使用 UID、 PWD 或 标识符 。
{attribute-value-list} 是对相应 attribute-keyword 有效的实际值的枚举。请注意，大括号（{}）不指示选项列表;它们由驱动程序返回。例如，它可能是服务器名称的列表或数据库名称的列表。
如果特性值是单个问号（？），则单个值对应于 attribute-keyword。例如，UID=JohnS;PWD=Sesame。
每次调用 SQLBrowseConnect 仅返回满足下一级连接过程所需的信息。驱动程序将状态信息与连接句柄相关联，以便始终可以在每次调用时确定上下文。

使用 SQLBrowseConnect

SQLBrowseConnect 需要分配的连接。驱动程序管理器加载在初始浏览请求连接字符串中指定的或对应于数据源名称的驱动程序;有关何时发生此情况的信息，请参阅 SQLConnect 函数中的“注释”部分。驱动程序可能会在浏览过程中与数据源建立连接。如果 SQLBrowseConnect 返回SQL_ERROR，则会终止未完成的连接，并将连接返回到未连接状态。

注意

SQLBrowseConnect 不支持连接池。如果在 启用连接池时调用 SQLBrowseConnect ，将返回 SQLSTATE HY000 （常规错误）。

首次在连接上调用 SQLBrowseConnect 时，浏览请求连接字符串必须包含 DSN 关键字或 DRIVER 关键字。如果浏览请求连接字符串包含 DSN 关键字，驱动程序管理器在系统信息中找到相应的数据源规范：

如果驱动程序管理器找到相应的数据源规范，它将加载关联的驱动程序 DLL;驱动程序可以从系统信息中检索有关数据源的信息。
如果驱动程序管理器找不到相应的数据源规范，它将找到默认数据源规范并加载关联的驱动程序 DLL;驱动程序可以从系统信息中检索有关默认数据源的信息。 “DEFAULT”将传递给 DSN 的驱动程序。
如果驱动程序管理器找不到相应的数据源规范，并且没有默认数据源规范，则会返回 SQLSTATE IM002 SQL_ERROR（找不到数据源且未指定默认驱动程序）。

如果浏览请求连接字符串包含 DRIVER 关键字，驱动程序管理器将加载指定的驱动程序;它不会尝试在系统信息中找到数据源。 由于 DRIVER 关键字不使用系统信息中的信息，因此驱动程序必须定义足够的关键字，以便驱动程序只能使用浏览请求中的信息连接到数据源连接字符串。

每次调用 SQLBrowseConnect 时，应用程序都会指定浏览请求中的连接属性值连接字符串。驱动程序在浏览结果连接字符串中返回连续级别的属性和属性值;只要在浏览请求连接字符串中尚未枚举连接属性，它就返回SQL_NEED_DATA。应用程序使用浏览结果的内容连接字符串生成浏览请求，连接字符串对 SQLBrowseConnect 的下一次调用。对 SQLBrowseConnect 的下一次调用中必须包括所有必需的属性（这些属性前面没有星号）。 请注意，在生成当前浏览请求连接字符串时，应用程序无法使用以前的浏览结果连接字符串的内容;也就是说，它不能为上一级别中设置的属性指定不同的值。

枚举所有级别的连接及其关联的属性后，驱动程序将返回SQL_SUCCESS、与数据源的连接已完成，并将完整的连接字符串返回到应用程序。连接字符串适合与 SQLDriverConnect 结合使用，并使用SQL_DRIVER_NOPROMPT选项建立另一个连接。但是，不能在另一次调用 SQLBrowseConnect 中使用完整的连接字符串;但是，如果再次调用 SQLBrowseConnect，则必须重复整个调用序列。

SQLBrowseConnect 还返回SQL_NEED_DATA，如果在浏览过程中存在可恢复的非严重错误;例如，应用程序提供的密码或属性关键字无效。返回SQL_NEED_DATA且浏览结果连接字符串不变时，发生了错误，应用程序可以调用 SQLGetDiagRec 返回 SQLSTATE 以获取浏览时错误。这样，应用程序便可以更正属性并继续浏览。

应用程序可以通过调用 SQLDisconnect 随时终止浏览进程。驱动程序将终止任何未完成的连接，并将连接返回到未连接状态。

如果在连接句柄上启用了异步操作， SQLBrowseConnect 也可能返回SQL_STILL_EXECUTING。返回SQL_NEED_DATA时，应用程序必须使用 SQLDisconnect 来取消浏览过程。如果 SQLBrowseConnect 返回SQL_STILL_EXECUTING，应用程序应使用 SQLCancelHandle 取消正在进行的操作。在函数返回SQL_NEED_DATA后调用 SQLCancelHandle 不起作用。

有关详细信息，请参阅使用 SQLBrowseConnect 进行连接。

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

代码示例

注意

如果要连接到支持 Windows 身份验证的数据源提供程序，则应指定 Trusted_Connection=yes，而不是连接字符串中的用户 ID 和密码信息。

在以下示例中，应用程序重复调用 SQLBrowseConnect 。每次 SQLBrowseConnect 返回SQL_NEED_DATA时，都会传回有关 *OutConnectionString 中所需数据的信息。应用程序将 OutConnectionString 传递给其例程 GetUserInput（未显示）。 GetUserInput 分析信息、生成和显示对话框，并返回用户在 *InConnectionString 中输入的信息。在下一次调用 SQLBrowseConnect 时，应用程序会将用户的信息传递给驱动程序。应用程序提供驱动程序连接到数据源所需的所有信息后， SQLBrowseConnect 将返回SQL_SUCCESS，应用程序继续。

有关通过调用 SQLBrowseConnect 连接到 SQL Server 驱动程序的更详细示例，请参阅 SQL Server 浏览示例。

例如，若要连接到数据源 Sales，可能会执行以下操作。首先，应用程序将以下字符串传递给 SQLBrowseConnect：

"DSN=Sales"

驱动程序管理器加载与数据源 Sales 关联的驱动程序。然后，它使用从应用程序收到的相同参数调用驱动程序的 SQLBrowseConnect 函数。驱动程序在 *OutConnectionString 中返回以下字符串：

"HOST:Server={red,blue,green};UID:ID=?;PWD:Password=?"

应用程序将此字符串传递给其 GetUserInput 例程，该例程生成一个对话框，要求用户选择红色、蓝色或绿色服务器并输入用户 ID 和密码。例程在 *InConnectionString 中传递以下用户指定的信息，应用程序将这些信息传递给 SQLBrowseConnect：

"HOST=red;UID=Smith;PWD=Sesame"

SQLBrowseConnect 使用此信息通过密码 Sesame 连接到红色服务器，然后在 *OutConnectionString 中返回以下字符串：

"*DATABASE:Database={SalesEmployees,SalesGoals,SalesOrders}"

应用程序将此字符串传递给其 GetUserInput 例程，该例程生成一个对话框，要求用户选择数据库。用户选择 empdata，应用程序使用此字符串调用 SQLBrowseConnect 最后一次：

"DATABASE=SalesOrders"

这是驱动程序连接到数据源所需的最后一部分信息;SQLBrowseConnect 返回SQL_SUCCESS，*OutConnectionString 包含已完成的连接字符串：

// SQLBrowseConnect_Function.cpp  
// compile with: odbc32.lib  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
#define BRWS_LEN 100  
SQLHENV henv;  
SQLHDBC hdbc;  
SQLHSTMT hstmt;  
SQLRETURN retcode;  
SQLCHAR szConnStrIn[BRWS_LEN], szConnStrOut[BRWS_LEN];  
SQLSMALLINT cbConnStrOut;  
  
void GetUserInput(SQLCHAR * szConnStrOut, SQLCHAR * szConnStrIn) {}  
  
int main() {  
   // Allocate the environment handle.  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);        
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
      // Set the version environment attribute.  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
         // Allocate the connection handle.  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            // Call SQLBrowseConnect until it returns a value other than SQL_NEED_DATA   
            // (pass data source name the first time).  If SQL_NEED_DATA is returned, call GetUserInput   
            // (not shown) to build a dialog from the values in szConnStrOut.  The user-supplied values   
            // are returned in szConnStrIn, which is passed in the next call to SQLBrowseConnect.  
  
            strcpy_s((char*)szConnStrIn, _countof(szConnStrIn), "DSN=Sales");  
            do {  
               retcode = SQLBrowseConnect(hdbc, szConnStrIn, SQL_NTS,  
                  szConnStrOut, BRWS_LEN, &cbConnStrOut);  
               if (retcode == SQL_NEED_DATA)  
                  GetUserInput(szConnStrOut, szConnStrIn);  
            } while (retcode == SQL_NEED_DATA);  
  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){  
  
               // Allocate the statement handle.  
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)  
                  // Process data after successful connection  
                  SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
               SQLDisconnect(hdbc);  
            }  
         }  
         SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
      }  
   }  
   SQLFreeHandle(SQL_HANDLE_ENV, henv);  
}

有关以下内容的信息	请参阅
分配连接句柄	SQLAllocHandle 函数
连接到数据源	SQLConnect 函数
断开与数据源的连接	SQLDisconnect 函数
使用连接字符串或对话框连接到数据源	SQLDriverConnect 函数
返回驱动程序说明和属性	SQLDrivers 函数
释放连接句柄	SQLFreeHandle 函数

另请参阅

ODBC API 参考
 ODBC 头文件

通过

SQLBrowseConnect 函数

语法

参数

返回

诊断

InConnectionString 参数

OutConnectionString 参数

使用 SQLBrowseConnect

代码示例

另请参阅

反馈

其他资源

通过

SQLBrowseConnect 函数

语法

参数

返回

诊断

InConnectionString 参数

OutConnectionString 参数

使用 SQLBrowseConnect

代码示例

相关函数

另请参阅

反馈

其他资源