SQLGetConnectAttr 函数
一致性
引入的版本：ODBC 3.0 标准符合性：ISO 92
摘要
SQLGetConnectAttr 返回连接属性的当前设置。
注意
有关当 ODBC 3*.x* 应用程序使用 ODBC 2*.x* 驱动程序时驱动程序管理器将此函数映射到的内容的详细信息，请参阅 映射替换函数以实现应用程序的后向兼容性。
语法
SQLRETURN SQLGetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
参数
ConnectionHandle
[输入] 连接句柄。
Attribute
[输入]要检索的属性。
ValuePtr
[输出]指向内存的指针，在该内存中返回 由 Attribute 指定的特性的当前值。 对于整数类型属性，某些驱动程序可能只写入缓冲区的较低 32 位或 16 位，并保留高阶位不变。 因此，应用程序应使用 SQLULEN 缓冲区，并在调用此函数之前将值初始化为 0。
如果 ValuePtr 为 NULL， 则 StringLengthPtr 仍将返回总字节数 (不包括 valuePtr 指向的缓冲区中可返回的字符数据的 null 终止字符) 。
BufferLength
[输入]如果 Attribute 是 ODBC 定义的属性，并且 ValuePtr 指向字符串或二进制缓冲区，则此参数应为 *ValuePtr 的长度。 如果 Attribute 是 ODBC 定义的属性， 并且 *ValuePtr 是整数，则忽略 BufferLength 。 如果 *ValuePtr 中的值是调用 SQLGetConnectAttrW) 时 (Unicode 字符串， 则 BufferLength 参数必须是偶数。
如果 Attribute 是驱动程序定义的属性，则应用程序通过设置 BufferLength 参数向驱动程序管理器指示属性的性质。 BufferLength 可以具有以下值：
如果 *ValuePtr 是指向字符串的指针， 则 BufferLength 是字符串的长度。
如果 *ValuePtr 是指向二进制缓冲区的指针，则应用程序会将SQL_LEN_BINARY_ATTR (长度 的结果) 宏置于 BufferLength 中。 这会在 BufferLength 中放置一个负值。
如果 *ValuePtr 是指向字符串或二进制字符串以外的值的指针， 则 BufferLength 的值应SQL_IS_POINTER。
如果 *ValuePtr 包含固定长度的数据类型， 则 BufferLength 是SQL_IS_INTEGER或SQL_IS_UINTEGER（视情况而定）。
StringLengthPtr
[输出]指向缓冲区的指针，在该缓冲区中返回的总字节数 (不包括可在 *ValuePtr 中返回的 null 终止字符) 。 如果属性值是字符串，并且可返回的字节数大于 BufferLength 减去 null 终止字符的长度，则 *ValuePtr 中的数据将被截断为 BufferLength 减去 null 终止字符的长度，并由驱动程序以 null 结尾。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR或SQL_INVALID_HANDLE。
诊断
当 SQLGetConnectAttr 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过调用 SQLGetDiagRec 和 Handle SQL_HANDLE_DBC ofConnectionHandle，从诊断数据结构中获取关联的 SQLSTATE 值。 下表列出了通常由 SQLGetConnectAttr 返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 01004 | 字符串数据，右截断 | *ValuePtr 中返回的数据被截断为 BufferLength 减去 null 终止字符的长度。 未截断的字符串值的长度在 *StringLengthPtr 中返回。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 08003 | 连接未打开 | (DM) 指定了需要打开连接的 属性值 。 |
| 08S01 | 通信链接失败 | 在函数完成处理之前，驱动程序与驱动程序连接到的数据源之间的通信链接失败。 |
| HY000 | 常规错误 | 发生错误，其中没有特定的 SQLSTATE，并且没有定义特定于实现的 SQLSTATE。 SQLGetDiagField 中的参数 MessageText 从诊断数据结构返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY010 | 函数序列错误 | 为 ConnectionHandle 调用了 (DM) SQLBrowseConnect 并返回SQL_NEED_DATA。 此函数是在 SQLBrowseConnect 返回SQL_SUCCESS_WITH_INFO或SQL_SUCCESS之前调用的。 (DM) SQLExecute、 SQLExecDirect 或 SQLMoreResults 已为 ConnectionHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。 此函数是在检索所有流式处理参数的数据之前调用的。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为无法访问基础内存对象，可能是因为内存不足。 |
| HY090 | 无效的字符串或缓冲区长度 | (DM) *ValuePtr 是一个字符串，BufferLength 小于零但不等于SQL_NTS。 |
| HY092 | 无效的属性/选项标识符 | 为参数 Attribute 指定的值对驱动程序支持的 ODBC 版本无效。 |
| HY114 | 驱动程序不支持连接级异步函数执行 | (DM) 应用程序尝试为不支持异步连接操作的驱动程序启用SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE异步函数执行。 |
| HY117 | 由于未知的事务状态，连接已挂起。 仅允许断开连接和只读函数。 | (DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYC00 | 未实现可选功能 | 为参数 Attribute 指定的值是驱动程序支持的 ODBC 版本的有效 ODBC 连接属性，但驱动程序不支持。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限是通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置的。 |
| IM001 | 驱动程序不支持此函数 | (DM) 对应于 ConnectionHandle 的 驱动程序不支持 函数。 |
注释
有关连接属性的一般信息，请参阅 连接属性。
有关可设置的属性列表，请参阅 SQLSetConnectAttr。 请注意，如果 Attribute 指定返回字符串的属性， 则 ValuePtr 必须是指向字符串缓冲区的指针。 返回的字符串（包括 null 终止字符）的最大长度为 BufferLength 字节。
根据 属性，应用程序无需在调用 SQLGetConnectAttr 之前建立连接。 但是，如果调用 了 SQLGetConnectAttr ，并且指定的属性没有默认值，并且之前调用 SQLSetConnectAttr 尚未设置， 则 SQLGetConnectAttr 将返回SQL_NO_DATA。
如果 Attribute SQL_ATTR_ TRACE 或 SQL_ATTR_ TRACEFILE，则 ConnectionHandle 不必有效，并且如果 ConnectionHandle 无效，SQLGetConnectAttr 不会返回SQL_ERROR或SQL_INVALID_HANDLE。 这些属性适用于所有连接。 如果另一个参数无效，SQLGetConnectAttr 将返回SQL_ERROR或SQL_INVALID_HANDLE。
尽管应用程序可以使用 SQLSetConnectAttr 设置语句属性，但应用程序不能使用 SQLGetConnectAttr 检索语句属性值;它必须调用 SQLGetStmtAttr 来检索语句属性的设置。
SQL_ATTR_AUTO_IPD和SQL_ATTR_CONNECTION_DEAD连接属性都可以通过调用 SQLGetConnectAttr 返回，但不能通过调用 SQLSetConnectAttr 来设置。
注意
SQLGetConnectAttr 没有异步支持。 实现 SQLGetConnectAttr 时，驱动程序可以通过最大程度地减少从服务器发送或请求信息的次数来提高性能。
相关函数
| 有关以下方面的信息 | 请参阅 |
|---|---|
| 返回语句属性的设置 | SQLGetStmtAttr 函数 |
| 设置连接属性 | SQLSetConnectAttr 函数 |
| 设置环境属性 | SQLSetEnvAttr 函数 |
| 设置语句属性 | SQLSetStmtAttr 函数 |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