SQLSetStmtAttr - 设置语句属性

在线编辑

SQLSetStmtAttr() 设置特定语句句柄的属性。 要为与连接句柄关联的所有语句句柄设置选项，应用程序可以调用 SQLSetConnectOption()。

Unicode (UTF-16) 等效: 此函数还可以与 Unicode (UTF-16) 字符集配合使用。 对应的 Unicode 函数为 SQLSetStmtAttrW()。 请参阅 Db2 for i CLI 中的 Unicode ，以获取有关 DB2® CLI 的 Unicode 支持的更多信息。

语法

SQLRETURN SQLSetStmtAttr  (SQLHSTMT       hstmt,
                           SQLINTEGER     fAttr,
                           SQLPOINTER     vParam,
                           SQLINTEGER     sLen);

函数自变量

表 1. SQLSetStmtAttr参数
数据类型 自变量 使用 描述
SQLHSTMT hstmt 输入 语句句柄。
SQLINTEGER fAttr 输入 要设置的属性。 请参阅 表 2 以获取可设置语句属性的列表。
SQLPOINTER vParam 输入 与 fAttr关联的值。 vParam 可以是 32 位整数值或字符串。
SQLINTEGER sLen 输入 数据长度 (如果数据是字符串); 否则，未使用。

用法

hstmt 的语句选项保持有效，直到它们被另一个对 SQLSetStmtAttr() 的调用更改，或者通过使用 SQL_DROP 选项调用 SQLFreeStmt() 来删除 hstmt 。 使用 SQL_CLOSE ， SQL_UNBIND 或 SQL_RESET_PARAMS 选项调用 SQLFreeStmt() 不会重置语句选项。

通过 vParam 设置的信息的格式取决于指定的 fOption。 表 2中记录了每个表的格式。

表 2。 语句属性
fAttr 内容
SQL_ATTR_APP_PARAM_DESC VParam 必须是描述符句柄。 指定的描述符充当稍后在语句句柄上调用 SQLExecute() 和 SQLExecDirect() 的应用程序参数描述符。
SQL_ATTR_APP_ROW_DESC VParam 必须是描述符句柄。 指定的描述符充当稍后在语句句柄上调用 SQLFetch() 的应用程序行描述符。
SQL_ATTR_BIND_TYPE 这指定是使用逐行绑定还是逐列绑定。
  • SQL_BIND_BY_ROW-绑定是逐行绑定。 这是缺省情况。

    对多行访存使用逐行绑定时，将在连续存储器中返回一行的所有数据，后跟下一行的数据，依此类推。

  • SQL_BIND_BY_COLUMN-按列进行绑定。

    对多行访存使用按列绑定时，将在连续存储器中返回每个列的所有数据。 每行的存储器不必是连续的。 用户为结果集中的每个列提供不同的地址，用户负责确保每个地址都有空间用于检索所有数据。
SQL_ATTR_CURSOR_HOLD 32 位整数值，用于指定是否应该保留为此语句句柄打开的游标。
  • SQL_FALSE-此语句句柄的打开游标在落实或回滚操作时关闭。 这是缺省情况。
  • SQL_TRUE-未在落实或回滚操作时关闭此语句句柄的打开游标。
SQL_ATTR_CURSOR_SCROLLABLE 32 位整数值，用于指定为此语句句柄打开的游标是否应该可滚动。
  • SQL_FALSE-游标不可滚动，不能对其使用 SQLFetchScroll() 。 这是缺省情况。
  • SQL_TRUE-可滚动游标。 SQLFetchScroll() 可用于从这些游标检索数据。
SQL_ATTR_CURSOR_灵敏度 32 位整数值，用于指定为此语句句柄打开的游标是否使另一个游标对结果集所作的更改可视。 请参阅 DECLARE CURSOR 以获取以下选项的更精确定义:
  • SQL_UNSPECIFIED-根据游标类型，语句句柄上的游标可能会使任何，某些或所有此类更改都不可视。 这是缺省情况。
  • SQL_INSENSITIVE-语句句柄上的所有有效游标显示结果集而不反映任何其他游标对其进行的任何更改。
  • SQL_SENSITIVE-语句句柄上的所有有效游标使另一个游标对结果所作的所有更改可视。
