SQLDataSources 函数
一致性
引入的版本：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 函数 |