一致性
推出版本：ODBC 3.0 标准合规：ISO 92
总结
SQLGetConnectAttr 返回当前连接属性的设置。
注释
关于当 ODBC 3*.x* 应用程序与 ODBC 2*.x* 驱动协作时，驱动程序管理器将该函数映射到什么，请参见“应用 向后兼容性映射替换函数”。
Syntax
SQLRETURN SQLGetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Arguments
ConnectionHandle
[输入] 连接句柄。
属性
[输入]属性要检索。
ValuePtr
[输出]指向内存的指针，用于返回由 属性指定的属性当前值。 对于整数类型属性，有些驱动程序可能只写入缓冲区的低32位或16位，而不更改高阶位。 因此，应用程序应使用SQLULEN缓冲区，并在调用该函数前将该值初始化为0。
如果 ValuePtr 是 NULL，StringLengthPtr 仍然会返回 ValuePtr 指向的缓冲区中可返回的总字节数（不含字符数据的空终止字符）。
BufferLength
[输入]如果 Attribute 是 ODBC 定义的属性，ValuePtr 指向字符串或二进制缓冲区，则此参数应为 *ValuePtr 的长度。 如果 Attribute 是 ODBC 定义的属性，* ValuePtr 是整数，则忽略 BufferLength 。 如果 *ValuePtr 中的值是 Unicode 字符串（调用 SQLGetConnectAttrW 时）， BufferLength 参数必须是偶数。
如果 属性 是驱动程序定义的属性，应用程序通过设置 BufferLength 参数向驱动程序管理器指示该属性的性质。 缓冲长度 可以有以下数值：
如果 *ValuePtr 是指向字符串的指针， BufferLength 是字符串的长度。
如果 *ValuePtr 是指向二进制缓冲区的指针，应用程序将 SQL_LEN_BINARY_ATTR（长度）宏的结果置入 BufferLength。 这会使 缓冲长度为负值。
如果 *ValuePtr 指向非字符字符串或二进制字符串的值， BufferLength 应具有 SQL_IS_POINTER。
如果 *ValuePtr 包含固定长度的数据类型，则缓冲 长度 可以是SQL_IS_INTEGER或SQL_IS_UINTEGER，视情况而定。
StringLengthPtr
[输出]指向缓冲区的指针，用于返回*ValuePtr中可返回的总字节数（不含空终止字符）。 如果属性值是一个字符字符串，且可返回的字节数大于 BufferLength 减去空终止字符长度，则 *ValuePtr 中的数据会被截断为缓冲 长度 减去空终止字符长度，并被驱动程序终止为空。
Returns
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR或SQL_INVALID_HANDLE。
诊断
当 SQLGetConnectAttr 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用 SQLGetDiagRec 的 HandleType（SQL_HANDLE_DBC）和 Handle（ConnectionHandle）来从诊断数据结构中获得关联的 SQLSTATE 值。 下表列出了 SQLGetConnectAttr 通常返回的SQLSTATE值，并在此函数的上下文中解释了每个值;“（DM）” 符号位于驱动程序管理器返回的 SQLSTATE 描述之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| 01004 | 字符串数据，右截断 | *ValuePtr 中返回的数据被截断为 BufferLength 减去一个空终止字符的长度。 未截断字符串值的长度返回为 *StringLengthPtr。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| 08003 | 连接未打开 | （DM） 指定了一个需要开放连接的 属性 值。 |
| 08S01 | 通信链接失败 | 驱动程序与驱动程序连接到的数据源之间的通信链接在函数完成处理之前失败。 |
| HY000 | 常规错误 | 发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 诊断数据结构中通过参数 MessageText 返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY010 | 函数序列错误 | （DM） SQLBrowseConnect 被调用以获取 ConnectionHandle 并返回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 | 无效属性/选项标识符 | 参数属性指定的 值在驱动程序 支持的ODBC版本中不适用。 |
| HY114 | 驱动程序不支持连接级异步函数执行 | （DM） 一个应用程序尝试用SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE启用不支持异步连接操作的驱动程序的异步函数执行。 |
| HY117 | 连接因未知事务状态而挂起。 仅允许断开连接和只读函数。 | （DM） 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYC00 | 未实现可选功能 | 参数属性指定的 值是驱动 支持但驱动不支持的 ODBC 版本的有效 ODBC 连接属性。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr 设置，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驱动程序不支持此函数 | （DM） 与 ConnectionHandle 对应的驱动程序不支持该函数。 |
Comments
有关连接属性的一般信息，请参见 连接属性。
有关可设置属性列表，请参见 SQLSetConnectAttr。 注意，如果 Attribute 指定返回字符串的属性， ValuePtr 必须是该字符串缓冲区的指针。 返回字符串的最大长度，包括空终止字符，将是 BufferLength 字节。
根据属性的不同，应用程序无需在调用 SQLGetConnectAttr 前建立连接。 然而，如果调用 SQLGetConnectAttr 且指定的属性没有默认值，且之前未被 SQLSetConnectAttr 设置， SQLGetConnectAttr 会返回SQL_NO_DATA。
如果 属性SQL_ATTR_ TRACE 或 SQL_ATTR_ TRACEFILE，ConnectionHandle 不必有效，且 SQLGetConnectAttr 不会返回 ConnectionHandle 无效的 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 函数 |