SQLSetConnectAttr －设置与连接相关的选项

用途

规范：

DB2 CLI

ODBC 1.0

ISO CLI

SQLSetConnectAttr() 设置与连接相关的选项。

语法

SQLRETURN   SQLSetConnectAttr   (SQLHDBC        ConnectionHandle,   
                              SQLINTEGER        Attribute,
                              SQLPOINTER        ValuePtr,
                              SQLINTEGER        StringLength);

函数自变量

表 80. SQLSetConnectAttr 自变量

数据类型	自变量	使用	描述
SQLHDBC	`ConnectionHandle`	输入	连接句柄。
SQLINTEGER	`Attribute`	输入	要设置的选项。
SQLPOINTER	`ValuePtr`	输入	如果 `Attribute` 是一个 ODBC 定义的属性，且 `ValuePtr` 指向字符串或二进制缓冲区，则此自变量应是 `ValuePtr` 的长度。如果 `Attribute` 是一个 ODBC 定义的属性，且 ValuePtr 是整数，则忽略 `StringLength`。如果 `Attribute` 是一个 DB2 CLI 属性，则应用程序通过设置 `StringLength` 自变量来指示该属性的性质。`StringLength` 可以具有下列值：如果 `ValuePtr` 是指向字符串的指针，则 `StringLength` 是字符串或 SQL_NTS 的长度。如果 `ValuePtr` 是指向二进制缓冲区的指针，则应用程序将 SQL_LEN_BINARY_ATTR(length) 宏的结果放在 `StringLength` 中。这将在 `StringLength` 中放置一个负数值。如果 `ValuePtr` 是指向除字符串或二进制字符串外的值的指针，则 `StringLength` 的值应为 SQL_IS_POINTER。如果 `ValuePtr` 包含定长值，则 `StringLength` 是 SQL_IS_INTEGER 或 SQL_IS_UINTEGER（在适当的时候）。
SQLINTEGER	`StringLength`	输入	如果 `ValuePtr` 指向字符串或二进制缓冲区，则此自变量应是 `ValuePtr` 的长度。如果 `ValuePtr` 是一个指针，但并非指向字符串或二进制缓冲区，则 `StringLength` 的值应当是 SQL_IS_POINTER。如果 `ValuePtr` 不是指针，则 `StringLength` 的值应当是 SQL_IS_NOT_POINTER。

用法

连接的连接属性会一直有效，直到它们被对 SQLSetConnectAttr() 的另一调用更改，或是通过调用 SQLDisconnect() 断开了该连接。

SQLSetConnectAttr() 接受两种不同格式的属性信息：以 null 结束的字符串或 32 位整数值。每一种的格式都在该属性的描述中有记载。SQLSetConnectAttr() 的 ValuePtr 自变量所指向的字符串的长度为 StringLength。

连接属性

当前定义的属性显示如下。

SQL_ATTR_AUTOCOMMIT (DB2 CLI/ODBC)

一个 32 位整数值，它指定方式类型。支持的值是：

SQL_AUTOCOMMIT_ON = 自动提交每个语句。这是缺省值。
在自动落实方式下，一个语句所执行的所有更新在该语句执行完成后都自动具有持久状态。自动落实方式是缺省行为。在缺省情况下，未启用事务支持，而且，并不保证语句级别基数。例如，下列 UPDATE 语句可能会在处理期间失败且可能只更新行的子集：
```
UPDATE T SET A = A + 1
```
更新／删除／插入操作失败有多种原因。例如，在更新期间可能违反了检查约束。因此，可以正确更新表的一部分，而表的其余部分不能更新，并且不能回滚所作的更改。
SQL_AUTOCOMMIT_OFF = 应用程序必须手工显式落实或回滚事务。落实或回滚事务是通过调用 SQLEndTran() 来完成的。有关使用 SQLEndTran() 的更多信息，请参阅SQLEndTran －请求 COMMIT 或 ROLLBACK。
在手工落实方式下，事务是在第一次访问数据库时通过使用 SQLPrepare() 和 SQLExecDirect() 隐式启动的，在此情况下，即使调用失败，事务也已经开始了。当您使用 SQLEndTran() 来对事务进行 ROLLBACK 或 COMMIT 操作时，事务就结束了。
在手工落实方式下，事务可发出所有 SQL 语句，包括 DDL 和 DML（例如，CREATE TABLE 或 UPDATE 语句）。

