Share via

SQLGetEnvAttr 函数

  • 项目

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

摘要
SQLGetEnvAttr 返回环境属性的当前设置。

语法

  
SQLRETURN SQLGetEnvAttr(  
     SQLHENV        EnvironmentHandle,  
     SQLINTEGER     Attribute,  
     SQLPOINTER     ValuePtr,  
     SQLINTEGER     BufferLength,  
     SQLINTEGER *   StringLengthPtr);

参数

EnvironmentHandle
[输入]环境句柄。

Attribute
[输入]要检索的属性。

ValuePtr
[输出]指向缓冲区的指针，在该缓冲区中返回由 Attribute 指定的特性的当前值。

如果 ValuePtr 为 NULL， StringLengthPtr 仍将返回总字节数 (不包括字符数据的 null 终止字符数，) ValuePtr 指向的缓冲区中可以返回。

BufferLength
[输入]如果 ValuePtr 指向字符串，则此参数应为 *ValuePtr 的长度。 如果 *ValuePtr 是整数，则忽略 BufferLength 。 如果 *ValuePtr 是调用 SQLGetEnvAttrW) 时 (Unicode 字符串， 则 BufferLength 参数必须是偶数。 如果属性值不是字符串， 则未使用 BufferLength 。

StringLengthPtr
[输出]指向缓冲区的指针，该缓冲区返回的总字节数 (不包括 null 终止字符) 可在 *ValuePtr 中返回。 如果属性值是字符串，并且可返回的字节数大于或等于 BufferLength，则 *ValuePtr 中的数据将被截断为 BufferLength 减去 null 终止字符的长度，并由驱动程序以 null 结尾。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR或SQL_INVALID_HANDLE。

诊断

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

SQLSTATE 错误 说明
01000 常规警告 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.)
01004 字符串数据，右截断 *ValuePtr 中返回的数据被截断为 BufferLength 减去 null 终止字符。 非结构化字符串值的长度在 *StringLengthPtr 中返回。 (函数返回 SQL_SUCCESS_WITH_INFO.)
HY000 常规错误 发生错误，其中没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec 在 *MessageText 缓冲区中返回的错误消息描述了错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY010 函数序列错误 (DM) SQL_ATTR_ODBC_VERSION 尚未通过 SQLSetEnvAttr 设置。 如果使用 SQLAllocHandleStd，则无需显式设置SQL_ATTR_ODBC_VERSION。
HY013 内存管理错误 无法处理函数调用，因为无法访问基础内存对象，可能是由于内存不足。
HY092 无效的属性/选项标识符 为参数 Attribute 指定的值对驱动程序支持的 ODBC 版本无效。
HY117 由于事务状态未知，连接已暂停。 仅允许断开连接和只读函数。 (DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。
HYC00 未实现可选功能 为参数 Attribute 指定的值是驱动程序支持的 ODBC 版本的有效 ODBC 环境属性，但驱动程序不支持。
IM001 驱动程序不支持此函数 (DM) 对应于 EnvironmentHandle 的 驱动程序不支持 函数。

注释

有关属性的列表，请参阅 SQLSetEnvAttr。 没有特定于驱动程序的环境属性。 如果 Attribute 指定返回字符串的属性， 则 ValuePtr 必须是指向要返回字符串的缓冲区的指针。 字符串的最大长度（包括 null 终止字节）将为 BufferLength 字节。

可以在分配和释放环境句柄之间随时调用 SQLGetEnvAttr。 应用程序为环境成功设置的所有环境属性一直持续到在 HandleType 为 SQL_HANDLE_ENV 的 EnvironmentHandle 上调用 SQLFreeHandle 为止。 可以在 ODBC 3*.x* 中同时分配多个环境句柄。 分配了另一个环境时，一个环境中的环境属性不会受到影响。

注意

符合标准的应用程序支持SQL_ATTR_OUTPUT_NTS环境属性。 调用 SQLGetEnvAttr 时，ODBC 3*.x* 驱动程序管理器始终返回此属性SQL_TRUE。 只能通过调用 SQLSetEnvAttr 将SQL_ATTR_OUTPUT_NTS设置为SQL_TRUE。

有关以下方面的信息 请参阅
返回连接属性的设置 SQLGetConnectAttr 函数
返回语句属性的设置 SQLGetStmtAttr 函数
设置连接属性 SQLSetConnectAttr 函数
设置环境属性 SQLSetEnvAttr 函数
设置语句属性 SQLSetStmtAttr 函数

另请参阅

ODBC API 参考
ODBC 头文件