SQL_ATTR_CURSOR_TYPE 32 位整数值，用于指定为此语句句柄打开的游标的行为。
  • SQL_CURSOR_FORWARD_ONLY-游标不可滚动，并且不能对其使用 SQLFetchScroll() 函数。 这是缺省情况。
  • SQL_CURSOR_DYNAMIC-除不敏感的游标敏感度外，游标可滚动。 SQLFetchScroll() 函数可用于从这些游标检索数据。
  • SQL_CURSOR_STATIC-除敏感游标灵敏度外，游标可滚动。 SQLFetchScroll() 函数可用于从这些游标检索数据。
SQL_ATTR_EXTENDED_COL_INFO 32 位整数值，用于指定为此语句句柄打开的游标是否应提供扩展列信息。
  • SQL_FALSE-无法在 SQLColAttribute() 函数上使用此语句句柄来检索扩展列信息。 这是缺省情况。 在语句级别设置此属性将覆盖此属性的连接级别设置。
  • SQL_TRUE-可以在 SQLColAttribute() 函数上使用此语句句柄来检索扩展列信息，例如基本表，基本模式，基本列和标签。
SQL_ATTR_FOR_FETCH_ONLY 32 位整数值，用于指定是否应该只读为此语句句柄打开的游标:
  • SQL_TRUE-游标是只读的，不能用于定位更新或删除操作。 这是缺省值，除非 SQL_ATTR_FOR_FETCH_ONLY 环境已设置为 SQL_FALSE。
  • SQL_FALSE-游标可用于定位更新或删除操作。
SQL_ATTR_FULL_OPEN 32 位整数值，用于指定为此语句句柄打开的游标是否应该是完全打开操作。
  • SQL_FALSE-打开此语句句柄的游标可能会由于性能原因而使用高速缓存的游标。 这是缺省情况。
  • SQL_TRUE-打开此语句句柄的游标始终强制对新游标执行完全打开操作。
SQL_ATTR_NUMBER_RESULTSET_ROWS_PTR 32 位整数 * 值指向一个缓冲区，该缓冲区包含结果集中可用的总行数。 仅当游标灵敏度不敏感且游标类型为静态时，此属性才会返回有效结果。 如果没有这些设置，返回的结果将为零。 该值在成功调用 SQLExecute() 或 SQLExecDirect() 后设置。
SQL_ATTR_PARAM_BIND_TYPE 32 位整数值:
  • SQL_BIND_BY_ROW-绑定是逐行绑定。 这是缺省情况。 对多行语句使用逐行绑定时，每行的所有数据都必须是连续存储器，后跟下一行的数据，依此类推。
  • SQL_BIND_BY_COLUMN-按列进行绑定。 对多行语句使用列式绑定时，每个列的所有数据都位于连续存储器中。 用户为语句中的每个列提供不同的地址，用户负责确保每个地址都有空间用于要传递到数据库的所有参数数据。
SQL_ATTR_PARAM_STATUS_PTR 32 位整数 * 值，指向包含每行参数值的状态信息的值数组。 状态值是在调用 SQLExecDirect() 或 SQLExecute()之后设置的。 仅当 SQL_ATTR_PARAMSET_SIZE 大于 1 时，才使用此字段。 可以返回以下状态值。
  • SQL_PARAM_SUCCESS: 已成功针对这组参数执行 SQL 语句。
  • SQL_PARAM_SUCCESS_WITH_INFO: 已成功对此参数集执行 SQL 语句; 但是，返回了警告信息。
  • SQL_PARAM_ERROR: 处理此参数集时发生错误。
  • SQL_PARAM_未用: 设置的参数未使用。 如果先前设置的参数导致异常中止进一步处理的错误，那么会发生此情况。
  • SQL_PARAM_DIAG_UNAVAILABLE: DB2 CLI 当前未设置此值。
