SQLSetEnvAttr 函数

一致性
推出版本：ODBC 3.0 标准合规：ISO 92

总结
SQLSetEnvAttr 设置了管理环境某些方面的属性。

Syntax

  
SQLRETURN SQLSetEnvAttr(  
     SQLHENV      EnvironmentHandle,  
     SQLINTEGER   Attribute,  
     SQLPOINTER   ValuePtr,  
     SQLINTEGER   StringLength);

Arguments

环境控制
[输入]环境控制。

属性
[输入]归属集合，列在“评论”中。

ValuePtr
[输入]指向 要关联属性的值。 根据 属性值， ValuePtr 可能是 32 位整数值，或指向一个空终止字符字符串。

StringLength
[输入]如果 ValuePtr 指向字符字符串或二进制缓冲区，该参数应为 *ValuePtr 的长度。 对于字符字符串数据，该参数应包含字符串中的字节数。

如果 ValuePtr 是整数，则忽略 StringLength 。

Returns

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或SQL_INVALID_HANDLE。

诊断

当 SQLSetEnvAttr 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用 SQLGetDiagRec 获得关联的 SQLSTATE 值， HandleType 为 SQL_HANDLE_ENV，Handle 为 environmentHandle。 下表列出了 SQLSetEnvAttr 通常返回的SQLSTATE值，并在该函数的上下文中解释了每个值;“（DM）” 符号位于驱动程序管理器返回的 SQLSTATE 描述之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。 如果驱动程序不支持环境属性，错误只能在连接时返回。

SQLSTATE Error Description
01000 常规警告 特定于驱动程序的信息性消息。 （函数返回SQL_SUCCESS_WITH_INFO。）
01S02 选项值已更改 驱动程序不支持 ValuePtr 中指定的值，而是用类似的值替换。 （函数返回SQL_SUCCESS_WITH_INFO。）
HY000 常规错误 发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY009 无效使用 null 指针 属性参数用于识别需要字符串值的环境属性，而 ValuePtr 参数则是空指针。
HY010 函数序列错误 （DM） EnvironmentHandle 上已分配连接句柄。

（DM） SQL_ATTR_ODBC_VERSION 未用 SQLSetEnvAttr设置，属性 不等于 SQL_ATTR_ODBC_VERSION。 如果你用的是 SQLAllocHandleStd，就不需要显式设置SQL_ATTR_ODBC_VERSION。
HY013 内存管理错误 无法处理函数调用，因为基础内存对象无法访问，可能是因为内存条件低。
HY024 属性值无效 给定指定的属性值后，ValuePtr 中指定了无效值。
HY090 字符串或缓冲区长度无效 StringLength 参数小于 0，但不SQL_NTS。
HY092 无效属性/选项标识符 （DM） 为参数 特性 指定的值对驱动程序支持的 ODBC 版本无效。
HY117 连接因未知事务状态而挂起。 仅允许断开连接和只读函数。 （DM） 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。
HYC00 未实现可选功能 参数属性指定的 值是驱动 支持的 ODBC 版本的有效 ODBC 环境属性，但驱动不支持。

（DM） 属性 论证SQL_ATTR_OUTPUT_NTS， 价值Ptr SQL_FALSE。

Comments

只有当环境上没有分配连接句柄时，应用程序才能调用 SQLSetEnvAttr 。 应用程序成功为该环境设置的所有环境属性都会持续存在，直到环境调用 SQLFreeHandle 为止。 在 ODBC 3.x 中，可以同时分配多个环境句柄。

通过 ValuePtr 设置的信息格式取决于指定的 属性。 SQLSetEnvAttr 可接受两种不同格式中的属性信息：空终端字符字符串或 32 位整数值。 属性的说明中记录了每个格式。

没有驱动程序特定的环境属性。

连接属性不能通过调用 SQLSetEnvAttr 来设置。 尝试这样做会返回 SQLSTATE HY092（无效属性/选项标识符）。

属性 ValuePtr 内容
SQL_ATTR_CONNECTION_POOLING（ODBC 3.8） 一个32位SQLUINTEGER值，用于在环境层面启用或禁用连接池。 使用了以下值：

SQL_CP_OFF = 连接池已关闭。 这是默认值。

SQL_CP_ONE_PER_DRIVER = 每个驱动支持单一连接池。 池中的每个连接都关联到一个驱动程序。

SQL_CP_ONE_PER_HENV = 每个环境支持单一连接池。 池中的每个连接都关联到一个环境。

SQL_CP_DRIVER_AWARE = 如果有驱动的连接池感知功能，可以使用。 如果驱动程序不支持连接池感知，SQL_CP_DRIVER_AWARE会被忽略，SQL_CP_ONE_PER_HENV被使用。 有关详细信息，请参阅 驱动程序感知型连接池。 在某些驱动支持连接池感知、部分驱动不支持连接池感知的环境中，SQL_CP_DRIVER_AWARE可以在支持驱动的驱动上启用连接池感知功能，但这等同于在不支持连接池感知功能的驱动程序上设置为SQL_CP_ONE_PER_HENV。

