符合性
版本引入了: ODBC 3.0 标准符合性: ISO 92
摘要
SQLSetEnvAttr设置控制的环境方面的属性。
语法
SQLRETURN SQLSetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
参数
EnvironmentHandle
[输入]环境句柄。
Attribute
[输入]要设置,属性列在"注释"。
ValuePtr
[输入]指向要与之关联的值属性。 具体取决于值特性, 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,关联的 SQLSTATE 值可以通过调用来获取SQLGetDiagRec与HandleType的 SQL_HANDLE_ENV 和一个处理的EnvironmentHandle。 下表列出了通常由返回的 SQLSTATE 值SQLSetEnvAttr ,并解释了此函数; 每个上下文中的表示法"(数据挖掘)"之前 SQLSTATEs 返回由驱动程序管理器的说明。 与每个 SQLSTATE 值关联的返回代码是 SQL_ERROR,除非另有说明。 如果驱动程序不支持的环境属性,则可以仅在连接时返回的错误。
| SQLSTATE | 错误 | Description |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO。) |
| 01S02 | 选项值已更改 | 该驱动程序不支持在指定的值ValuePtr和替换一个相近的值。 (函数返回 SQL_SUCCESS_WITH_INFO。) |
| HY000 | 常规错误 | 有关其中没有任何特定的 SQLSTATE 和为其定义任何特定于实现的 SQLSTATE 出错。 返回的错误消息SQLGetDiagRec中 *MessageText缓冲区描述错误以及其原因。 |
| HY001 | 内存分配错误 | 该驱动程序无法分配支持执行或完成该函数所需的内存。 |
| HY009 | 使用空指针无效 | 特性参数标识所需的字符串值,一个环境属性和ValuePtr参数是空指针。 |
| HY010 | 函数序列错误 | (DM) 上分配了连接句柄EnvironmentHandle。 (数据挖掘) SQL_ATTR_ODBC_VERSION尚未设置与SQLSetEnvAttr并特性是否不等于SQL_ATTR_ODBC_VERSION。 不需要设置SQL_ATTR_ODBC_VERSION显式如果使用的SQLAllocHandleStd。 |
| HY013 | 内存管理错误 | 无法处理函数调用,因为基础内存对象无法访问,可能是由于内存不足的情况。 |
| HY024 | 属性值无效 | 给出指定特性值,在指定了无效的值ValuePtr。 |
| HY090 | 字符串或缓冲区长度无效 | StringLength参数为小于 0,但不是 sql_nts;。 |
| HY092 | 属性/选项标识符无效 | (DM) 的参数指定的值特性对 ODBC 驱动程序支持的版本无效。 |
| HY117 | 由于未知的事务状态而挂起连接。 仅断开连接,并允许使用只读的函数。 | (DM) 有关挂起状态的详细信息,请参阅SQLEndTran 函数。 |
| HYC00 | 未实现的可选功能 | 为参数指定的值特性是有效的 ODBC 环境属性的 ODBC 版本支持的驱动程序,但不是受驱动程序。 (数据挖掘)特性参数为 SQL_ATTR_OUTPUT_NTS,并ValuePtr已 SQL_FALSE。 |
注释
应用程序可以调用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日期、 时间和时间戳的代码。-驱动程序将返回 ODBC 3。x SQLSTATE 代码何时SQLError, SQLGetDiagField,或者SQLGetDiagRec调用。- CatalogName调用中的参数SQLTables接受搜索模式。-驱动程序管理器支持 C 数据类型可扩展性。 有关 C 数据类型可扩展性的详细信息,请参阅ODBC 中的 C 数据类型。 有关详细信息,请参阅What's New in ODBC 3.8。 SQL_OV_ODBC3 = 驱动程序管理器和驱动程序附录以下 ODBC 3 .x行为: -驱动程序返回,并需要使用 ODBC 3 个 .x日期、 时间和时间戳的代码。-驱动程序将返回 ODBC 3 .x SQLSTATE 代码何时SQLError, SQLGetDiagField,或者SQLGetDiagRec调用。- CatalogName调用中的参数SQLTables接受搜索模式。-驱动程序管理器不支持 C 数据类型扩展能力。 SQL_OV_ODBC2 = 驱动程序管理器和驱动程序附录以下 ODBC 2 .x行为。 此方法特别有用的 ODBC 2 .x应用程序使用 ODBC 3 .x驱动程序。 -驱动程序返回,并期望 ODBC 2 .x日期、 时间和时间戳的代码。-驱动程序将返回 ODBC 2 .x SQLSTATE 代码何时SQLError, SQLGetDiagField,或者SQLGetDiagRec调用。- CatalogName调用中的参数SQLTables不接受的搜索模式。-驱动程序管理器不支持 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 中的新增功能
历史资料。此文对应 2018-11-30 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 MightyPen)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
