SQLSetStmtAttr － 设置与语句相关的选项

用途

SQLSetStmtAttr() 设置与语句相关的选项。

语法

SQLRETURN   SQLSetStmtAttr   (SQLHSTMT          StatementHandle,   
                              SQLINTEGER        Attribute,
                              SQLPOINTER        ValuePtr,
                              SQLINTEGER        StringLength);

函数自变量

表 82. SQLSetStmtAttr 自变量

用法

语句的语句属性在被另一 SQLSetStmtAttr() 调用更改之前，或通过调用 SQLFreeHandle() 删除该语句之前，语句属性保持有效。调用 SQLFreeStmt() 时，如果指定了 SQL_CLOSE、SQL_UNBIND 或 SQL_RESET_PARAMS 选项，则不会将语句属性复位。

如果数据源不支持 ValuePtr 中指定的值，则某些语句属性支持类似值的替换。在这样的情况下，DB2 CLI 返回 SQL_SUCCESS_WITH_INFO 和 SQLSTATE 01S02（选项值已更改）。例如，如果 Attribute 是 SQL_ATTR_CONCURRENCY，ValuePtr 是 SQL_CONCUR_ROWVER，而数据源不支持这一点，则 DB2 CLI 替换 SQL_CONCUR_VALUES 并返回 SQL_SUCCESS_WITH_INFO。要确定替换的值，应用程序调用 SQLGetStmtAttr()。用 ValuePtr 设置的信息格式取决于指定的 Attribute。

SQLSetStmtAttr() 接受两种不同格式之一的属性信息： null 终止的字符串或 32 位整数值。每一种的格式都在该属性的描述中有记载。此格式适用于对 SQLGetStmtAttr() 中每个属性返回的信息。SQLSetStmtAttr() 的 ValuePtr 自变量所指向的字符串的长度为 StringLength。

脏位

DB2 Everyplace 使用脏位跟踪对记录的更改。SQL_ATTR_DELETE_MODE、SQL_ATTR_READ_MODE 和 SQL_ATTR_DIRTYBIT_SET_MODE 语句属性影响脏位的性能。下表显示在记录上执行某些数据库操作后脏位的状态。该表假定 SQL_ATTR_DIRTYBIT_SET_MODE 参数被设置为带有系统维护的脏位的 SQL_DIRTYBIT_SET_BY_SYSTEM。

表 83. DB2 Everyplace 脏位状态

通过查询表的 $dirty 列能够获得脏位的值。例如，以下语句返回脏位和电话簿表的 NAME 列：

SELECT $dirty, NAME from PHONEBOOK

脏位可以有以下值。

表 84. DB2 Everyplace 脏位值

语句属性

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

SQL_ATTR_CURSOR_SCROLLABLE（DB2 CLI）

指定该应用程序需要的支持级别的 32 位整数。 设置此属性会影响对 SQLExecDirect() 和 SQLExecute() 的后续调用。支持的值是：

• SQL_NONSCROLLABLE

  语句句柄上不需要可滚动游标。 如果应用程序在此句柄上调用 SQLFetchScroll()，则 FetchOrientation() 的唯一有效值是 SQL_FETCH_NEXT。 这是缺省值。

• SQL_SCROLLABLE

  该语句句柄上需要可滚动游标。当调用 SQLFetchScroll() 时，应用程序可以指定 FetchOrientation 的任何有效值，以便可以以除顺序方式以外的方式定位游标。

SQL_ATTR_CURSOR_SENSITIVITY（DB2 CLI）

一个 32 位整数值，指定游标是否对另一个游标的写活动敏感。 支持的值是：

• SQL_UNSPECIFIED

  其它游标的写活动对当前游标具有未定义的影响。这是缺省值。

• SQL_INSENSITIVE

  其它游标的写活动对当前游标没有影响。

  注意:

  因为此属性值会影响性能，所以应尽量少使用。

SQL_ATTR_CURSOR_TYPE (DB2 CLI)

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

• SQL_CURSOR_FORWARD_ONLY = 游标只正向滚动。这是缺省值。
• SQL_CURSOR_STATIC = 结果集中的数据是静态的。

不能对打开的游标指定此选项。

SQL_ATTR_ROW_ARRAY_SIZE (DB2 CLI)

一个 32 位整数值，它指定行集中的行数。这是每次调用 SQLFetch() 或 SQLFetchScroll() 时返回的行数。缺省值是 1。如果指定的行集大小超过数据源支持的最大行集大小，则 DB2 CLI 换上该值并返回 SQLSTATE 01S02（选项值已更改）。可对打开的游标指定此选项。

SQL_ATTR_ROW_BIND_TYPE (DB2 CLI)

一个 32 位的整数值，它设置对相关联的语句调用 SQLFetch() 或 SQLFetchScroll() 时要使用的绑定方向。通过在 ValuePtr 中提供已定义的常量 SQL_BIND_BY_COLUMN 选择列智能绑定。ValuePtr 中指定的长度必须包括用于所有绑定列的空间以及任何结构或缓冲区的填充，以确保当绑定列的地址以指定的长度增加时，结果会指向下一行中的同一列的起始位置。当将 sizeof 运算符与 ANSI C 中的结构或连接配合使用时，此行为能得到保证。列智能绑定是 SQLFetchScroll() 的缺省绑定方向。

SQL_ATTR_ROW_NUMBER（DB2 CLI）

