SQLSetEnvAttr 函数

  • 项目

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

摘要
SQLSetEnvAttr 设置控制环境的各个方面的属性。

语法

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

自变量

EnvironmentHandle
[输入]环境句柄。

Attribute
[输入]要设置的属性，在“注释”中列出。

ValuePtr
[输入]指向要与 Attribute 关联的值的指针。 根据 Attribute 的值， ValuePtr 将是一个 32 位整数值或指向以 null 结尾的字符串。

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

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

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。

诊断

当 SQLSetEnvAttr 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值，该 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_ENV 和 Handle of EnvironmentHandle。 下表列出了通常由 SQLSetEnvAttr 返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。 如果驱动程序不支持环境属性，则只能在连接期间返回错误。

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

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

(DM) 已SQL_ATTR_OUTPUT_NTS Attribute 参数，并且SQL_FALSE ValuePtr 。

注释

仅当未在环境中分配任何连接句柄时，应用程序才能调用 SQLSetEnvAttr 。 应用程序为环境成功设置的所有环境属性将一直保留，直到在环境中调用 SQLFreeHandle 。 可以在 ODBC 3.x 中同时分配多个环境句柄。

通过 ValuePtr 设置的信息格式取决于指定的 属性。 SQLSetEnvAttr 将接受以下两种格式之一的属性信息：以 null 结尾的字符串或 32 位整数值。 属性的说明中会记录每个格式。

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

无法通过调用 SQLSetEnvAttr 来设置连接属性。 尝试执行此操作将返回 SQLSTATE HY092 (无效的属性/选项标识符) 。

Attribute 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 时的环境句柄设置为 null，这使得SQL_ATTR_CONNECTION_POOLING进程级属性。 启用连接池后，应用程序通过调用 SQLAllocHandle 分配隐式共享环境，并将 InputHandle 参数设置为 SQL_HANDLE_ENV。

启用连接池并为应用程序选择共享环境后，无法为该环境重置SQL_ATTR_CONNECTION_POOLING，因为在设置此属性时，使用空环境句柄调用 SQLSetEnvAttr 。 如果在共享环境中启用了连接池时设置了此属性，则属性仅影响随后分配的共享环境。

还可以在环境中启用连接池。 请注意以下有关环境连接池的事项：

- 在 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.xSQLSTATE 代码。
- 调用 SQLTables 中的 CatalogName 参数接受搜索模式。
- 驱动程序管理器支持 C 数据类型扩展性。 有关 C 数据类型扩展性的详细信息，请参阅 ODBC 中的 C 数据类型。

有关详细信息，请参阅 ODBC 3.8 中的新增功能。

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

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

SQL_OV_ODBC2 = 驱动程序管理器和驱动程序显示以下 ODBC 2.x 行为。 这对于使用 ODBC 3.x 驱动程序的 ODBC 2.x 应用程序特别有用。

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

应用程序必须在调用具有 SQLHENV 参数的任何函数之前设置此环境属性，否则调用将返回 SQLSTATE HY010 (函数序列错误) 。 对于这些环境标志是否存在其他行为，这是特定于驱动程序的。

- 有关详细信息，请参阅 声明应用程序的 ODBC 版本 和 行为更改。
SQL_ATTR_OUTPUT_NTS (ODBC 3.0) 一个 32 位整数，确定驱动程序如何返回字符串数据。 如果SQL_TRUE，驱动程序将返回以 null 结尾的字符串数据。 如果SQL_FALSE，驱动程序不会返回以 null 结尾的字符串数据。

此属性默认为 SQL_TRUE。 调用 SQLSetEnvAttr 将其设置为 SQL_TRUE 将返回SQL_SUCCESS。 调用 SQLSetEnvAttr 将其设置为 SQL_FALSE 将返回SQL_ERROR，SQLSTATE HYC00 () 未实现的可选功能。
有关以下方面的信息 请参阅
分配句柄 SQLAllocHandle 函数
返回环境属性的设置 SQLGetEnvAttr 函数

另请参阅

ODBC API 参考
ODBC 头文件
ODBC 3.8 中的新增功能