此语句属性可以设置为空指针，在这种情况下， DB2 CLI 不会返回参数状态值。
SQL_ATTR_PARAMS_PROCESSED_PTR 指向当前行号的 32 位整数 * 值。 在处理每行参数时，会将其设置为该行的编号。 如果调用 SQLExecDirect() 或 SQLExecute() 填入此属性指向的 SQLINTEGER 缓冲区时没有返回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO，则缓冲区的内容未定义。

此语句属性可以设置为空指针，在这种情况下， DB2 CLI 不会返回行号。
SQL_ATTR_PARAMSET_SIZE 32 位整数值，用于指定要与每个参数标记关联的值的数目。 如果这大于 1 ，那么 SQLBindParameter() 中的 rgbValue 自变量将指向参数值数组，而 pcbValue 将指向长度数组。 这是通过 SQLParamOptions() API 设置值大小的替代方法。
SQL_ATTR_ROW_BIND_TYPE 32 位整数值:
  • SQL_BIND_BY_ROW-绑定是逐行绑定。 这是缺省情况。 对多行访存使用逐行绑定时，将在连续存储器中返回一行的所有数据，后跟下一行的数据，依此类推。
  • SQL_BIND_BY_COLUMN-按列进行绑定。 对多行访存使用按列绑定时，将在连续存储器中返回每个列的所有数据。 每个列的存储不必是连续的。 用户为结果集中的每个列提供不同的地址，用户负责确保每个地址都有空间用于检索所有数据。
SQL_ATTR_ROW_STATUS_PTR 16 位 SMALLINT * 值，指向 SQLFetchScroll()处的状态值数组。 元素数必须等于行集中的行数 (由 SQL_ROWSET_SIZE 属性定义)。 将返回每个访存的行的状态值 SQL_ROW_SUCCESS。

如果访存的行数小于状态数组中的元素数 (即，小于行集大小) ，那么剩余的状态元素将设置为 SQL_ROW_NOROW。 在输出指针中返回访存的行数。 可通过 SQLSetStmtAttr 属性 SQL_ATTR_ROWS_FETCHED_PTR 设置。

Db2 for i CLI 无法检测自访存启动以来是否已更新或删除行。 因此，不会报告以下 ODBC 定义的状态值:

  • SQL_ROW_DELETED。
  • SQL_ROW_UPDATED。
SQL_ATTR_ROWS_FETCHED_PTR 32 位整数 * 值，指向包含 SQLFetchScroll()实际访存的行数的缓冲区。 如果在处理期间发生错误，那么指针指向发生错误的行 (在行集中) 之前的行的有序位置。 如果检索第一行时发生错误，那么指针指向值 0。
SQL_ATTR_ROWSET_SIZE 32 位整数值，用于指定行集中的行数。 这是每次调用 SQLExtendedFetch()时返回的行数。 最大值为 32767。 缺省值是1。

返回码

  • SQL_SUCCESS
  • SQL_ERROR
  • SQL_INVALID_HANDLE

诊断

表 3. SQLStmtAttr SQLSTATEs
SQLSTATE 描述 说明
40003 * 语句完成未知 在该功能完成处理之前， CLI 与数据源之间的通信链路发生故障。
HY000 一般错误 发生了错误，没有为其定义特定 SQLSTATE ，也没有为其定义实现 SQLSTATE。 SQLError 在参数 szErrorMsg 中返回的错误信息描述了错误及其原因。
HY001 内存分配失败 驱动程序无法分配支持功能处理或完成所需的内存。
HY009 参数值无效 给定指定的 fAttr 值，将为自变量 vParam指定无效的值。

指定了无效的 fAttr 值。

自变量 vParam 是空指针。
HY010 函数顺序错误 调用此函数的顺序不正确。
HYC00 驱动程序不支持 驱动程序或数据源不支持指定的选项。

引用