连接池通过调用 SQLSetEnvAttr 将 SQL_ATTR_CONNECTION_POOLING 属性设置为 SQL_CP_ONE_PER_DRIVER 或 SQL_CP_ONE_PER_HENV 来实现。 在应用程序分配共享环境以启用连接池之前，必须进行此调用。 调用 SQLSetEnvAttr 的环境句柄设置为空，这使得 SQL_ATTR_CONNECTION_POOLING 成为进程级属性。 在启用连接池后，应用程序通过调用 SQLAllocHandle 并将 InputHandle 参数设置为 SQL_HANDLE_ENV，从而分配一个隐式共享环境。

在启用连接池并为某个应用选择共享环境后，SQL_ATTR_CONNECTION_POOLING无法为该环境重置 ，因为在 设置该属性时调用了空环境句柄。 如果该属性在共享环境中已启用连接池时设置，则该属性只影响后续分配的共享环境。

也可以在环境中启用连接池。 请注意以下关于环境连接池的说明：

- 在 NULL 句柄上启用连接池是进程级属性。 随后分配的环境将成为共享环境，并继承进程级连接池设置。
- 环境分配后，应用程序仍可更改连接池设置。
- 如果启用了环境连接池，且连接驱动使用驱动程序池，则环境池优先。

SQL_ATTR_CONNECTION_POOLING在驱动程序管理器中实现。 驱动程序无需实现SQL_ATTR_CONNECTION_POOLING。 ODBC 2.0 和 3.0 应用程序可以设置该环境属性。

有关详细信息，请参阅 ODBC 连接池。
SQL_ATTR_CP_MATCH（ODBC 3.0） 一个32位SQLUINTEGER值，用于决定连接如何从连接池中选择连接。 当调用 SQLConnect 或 SQLDriverConnect 时，驱动程序管理器会确定从池中重用哪条连接。 驱动程序管理器会尝试将调用中的连接选项和应用程序设置的连接属性与池中连接的关键词和连接属性匹配。 该属性的值决定了匹配标准的精度水平。

以下数值用于设置该属性的值：

SQL_CP_STRICT_MATCH = 仅重复使用与调用中连接选项和应用程序设置的连接属性完全匹配的连接。 这是默认值。

SQL_CP_RELAXED_MATCH = 可使用与连接字符串关键词匹配的连接。 关键词必须匹配，但并非所有连接属性都必须匹配。

关于驱动管理器如何在连接池连接时执行匹配的更多信息，请参见 SQLConnect。 有关连接池的详细信息，请参阅 ODBC 连接池。
SQL_ATTR_ODBC_VERSION（ODBC 3.0） 一个32位整数，用于确定某些功能表现出ODBC 2.x 行为还是ODBC 3.x 行为。 以下数值用于设置该属性的值：

SQL_OV_ODBC3_80 = 驱动程序管理器和驱动程序表现出以下ODBC 3.8行为：

- 驱动程序返回，期望收到ODBC 3.x 的日期、时间和时间戳代码。
- 当调用SQLError、SQLGetDiagField或SQLGetDiagRec时，驱动程序返回ODBC 3.x SQLSTATE代码。
- 调用 SQLTables 时的 CatalogName 参数接受搜索模式。
- 驱动程序管理器支持C语言数据类型扩展性。 有关 C 语言数据类型可扩展性的更多信息，请参见 ODBC 中的 C 语言数据类型。

更多信息请参见 ODBC 3.8的新动态。

SQL_OV_ODBC3 = 驱动程序管理器和驱动程序表现出以下ODBC 3.x 行为：

- 驱动程序返回，期望收到ODBC 3.x 的日期、时间和时间戳代码。
- 当调用SQLError、SQLGetDiagField或SQLGetDiagRec时，驱动程序返回ODBC 3.x SQLSTATE代码。
- 调用 SQLTables 时的 CatalogName 参数接受搜索模式。
- 驱动程序管理器不支持C语言数据类型的可扩展性。

SQL_OV_ODBC2 = 驱动管理器和驱动程序表现出以下 ODBC 2.x 行为。 这对于使用 ODBC 3.x 驱动的 ODBC 2.x 应用程序尤其有用。

- 驱动程序返回，期望收到日期、时间和时间戳的ODBC 2.x 代码。
- 当调用 SQLError、SQLGetDiagField 或 SQLGetDiagRec 时，驱动程序返回 ODBC 2.x 的 SQLSTATE 代码。
- 调用SQLTables时的CatalogName参数不接受搜索模式。
- 驱动程序管理器不支持C语言数据类型的可扩展性。

应用程序必须在调用包含 SQLHENV 参数的任何函数之前设置该环境属性，否则调用将返回 SQLSTATE HY010（函数序列错误）。 这些环境标志是否存在额外的行为取决于具体驾驶员。

- 更多信息请参见 “宣告应用程序的ODBC版本 及 行为变更”。
SQL_ATTR_OUTPUT_NTS（ODBC 3.0） 一个32位整数，决定驱动程序返回字符串数据的方式。 如果SQL_TRUE，驱动程序返回的字符串数据是空终止的。 如果SQL_FALSE，驱动程序不会返回空终止的字符串数据。

该属性默认为SQL_TRUE。 调用 SQLSetEnvAttr 将其设置为 SQL_TRUE 返回SQL_SUCCESS。 调用 SQLSetEnvAttr 将其设置为 SQL_FALSE 返回 SQL_ERROR 和 SQLSTATE HYC00（未实现可选功能）。
有关以下内容的信息 请参阅
分配手柄 SQLAllocHandle 函数
返回环境属性的设置 SQLGetEnvAttr 函数

相关内容

  • Last updated on