SQLDrivers 函数
一致性
引入的版本：ODBC 2.0 标准合规性：ODBC
摘要
SQLDrivers 列出了驱动程序说明和驱动程序属性关键字。 此函数仅由驱动程序管理器实现。
语法
SQLRETURN SQLDrivers(
SQLHENV EnvironmentHandle,
SQLUSMALLINT Direction,
SQLCHAR * DriverDescription,
SQLSMALLINT BufferLength1,
SQLSMALLINT * DescriptionLengthPtr,
SQLCHAR * DriverAttributes,
SQLSMALLINT BufferLength2,
SQLSMALLINT * AttributesLengthPtr);
参数
EnvironmentHandle
[输入]环境句柄。
方向
[输入]确定驱动程序管理器是否提取列表中 (SQL_FETCH_NEXT) 的下一个驱动程序说明，或者搜索是否从列表的开头开始 (SQL_FETCH_FIRST) 。
DriverDescription
[输出]指向要在其中返回驱动程序说明的缓冲区的指针。
如果 DriverDescription 为 NULL， DescriptionLengthPtr 仍将返回字符总数， (不包括在 DriverDescription 指向的缓冲区中返回的字符数据的 null 终止字符) 。
BufferLength1
[输入]*DriverDescription 缓冲区的长度（以字符为单位）。
DescriptionLengthPtr
[输出]指向缓冲区的指针，该缓冲区将返回总字符数 (不包括可在 *DriverDescription 中返回的 null 终止字符) 。 如果可返回的字符数大于或等于 BufferLength1，则*DriverDescription 中的驱动程序说明将截断为 BufferLength1 减去 null 终止字符的长度。
DriverAttributes
[输出]指向要在其中返回驱动程序属性值对列表的缓冲区的指针， (请参阅“注释”) 。
如果 DriverAttributes 为 NULL， 则 AttributesLengthPtr 仍将返回字节总数， (不包括可在 DriverAttributes 指向的缓冲区中返回的字符数据的 null 终止字符) 。
BufferLength2
[输入]*DriverAttributes 缓冲区的长度（以字符为单位）。 如果 *DriverDescription 值是调用 SQLDriversW) 时 (的 Unicode 字符串， 则 BufferLength 参数必须是偶数。
AttributesLengthPtr
[输出]指向缓冲区的指针，该缓冲区将返回总字节数 (不包括可在 *DriverAttributes 中返回的 null-end 字节) 。 如果可返回的字节数大于或等于 BufferLength2，则 *DriverAttributes 中的属性值对列表将被截断为 BufferLength2 减去 null 终止字符的长度。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR或SQL_INVALID_HANDLE。
诊断
当 SQLDrivers 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过使用 handleType 为 SQL_HANDLE_ENV 和 Handle of EnvironmentHandle 调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLDrivers 通常返回的 SQLSTATE 值，并对此函数上下文中的每个值进行了说明：表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATE 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | (DM) 特定于驱动程序管理器的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 01004 | 字符串数据，右截断 | (DM) 缓冲区 *DriverDescription 不够大，无法返回完整的驱动程序说明。 因此，说明被截断。 完整驱动程序说明的长度在 *DescriptionLengthPtr 中返回。 (函数返回 SQL_SUCCESS_WITH_INFO.) (DM) 缓冲区 *DriverAttributes 不够大，无法返回属性值对的完整列表。 因此，列表已被截断。 属性值对的未构造列表的长度在 *AttributesLengthPtr 中返回。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| HY000 | 常规错误 | 发生错误，其中没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec 在 *MessageText 缓冲区中返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配错误 | (DM) 驱动程序管理器无法分配支持执行或完成函数所需的内存。 |
| HY010 | 函数序列错误 | (DM) SQLExecute、 SQLExecDirect 或 SQLMoreResults 已为 StatementHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。 此函数是在检索所有流参数的数据之前调用的。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为无法访问基础内存对象，可能是由于内存不足。 |
| HY090 | 无效的字符串或缓冲区长度 | (DM) 为参数 BufferLength1 指定的值小于 0。 (DM) 为参数 BufferLength2 指定的值小于 0 或等于 1。 |
| HY103 | 检索代码无效 | (DM) 为参数 Direction 指定的值不等于 SQL_FETCH_FIRST 或 SQL_FETCH_NEXT。 |
| HY117 | 由于事务状态未知，连接已暂停。 仅允许断开连接和只读函数。 | (DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
注释
SQLDrivers 返回 *DriverDescription 缓冲区中的驱动程序说明。 它以关键字值对列表的形式返回有关 *DriverAttributes 缓冲区中的驱动程序的其他信息。 将为除 CreateDSN 之外的所有驱动程序返回驱动程序的系统信息中列出的所有关键字， CreateDSN 用于提示创建数据源，因此是可选的。 每个对都以 null 字节终止，完整列表以 null 字节 (即，两个 null 字节将列表的末尾标记为) 。 例如，使用 C 语法的基于文件的驱动程序可能会返回以下属性列表， (“\0”表示空字符) ：
FileUsage=1\0FileExtns=*.dbf\0\0
如果 *DriverAttributes 的大小不足以容纳整个列表，则列表将被截断， SQLDrivers 返回 SQLSTATE 01004 (数据截断) ，列表的长度 (不包括最终的 null 终止字节) 在 *AttributesLengthPtr 中返回。
安装驱动程序时，将从系统信息中添加驱动程序属性关键字。 有关详细信息，请参阅 安装 ODBC 组件。
应用程序可以多次调用 SQLDrivers 来检索所有驱动程序说明。 驱动程序管理器从系统信息中检索此信息。 如果没有其他驱动程序说明， SQLDrivers 将返回SQL_NO_DATA。 如果 SQLDrivers 在返回SQL_NO_DATA后立即使用 SQL_FETCH_NEXT 调用，则会返回第一个驱动程序说明。 有关应用程序如何使用 SQLDrivers 返回的信息的信息，请参阅 选择数据源或驱动程序。
如果SQL_FETCH_NEXT在首次调用 SQLDrivers 时传递给 SQLDrivers，SQLDrivers 将返回第一个数据源名称。
由于 SQLDrivers 是在驱动程序管理器中实现的，因此所有驱动程序都支持 SQLDrivers，而不考虑特定驱动程序的标准符合性。
相关函数
| 有关以下方面的信息 | 请参阅 |
|---|---|
| 发现并列出连接到数据源所需的值 | SQLBrowseConnect 函数 |
| 连接到数据源 | SQLConnect 函数 |
| 返回数据源名称 | SQLDataSources 函数 |
| 使用连接字符串或对话框连接到数据源 | SQLDriverConnect 函数 |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