SQLBrowseConnect 函数
一致性
引入的版本：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
[输出]指向要在其中返回浏览结果连接字符串的字符缓冲区的指针 (在“Comments”) 中看到“OutConnectionString 参数”。
如果 OutConnectionString 为 NULL， 则 StringLength2Ptr 仍将返回字符总数， (不包括字符数据的 null 终止字符，) OutConnectionString 指向的缓冲区中返回。
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时，可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值， 其 HandleType 为 SQL_HANDLE_STMT 和 ConnectionHandle 的 Handle。 下表列出了 SQLBrowseConnect 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 01004 | 字符串数据，右截断 | 缓冲区 *OutConnectionString 不够大，无法返回整个浏览结果连接字符串，因此字符串被截断。 缓冲区 *StringLength2Ptr 包含未构造的浏览结果连接字符串的长度。 (函数返回 SQL_NEED_DATA.) |
| 01S00 | 连接字符串属性无效 | 在 InConnectionString) 的浏览请求连接字符串 (指定了无效的 attribute 关键字。 (函数返回 SQL_NEED_DATA.) 在浏览请求连接字符串 (InConnectionString) 中指定了不适用于当前连接级别的 attribute 关键字。 (函数返回 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 期间，驱动程序管理器调用了驱动程序的 SQLAllocHandle 函数， HandleType 为 SQL_HANDLE_ENV，驱动程序返回了错误。 |
| IM005 | SQL_HANDLE_DBC 上的驱动程序的 SQLAllocHandle 失败 | (DM) SQLBrowseConnect 期间，驱动程序管理器调用了驱动程序的 SQLAllocHandle 函数， HandleType 为 SQL_HANDLE_DBC，驱动程序返回了错误。 |
| 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[;] | 属性;connection-string;
attribute ：：= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]
attribute-keyword ：：= DSNPWDUID | | | driver-defined-attribute-keyword
attribute-value ：：= character-string
driver-defined-attribute-keyword ：：= identifier
其中 ，字符串 包含零个或多个字符; 标识符 包含一个或多个字符; attribute-keyword 不区分大小写; attribute-value 可能区分大小写;和 DSN 关键字的值不只包含空白。 由于连接字符串和初始化文件语法、关键字和属性值包含字符 []{} () ，;？应避免 *=！@ 。 由于系统信息中的语法，关键字和数据源名称不能包含反斜杠 (\) 字符。 对于 ODBC 2。x driver，DRIVER 关键字的属性值周围需要大括号。
如果在浏览请求连接字符串中重复任何关键字，驱动程序将使用与关键字的第一个匹配项关联的值。 如果 DSN 和 DRIVER 关键字包含在相同的浏览请求连接字符串中，驱动程序管理器和驱动程序将使用最先显示的关键字。
有关应用程序如何选择数据源或驱动程序的信息，请参阅 选择数据源或驱动程序。
OutConnectionString 参数
浏览结果连接字符串是连接属性的列表。 连接属性由 attribute 关键字和相应的属性值组成。 浏览结果连接字符串具有以下语法：
connection-string ：：= attribute[;] | 属性;connection-string
attribute ：：= [*]attribute-keyword=attribute-value
attribute-keyword ：：= ODBC-attribute-keyword | driver-defined-attribute-keyword
ODBC-attribute-keyword = {UID | PWD}[:localized-identifier] driver-defined-attribute-keyword ：：= identifier[:localized-identifier] attribute-value ：：= {attribute-value-list} | ? (大括号是文本;它们由 driver.)
attribute-value-list ：：= character-string [:localized-character string] | character-string [:localized-character string] ,attribute-value-list
其中 字符字符串 和 本地化字符串 具有零个或多个字符; identifier 和 localized-identifier 有一个或多个字符; 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=芝麻。
每次调用 SQLBrowseConnect 仅返回满足下一级连接过程所需的信息。 驱动程序将状态信息与连接句柄相关联，以便始终可以在每次调用时确定上下文。
使用 SQLBrowseConnect
SQLBrowseConnect 需要分配的连接。 驱动程序管理器加载在 或 中指定的驱动程序，该驱动程序对应于初始浏览请求连接字符串中指定的数据源名称;有关何时发生此情况的信息，请参阅 SQLConnect 函数中的“注释”部分。 驱动程序可能会在浏览过程中与数据源建立连接。 如果 SQLBrowseConnect 返回SQL_ERROR，则未完成的连接将终止，连接将返回到未连接状态。
注意
SQLBrowseConnect 不支持连接池。 如果在启用连接池时调用 SQLBrowseConnect ，将返回 SQLSTATE HY000 (常规错误) 。
首次在连接上调用 SQLBrowseConnect 时，浏览请求连接字符串必须包含 DSN 关键字或 DRIVER 关键字。 如果浏览请求连接字符串包含 DSN 关键字，驱动程序管理器在系统信息中找到相应的数据源规范：
如果驱动程序管理器找到相应的数据源规范，它将加载关联的驱动程序 DLL;驱动程序可以从系统信息中检索有关数据源的信息。
如果驱动程序管理器找不到相应的数据源规范，它会查找默认数据源规范并加载关联的驱动程序 DLL;驱动程序可以从系统信息中检索有关默认数据源的信息。 “DEFAULT”传递给 DSN 的驱动程序。
如果驱动程序管理器找不到相应的数据源规范，并且没有默认数据源规范，则返回SQL_ERROR SQLSTATE IM002 (找不到数据源，并且未) 指定默认驱动程序。
如果浏览请求连接字符串包含 DRIVER 关键字，驱动程序管理器将加载指定的驱动程序;它不会尝试在系统信息中查找数据源。 由于 DRIVER 关键字不使用系统信息中的信息，因此驱动程序必须定义足够的关键字，以便驱动程序能够仅使用浏览请求连接字符串中的信息连接到数据源。
每次调用 SQLBrowseConnect 时，应用程序都会在浏览请求连接字符串中指定连接属性值。 驱动程序在浏览结果连接字符串中返回属性和属性值的连续级别;只要浏览请求连接字符串中尚未枚举的连接属性，它就返回SQL_NEED_DATA。 应用程序使用浏览结果连接字符串的内容为下一次调用 SQLBrowseConnect 生成浏览请求连接字符串。 所有必需属性 (OutConnectionString 参数) 前面没有星号的属性都必须包含在对 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 取消正在进行的操作。 在函数返回后调用 SQLCancelHandle SQL_NEED_DATA不起作用。
有关详细信息，请参阅 使用 SQLBrowseConnect 进行连接。
如果驱动程序支持 SQLBrowseConnect，则驱动程序的系统信息中的驱动程序关键字部分必须包含 ConnectFunctions 关键字，并将第三个字符设置为“Y”。
代码示例
注意
如果要连接到支持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 使用此信息以 Smith 的身份使用密码 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 函数 |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