一个 32 位整数值，它是整个结果集中当前行的编号。 如果不能确定当前行的编号或没有当前行，则 DB2 CLI 返回 0。 可以通过调用 SQLGetStmtAttr() 检索此属性， 但不能调用 SQLSetStmtAttr() 进行设置。

SQL_ATTR_ROW_STATUS_PTR (DB2 CLI)

一个 16 位无符号整数值，它指向 UWORD 值的一个数组，该数组包含调用 SQLFetch() 或 SQLFetchScroll() 后的行状态值。该数组具有的元素数目与行集中的行数相同。可以将此语句属性设置为空指针，在这种情况下，DB2 CLI 不返回行状态值。此属性可以随时设置，但新值只能在下次调用 SQLFetch() 或 SQLFetchScroll() 之后才可使用。

SQL_ATTR_ROWS_FETCHED_PTR (DB2 CLI)

一个 32 位无符号整数值，它指向一个缓冲区，调用 SQLFetch() 或 SQLFetchScroll() 后取装的行数在该缓冲区中返回。

SQL_ATTR_DELETE_MODE (DB2 Everyplace)

支持的值是：

• SQL_DELETE_MARK_ONLY

  这是系统缺省值。在执行删除 SQL 语句时，记录仅被标记为“删除”。如果设置了 SQL_READ_INCLUDE_MARKED_DELETE，则该记录的内容仍然可读。

• SQL_DELETE_PHYSICAL_REMOVE

  删除 SQL 语句会上物理上除去满足 WHERE 子句条件的记录，而不管其脏位如何。

例如，使用以下语法物理除去某些记录，而忽略其脏位的状态：

SQLSetStmtAttr (stmt, SQL_ATTR_DELETE_MODE, SQL_DELETE_PHYSICAL_REMOVE, 0)
 

然后执行以下 SQL 语句以从表 T 中删除 X 不等于 0 的所有记录：

DELETE T WHERE X<>0

SQL_ATTR_DIRTYBIT_SET_MODE (DB2 Everyplace)

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

• SQL_DIRTYBIT_SET_BY_SYSTEM

  这是系统缺省值。插入、更新或删除的记录的脏位分别设置为 INSERT、UPDATE 或 DELETE。当设置了 SQL_DIRTYBIT_SET_BY_SYSTEM 时，不允许对 $dirty 列执行 UPDATE。

• SQL_DIRTYBIT_SET_BY_APPLICATION

  应用程序负责在插入、更新或删除记录时设置脏位。每个操作的语义如下：

  UPDATE

  系统完全按照应用程序所指定的那样来设置脏位。 例如，如果应用程序执行以下语句，则会将表中的所有记录复位为 0（CLEAN）：

  UPDATE T SET $dirty=0 WHERE $dirty>0
  

  INSERT

  新插入的记录的脏位设置为 CLEAN。

  DELETE

  如果设置了 SQL_DELETE_PHYSICAL_REMOVE，DELETE 在物理上从数据库除去记录。 否则，$dirty 列的值设置为 DELETE 且记录仍保留在数据库中。

例如，要清除记录的脏位，使用以下语句：

SQLSetStmtAttr (stmt, SQL_ATTR_DIRTYBIT_SET_MODE,
SQL_DIRTYBIT_SET_BY_APPLICATION, 0)

然后执行以下 SQL 语句：

UPDATE T SET $DIRTY=0 WHERE $DIRTY>0

一般说来，如果在跟踪最终用户所作的数据库更新时不需要脏位，应用程序可设置 SQL_DIRTYBIT_SET_BY_APPLICATION。

SQL_ATTR_READ_MODE (DB2 Everyplace)

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

• SQL_READ_EXCLUDE_MARKED_DELETE

  这是系统缺省值。其脏位被设置为“删除”的所有记录将不为 SQL 所知。

• SQL_READ_INCLUDE_MARKED_DELETE

  一旦设置了此项， 其脏位被设置为 DELETE 的记录对 SQL SELECT 语句是可视的。应用程序可通过检查记录的脏位来将这些已删除记录与其它记录区别开。

例如，使用以下语句来读取设置了脏位的所有记录，包括那些脏位被标记为 DELETE 的记录：

SQLSetStmtAttr (stmt, SQL_ATTR_READ_MODE, SQL_READ_INCLUDE_MARKED_DELETE, 0)
 

然后执行以下 SQL 语句以检索所有记录：

SELECT * FROM T WHERE $dirty<>0

SQL_ATTR_REORG_MODE（DB2 Everyplace）

一个 32 位的整数值，指定是否对用户创建的表自动执行数据库重组以及是否允许显式的 REORG SQL 语句。支持的值是：

• SQL_REORG_ENABLED － 这是系统缺省值。DB2 Everyplace 可以执行数据库重组，用户也可以使用 REORG SQL 语句以显式方式执行重组。
• SQL_REORG_DISABLED － REORG SQL 语句受到限制，禁止对用户创建的表自动执行数据库重组。

不能对打开的游标指定此选项。

返回码

• SQL_SUCCESS
• SQL_SUCCESS_WITH_INFO
• SQL_ERROR
• SQL_INVALID_HANDLE

诊断

表 85. SQLSetStmtAttr SQLSTATE

限制

无。

相关参考

• DB2 CLI 函数描述的关键
• DB2 CLI 函数摘要