SQLDataSources 函数

项目
05/23/2023

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

摘要
SQLDataSources 返回有关数据源的信息。此函数仅由驱动程序管理器实现。

语法

  
SQLRETURN SQLDataSources(  
     SQLHENV          EnvironmentHandle,  
     SQLUSMALLINT     Direction,  
     SQLCHAR *        ServerName,  
     SQLSMALLINT      BufferLength1,  
     SQLSMALLINT *    NameLength1Ptr,  
     SQLCHAR *        Description,  
     SQLSMALLINT      BufferLength2,  
     SQLSMALLINT *    NameLength2Ptr);

参数

EnvironmentHandle
[输入]环境句柄。

方向
[输入]确定驱动程序管理器返回有关哪个数据源的信息。可以是：

SQL_FETCH_NEXT (提取列表中) 的下一个数据源名称，SQL_FETCH_FIRST (从列表) 的开头提取，SQL_FETCH_FIRST_USER (提取第一个用户 DSN) ，或SQL_FETCH_FIRST_SYSTEM (提取第一个系统 DSN) 。

当 Direction 设置为 SQL_FETCH_FIRST 时，对 SQLDataSources 的 后续调用（ 将 Direction 设置为 SQL_FETCH_NEXT返回用户和系统 DSN。当 Direction 设置为 SQL_FETCH_FIRST_USER 时，对 SqlDataSources 的所有后续调用（ 将 Direction 设置为 SQL_FETCH_NEXT仅返回用户 DSN）。当 Direction 设置为 SQL_FETCH_FIRST_SYSTEM 时，对 Direction 设置为 SQLDataSources 的所有后续调用SQL_FETCH_NEXT仅返回系统 DSN。

ServerName
[输出]指向要在其中返回数据源名称的缓冲区的指针。

如果 ServerName 为 NULL， 则 NameLength1Ptr 仍将返回总字符数， (不包括可在 ServerName 指向的缓冲区中返回的字符数据的 null 终止字符) 。

BufferLength1
[输入]*ServerName 缓冲区的长度（以字符为单位）;这不需要超过 SQL_MAX_DSN_LENGTH 加上 null 终止字符。

NameLength1Ptr
[输出]指向缓冲区的指针，该缓冲区将返回总字符数， (不包括可在 *ServerName 中返回的 null 终止字符) 。如果可返回的字符数大于或等于 BufferLength1，则 *ServerName 中的数据源名称将被截断为 BufferLength1 减去 null 终止字符的长度。

说明
[输出]指向缓冲区的指针，该缓冲区将返回与数据源关联的驱动程序的说明。例如，dBASE 或 SQL Server。

如果 Description 为 NULL，NameLength2Ptr 仍将返回字符总数 (不包括字符数据的 null 终止字符数，) 说明指向的缓冲区中返回。

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

NameLength2Ptr
[输出]指向缓冲区的指针，该缓冲区要返回总字符数， (不包括可在 *Description 中返回的 null 终止字符) 。如果可返回的字符数大于或等于 BufferLength2，则*Description 中的驱动程序说明将截断为 BufferLength2 减去 null 终止字符的长度。

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR或SQL_INVALID_HANDLE。

诊断

当 SQLDataSources 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过使用 handleType 为 SQL_HANDLE_ENV 和 Handle ofEnvironmentHandle 调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。下表列出了 SQLDataSources 通常返回的 SQLSTATE 值，并对此函数上下文中的每个值进行了说明：表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATE 说明之前。与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。

SQLSTATE	错误	说明
01000	常规警告	(DM) 特定于驱动程序管理器的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.)
01004	字符串数据，右截断	(DM) 缓冲区 *ServerName 不够大，无法返回完整的数据源名称。因此，名称被截断。整个数据源名称的长度在 *NameLength1Ptr 中返回。 (函数返回 SQL_SUCCESS_WITH_INFO.) (DM) 缓冲区说明不够大，无法返回完整的驱动程序说明。因此，说明被截断。非结构化数据源说明的长度在 NameLength2Ptr 中返回。 (函数返回 SQL_SUCCESS_WITH_INFO.)
HY000	常规错误	(DM) 发生错误，其中没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec 在 *MessageText 缓冲区中返回的错误消息描述了错误及其原因。
HY001	内存分配错误	(DM) 驱动程序管理器无法分配支持执行或完成函数所需的内存。
HY010	函数序列错误	(DM) SQLExecute、 SQLExecDirect 或 SQLMoreResults 已为 StatementHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。此函数是在检索所有流参数的数据之前调用的。
HY013	内存管理错误	无法处理函数调用，因为无法访问基础内存对象，可能是由于内存不足。
HY090	无效的字符串或缓冲区长度	(DM) 为参数 BufferLength1 指定的值小于 0。 (DM) 为参数 BufferLength2 指定的值小于 0。
HY103	检索代码无效	(DM) 为参数 Direction 指定的值不等于 SQL_FETCH_FIRST、SQL_FETCH_FIRST_USER、SQL_FETCH_FIRST_SYSTEM 或 SQL_FETCH_NEXT。
HY117	由于事务状态未知，连接已暂停。仅允许断开连接和只读函数。	(DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。

注释

由于 SQLDataSources 是在驱动程序管理器中实现的，因此所有驱动程序都支持 SQLDataSources，而不考虑特定驱动程序的标准符合性。

应用程序可以多次调用 SQLDataSources 来检索所有数据源名称。驱动程序管理器从系统信息中检索此信息。如果没有其他数据源名称，驱动程序管理器将返回SQL_NO_DATA。如果 SQLDataSources 在返回SQL_NO_DATA后立即使用 SQL_FETCH_NEXT调用，它将返回第一个数据源名称。有关应用程序如何使用 SQLDataSources 返回的信息的信息，请参阅选择数据源或驱动程序。

如果在首次调用 SQLDataSources 时将SQL_FETCH_NEXT传递给 SQLDataSources ，它将返回第一个数据源名称。

驱动程序确定如何将数据源名称映射到实际数据源。

有关以下方面的信息	请参阅
发现并列出连接到数据源所需的值	SQLBrowseConnect 函数
连接到数据源	SQLConnect 函数
使用连接字符串或对话框连接到数据源	SQLDriverConnect 函数
返回驱动程序说明和属性	SQLDrivers 函数

另请参阅

ODBC API 参考
 ODBC 头文件

SQLDataSources 函数

语法

参数

返回

诊断

注释

另请参阅

反馈

反馈

其他资源

SQLDataSources 函数

语法

参数

返回

诊断

注释

相关函数

另请参阅

反馈

反馈

其他资源