SQL_ATTR_CONNECTION_DEAD (DB2 CLI/ODBC)

READ ONLY 32 位整数值，用来指示连接是否仍然是活动的。DB2 CLI 将返回下列其中一个值：

SQL_CD_FALSE －连接仍然是活动的。
SQL_CD_TRUE －连接已死。

SQL_ATTR_LOGIN_TIMEOUT (DB2 CLI/ODBC)

一个 32 位整数值，对应于在将控制返回给应用程序之前等待登录请求完成的秒数。

SQL_ATTR_FILENAME_FORMAT (DB2 Everyplace)

一个 32 位整数指定 DB2e 数据库引擎是以长格式还是以 8.3 格式创建文件名。当调用 SQLSetConnectAttr 时，仅当连接的路径中没有目录文件，才允许应用程序更改文件名格式。如果由于预先存在的目录文件而拒绝更改文件名格式，将返回具有 SQLState HY000 的 SQL_ERROR。例如，如果应用程序连接至已存在 DB2 Everyplace 目录文件的路径，任何更改文件格式的尝试都将失败。如果应用程序连接至不存在 DB2 Everyplace 目录文件的路径且在试图在第一个 CREATE TABLE 语句之后更改文件名格式，SQLSetConnectAttr 也将返回 SQL_ERROR。这是因为在首个 CREATE TABLE 语句期间会创建目录文件，在创建目录文件之后不允许更改文件名格式。缺省文件名格式取决于平台。SQL_FILENAME_FORMAT_LONG 当前是受支持的所有平台的缺省值。

属性值：

 SQL_FILENAME_FORMAT_LONG － 将以长文件名格式创建文件。

 SQL_FILENAME_FORMAT_83 － 将以 8.3 文件名格式创建文件。

返回码

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

诊断

表 81. SQLSetConnectAttr SQLSTATE

SQLSTATE	描述	解释
HY000	一般错误。	不能更改文件名格式。
HY001	内存分配失败。	DB2 CLI 无法分配支持函数的执行或完成所需的内存。
HY014	不再有句柄。	因为内部资源问题，DB2 CLI 无法分配句柄。
HY090	字符串或缓冲区长度无效。	其中一个名称长度自变量的值小于 0，但不等于 SQL_NTS。

限制

一个事务中可以更新的表的数目是有限的。DB2 Everyplace 允许事务中最多有 256 个打开文件（假定操作系统也允许这么多的打开文件）。这通常意味着可更新大约 100 个表。表的数目取决于索引使用情况以及语句句柄数。活动语句句柄越多，可以潜在地更新的表越少。即使在一个事务中多次访问和／或更新某个表，对这个表也只计一次。
对 DB2 Everyplace 添加了事务，以允许在许多个表中一致地更新和插入若干个相关记录。在应用程序落实事务之后，便将更改写至数据表。
如果应用程序过早终止，而没有落实当前事务，则会自动回滚该事务内的更新。
在 SQLEndTran 返回之后，落实或回滚事务。
当应用程序连接至（在活动事务期间）过早终止的数据库时，会对事务进行恢复。数据库使用下列逻辑恢复事务：
- 如果事务未完成，则不更新数据库。
- 如果事务完成，则会使用来自该事务的信息更新数据库。
- 如果恢复被中断，则在下一次连接时执行适当的操作。

相关参考

SQLSetConnectAttr － 设置与连接相关的选项

SQLSetConnectAttr －设置与连接相关的选项