通过

SQLSetStmtAttr 函数

  • 项目

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

总结
SQLSetStmtAttr 设置与语句相关的属性。

注意

有关 Driver Manager 将此函数映射到 ODBC 3.x 应用程序使用 ODBC 2.x 驱动程序时的功能的详细信息，请参阅 映射替换函数以实现应用程序的向后兼容性。

语法

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

参数

StatementHandle
[输入]语句句柄。

属性
[输入]要设置的选项，在“批注”中列出。

ValuePtr
[输入]要与 Attribute 关联的值。 根据属性值，ValuePtr 将是下列值之一：

  • ODBC 描述符句柄。

  • SQLUINTEGER 值。

  • SQLULEN 值。

  • 指向以下项之一的指针：

    • 以 null 结尾的字符串。

    • 二进制缓冲区。

    • SQLLEN、SQLULEN 或 SQLUSMALLINT 类型的值或数组。

    • 驱动程序定义的值。

如果 Attribute 参数是特定于驱动程序的值，ValuePtr 可能是带符号整数。

StringLength
[输入]如果 Attribute 是 ODBC 定义的属性，ValuePtr 指向字符串或二进制缓冲区，则此参数应为 *ValuePtr 的长度。 如果 Attribute 是 ODBC 定义的属性，并且 ValuePtr 是整数， 则忽略 StringLength 。

如果 Attribute 是驱动程序定义的属性，则应用程序通过设置 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。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或SQL_INVALID_HANDLE。

诊断

当 SQLSetStmtAttr 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过使用 handleType of SQL_HANDLE_STMT 和 StatementHandle 句柄调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLSetStmtAttr 通常返回的 SQLSTATE 值，并解释此函数上下文中的每个值;表示法“（DM）”位于驱动程序管理器返回的 SQLSTATE 的说明之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。

SQLSTATE 错误 说明
01000 常规警告 特定于驱动程序的信息性消息。 （函数返回SQL_SUCCESS_WITH_INFO。）
01S02 选项值已更改 驱动程序不支持 ValuePtr 中指定的值，或者 ValuePtr 中指定的值由于实现工作条件而无效，因此驱动程序替换了类似的值。 （可以调用 SQLGetStmtAttr 来确定临时替换的值。替换值对 StatementHandle 有效，直到游标关闭，此时语句属性将还原为其以前的值。 可以更改的语句属性包括：

SQL_ ATTR_CONCURRENCY SQL_ ATTR_CURSOR_TYPE SQL_ ATTR_KEYSET_SIZE SQL_ ATTR_MAX_LENGTH SQL_ ATTR_MAX_ROWS SQL_ ATTR_QUERY_TIMEOUT SQL_ATTR_ROW_ARRAY_SIZE SQL_ ATTR_SIMULATE_CURSOR

（函数返回SQL_SUCCESS_WITH_INFO。）
08S01 通信链接失败 驱动程序与驱动程序连接到的数据源之间的通信链接在函数完成处理之前失败。
24000 游标状态无效 该 属性 是SQL_ATTR_CONCURRENCY、SQL_ATTR_CURSOR_TYPE、SQL_ATTR_SIMULATE_CURSOR或SQL_ATTR_USE_BOOKMARKS，并且光标已打开。
HY000 常规错误 发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY009 无效使用 null 指针 Attribute 参数标识了一个需要字符串属性的语句属性，ValuePtr 参数是空指针。
HY010 函数序列错误 （DM） 为与 StatementHandle 关联的连接句柄调用异步执行函数。 调用 SQLSetStmtAttr 函数时，此异步函数仍在执行。

（DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect 或 SQLMoreResults，并返回了SQL_PARAM_DATA_AVAILABLE。 在检索所有流式处理参数的数据之前调用此函数。

（DM） 为 StatementHandle 调用异步执行函数，并在调用此函数时仍在执行。

（DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，并返回了SQL_NEED_DATA。 在为所有数据执行参数或列发送数据之前调用此函数。
HY011 无法立即设置属性 该 属性 是SQL_ATTR_CONCURRENCY、SQL_ ATTR_CURSOR_TYPE、SQL_ ATTR_SIMULATE_CURSOR或SQL_ ATTR_USE_BOOKMARKS，并且已准备好该语句。
HY013 内存管理错误 无法处理函数调用，因为基础内存对象无法访问，可能是因为内存条件低。
HY017 自动分配的描述符句柄的使用无效 （DM） 属性参数SQL_ATTR_IMP_ROW_DESC或SQL_ATTR_IMP_PARAM_DESC。

（DM） Attribute 参数SQL_ATTR_APP_ROW_DESC或SQL_ATTR_APP_PARAM_DESC，ValuePtr 中的值是隐式分配的描述符句柄，而不是最初为 ARD 或 APD 分配的句柄。
HY024 属性值无效 给定指定的属性值后，ValuePtr 中指定了无效值。 （驱动程序管理器仅针对接受一组离散值（如SQL_ATTR_ACCESS_MODE或SQL_ ATTR_ASYNC_ENABLE）的连接和语句属性返回此 SQLSTATE。对于所有其他连接和语句属性，驱动程序必须验证 ValuePtr 中指定的值。

Attribute 参数SQL_ATTR_APP_ROW_DESC或SQL_ATTR_APP_PARAM_DESC，ValuePtr 是显式分配的描述符句柄，与 StatementHandle 参数不在同一连接上。
HY090 字符串或缓冲区长度无效 （DM） *ValuePtr 是一个字符串，StringLength 参数小于 0，但未SQL_NTS。
HY092 属性/选项标识符无效 （DM） 为参数 特性 指定的值对驱动程序支持的 ODBC 版本无效。

（DM） 为参数 Attribute 指定的值为只读属性。
HY117 连接因未知事务状态而挂起。 仅允许断开连接和只读函数。 （DM） 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。
HYC00 未实现可选功能 为参数 Attribute 指定的值是驱动程序支持的 ODBC 版本的有效 ODBC 语句属性，但驱动程序不支持该属性。

Attribute 参数SQL_ATTR_ASYNC_ENABLE，对具有 infoType SQL_ASYNC_MODE的 SQLGetInfo 的调用将返回SQL_AM_CONNECTION。

Attribute 参数SQL_ATTR_ENABLE_AUTO_IPD，SQL_ATTR_AUTO_IPD的连接属性的值SQL_FALSE。
HYT01 超过连接超时时间 在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr 设置，SQL_ATTR_CONNECTION_TIMEOUT。
IM001 驱动程序不支持此函数 （DM） 与 StatementHandle 关联的驱动程序不支持该函数。
S1118 驱动程序不支持异步通知 如果调用 SQLSetStmtAttr 来设置SQL_ATTR_ASYNC_STMT_EVENT;驱动程序不支持异步通知。

注释

语句属性一直有效，直到另一次调用 SQLSetStmtAttr 更改语句或通过调用 SQLFreeHandle 删除该语句为止。 使用 SQL_CLOSE、SQL_UNBIND 或 SQL_RESET_PARAMS 选项调用 SQLFreeStmt 不会重置语句属性。

如果数据源不支持 ValuePtr 中指定的值，则某些语句属性支持替换类似的值。 在这种情况下，驱动程序返回 SQL_SUCCESS_WITH_INFO 和 SQLSTATE 01S02（选项值已更改）。 例如，如果 属性 SQL_ATTR_CONCURRENCY且 ValuePtr SQL_CONCUR_ROWVER，并且数据源不支持此属性，驱动程序将替换SQL_CONCUR_VALUES并返回SQL_SUCCESS_WITH_INFO。 若要确定替换的值，应用程序会调用 SQLGetStmtAttr。

使用 ValuePtr 设置的信息格式取决于指定的 属性。 SQLSetStmtAttr 接受以下两种不同格式之一的属性信息：字符串或整数值。 属性的说明中记录了每个格式。 此格式适用于 SQLGetStmtAttr 中每个属性返回的信息。 SQLSetStmtAttr 的 ValuePtr 参数指向的字符串长度为 StringLength。

注意

ODBC 3.x 中已弃用通过调用 SQLSetConnectAttr 在连接级别设置语句属性的功能。 ODBC 3.x 应用程序不应在连接级别设置语句属性。 ODBC 3.x 语句属性不能在连接级别设置，但SQL_ATTR_METADATA_ID和SQL_ATTR_ASYNC_ENABLE属性除外，这些属性既是连接属性，又可以是语句属性，也可以在连接级别或语句级别设置。

注意

如果 ODBC 3.x 驱动程序应使用在连接级别设置 ODBC 2.x 语句选项的 ODBC 2.x 应用程序，则只需支持此功能。 有关详细信息，请参阅附录 G 中的 SQLSetConnectOption 映射下的“设置语句选项”：用于向后兼容性的驱动程序准则。

设置描述符字段的语句属性

许多语句属性对应于描述符的标头字段。 设置这些属性实际上会导致描述符字段的设置。 通过调用 SQLSetStmtAttr 而不是 SQLSetDescField 设置字段具有为函数调用获取描述符句柄的优势。

注意

为一个语句调用 SQLSetStmtAttr 可能会影响其他语句。 当显式分配与该语句关联的 APD 或 ARD 并且也与其他语句关联时，将发生这种情况。 由于 SQLSetStmtAttr 修改了 APD 或 ARD，因此修改适用于与此描述符关联的所有语句。 如果这不是必需的行为，应用程序应在再次调用 SQLSetStmtAttr 之前将此描述符与其他语句（通过调用 SQLSetStmtAttr 将SQL_ATTR_APP_ROW_DESC或SQL_ATTR_APP_PARAM_DESC字段设置为其他描述符句柄）取消关联。

当将描述符字段设置为所设置的相应语句属性的结果时，仅针对当前与 StatementHandle 参数标识的语句关联的适用描述符设置该字段，并且属性设置不会影响将来可能与该语句关联的任何描述符。 当对 SQLSetDescField 的调用设置也是语句属性的描述符字段时，将设置相应的语句属性。 如果显式分配的描述符与语句取消关联，则与标头字段对应的语句属性将还原为隐式分配描述符中字段的值。

分配语句时（请参阅 SQLAllocHandle），会自动分配四个描述符句柄并与该语句关联。 显式分配的描述符句柄可以通过调用 sqlAllocHandle 和 fHandleType 为 SQL_HANDLE_DESC 的 fHandleType 来分配描述符句柄，然后调用 SQLSetStmtAttr 将描述符句柄与语句关联，从而与语句相关联。

下表中的语句属性对应于描述符标头字段。

语句属性 标题字段 Desc.
SQL_ATTR_PARAM_BIND_OFFSET_PTR SQL_DESC_BIND_OFFSET_PTR APD
SQL_ATTR_PARAM_BIND_TYPE SQL_DESC_BIND_TYPE APD
SQL_ATTR_PARAM_OPERATION_PTR SQL_DESC_ARRAY_STATUS_PTR APD
SQL_ATTR_PARAM_STATUS_PTR SQL_DESC_ARRAY_STATUS_PTR IPD
SQL_ATTR_PARAMS_PROCESSED_PTR SQL_DESC_ROWS_PROCESSED_PTR IPD
SQL_ATTR_PARAMSET_SIZE SQL_DESC_ARRAY_SIZE APD
SQL_ATTR_ROW_ARRAY_SIZE SQL_DESC_ARRAY_SIZE ARD
SQL_ATTR_ROW_BIND_OFFSET_PTR SQL_DESC_BIND_OFFSET_PTR ARD
SQL_ATTR_ROW_BIND_TYPE SQL_DESC_BIND_TYPE ARD
SQL_ATTR_ROW_OPERATION_PTR SQL_DESC_ARRAY_STATUS_PTR ARD
SQL_ATTR_ROW_STATUS_PTR SQL_DESC_ARRAY_STATUS_PTR IRD
SQL_ATTR_ROWS_FETCHED_PTR SQL_DESC_ROWS_PROCESSED_PTR IRD

语句属性

下表显示了当前定义的属性及其引入的 ODBC 版本：预计驱动程序将定义更多属性，以利用不同的数据源。 ODBC 保留一系列属性;驱动程序开发人员必须保留自己的开放组中特定于驱动程序的值。 有关详细信息，请参阅《特定于驱动程序的数据类型、描述符类型、信息类型、诊断类型和属性》。

属性 ValuePtr 内容
SQL_ATTR_APP_PARAM_DESC （ODBC 3.0） APID 的句柄，用于对语句句柄上的 SQLExecute 和 SQLExecDirect 的后续调用。 此属性的初始值是在最初分配语句时隐式分配的描述符。 如果此属性的值设置为SQL_NULL_DESC或最初为描述符分配的句柄，则以前与语句句柄关联的显式分配的 APD 句柄将取消关联，并且语句句柄将还原为隐式分配的 APD 句柄。

此属性不能设置为为另一个语句隐式分配的描述符句柄或在同一语句上隐式设置的另一个描述符句柄;隐式分配的描述符句柄不能与多个语句或描述符句柄相关联。
SQL_ATTR_APP_ROW_DESC （ODBC 3.0） 用于对语句句柄进行后续提取的 ARD 的句柄。 此属性的初始值是在最初分配语句时隐式分配的描述符。 如果此属性的值设置为SQL_NULL_DESC或最初为描述符分配的句柄，则以前与语句句柄关联的显式分配的 ARD 句柄将取消关联，并且语句句柄将还原为隐式分配的 ARD 句柄。

此属性不能设置为为另一个语句隐式分配的描述符句柄或在同一语句上隐式设置的另一个描述符句柄;隐式分配的描述符句柄不能与多个语句或描述符句柄相关联。
SQL_ATTR_ASYNC_ENABLE （ODBC 1.0） 一个 SQLULEN 值，该值指定是否异步执行使用指定语句调用的函数：

SQL_ASYNC_ENABLE_OFF = 禁用语句级别异步执行支持（默认值）。

SQL_ASYNC_ENABLE_ON = 启用语句级别异步执行支持。

有关详细信息，请参阅异步执行（轮询方法）。

对于具有语句级别异步执行支持的驱动程序，SQL_ATTR_ASYNC_ENABLE语句属性为只读。 其值与在分配语句句柄时具有相同名称的连接级别属性的值相同。

当SQL_ASYNC_MODE InfoType 返回SQL_AM_CONNECTION返回 SQLSTATE HYC00（未实现可选功能）时，调用 SQLSetStmtAttr 设置SQL_ATTR_ASYNC_ENABLE。 有关详细信息，请参阅 SQLSetConnectAttr 函数 。
SQL_ATTR_ASYNC_STMT_EVENT （ODBC 3.8） 作为事件句柄的 SQLPOINTER 值。

通过调用 SQLSetStmtAttr 来设置 SQL_ATTR_ASYNC_STMT_EVENT 属性并指定事件句柄，从而启用异步函数的完成通知。
SQL_ATTR_ASYNC_STMT_PCALLBACK （ODBC 3.8） 异步回调函数的 SQLPOINTER。

只有驱动程序管理器才能使用此属性调用驱动程序的 SQLSetStmtAttr 函数。
SQL_ATTR_ASYNC_STMT_PCONTEXT （ODBC 3.8） 上下文结构的 SQLPOINTER

只有驱动程序管理器才能使用此属性调用驱动程序的 SQLSetStmtAttr 函数。
SQL_ATTR_CONCURRENCY （ODBC 2.0） 一个指定游标并发的 SQLULEN 值：

SQL_CONCUR_READ_ONLY = 游标为只读。 不允许更新。

SQL_CONCUR_LOCK = 游标使用足够低级别的锁定来确保行可以更新。

SQL_CONCUR_ROWVER = 游标使用乐观并发控制，比较 SQLBase ROWID 或 Sybase TIMESTAMP 等行版本。

SQL_CONCUR_VALUES = 游标使用乐观并发控制，比较值。

SQL_ATTR_CONCURRENCY的默认值为SQL_CONCUR_READ_ONLY。

不能为打开的游标指定此属性。 有关详细信息，请参阅 并发类型。

如果SQL_ATTR_CURSOR_TYPE属性更改为不支持当前值SQL_ATTR_CONCURRENCY的类型，则在执行时将更改SQL_ATTR_CONCURRENCY的值，并在调用 SQLExecDirect 或 SQLPrepare 时发出警告。

如果驱动程序支持 SELECT FOR UPDATE 语句，并且当SQL_ATTR_CONCURRENCY的值设置为SQL_CONCUR_READ_ONLY时执行此类语句，将返回错误。 如果SQL_ATTR_CONCURRENCY的值更改为驱动程序支持某些值SQL_ATTR_CURSOR_TYPE但不支持当前值SQL_ATTR_CURSOR_TYPE的值，则调用 SQLExecDirect 或 SQLPrepare 时，将更改SQL_ATTR_CURSOR_TYPE的值，并在调用 SQLExecDirect 或 SQLPrepare 时发出 sqlSTATE 01S02（选项值已更改）。

如果数据源不支持指定的并发性，驱动程序将替换其他并发并返回 SQLSTATE 01S02（选项值已更改）。 对于SQL_CONCUR_VALUES，驱动程序将替换SQL_CONCUR_ROWVER，反之亦然。 对于SQL_CONCUR_LOCK，驱动程序按顺序替换SQL_CONCUR_ROWVER或SQL_CONCUR_VALUES。 在执行时间之前，不会检查替换值的有效性。

有关SQL_ATTR_CONCURRENCY与其他游标属性之间的关系的详细信息，请参阅 游标特征和游标类型。
SQL_ATTR_CURSOR_SCROLLABLE （ODBC 3.0） 一个 SQLULEN 值，该值指定应用程序所需的支持级别。 设置此属性会影响对 SQLExecDirect 和 SQLExecute 的后续调用。

SQL_NONSCROLLABLE = 语句句柄上不需要可滚动游标。 如果应用程序在此句柄上调用 SQLFetchScroll，则 FetchOrientation 的唯一有效值SQL_FETCH_NEXT。 这是默认情况。

SQL_SCROLLABLE = 语句句柄上需要可滚动游标。 调用 SQLFetchScroll 时，应用程序可以指定 FetchOrientation 的任何有效值，从而在顺序模式以外的模式中实现游标定位。

有关可滚动游标的详细信息，请参阅 可滚动游标。 有关SQL_ATTR_CURSOR_SCROLLABLE与其他游标属性之间的关系的详细信息，请参阅 游标特征和游标类型
SQL_ATTR_CURSOR_SENSITIVITY （ODBC 3.0） 一个 SQLULEN 值，该值指定语句句柄上的游标是否对另一个游标对结果集所做的更改可见。 设置此属性会影响对 SQLExecDirect 和 SQLExecute 的后续调用。 应用程序可以读回此属性的值，以获取应用程序最近设置的初始状态或状态。

SQL_UNSPECIFIED = 它未指定游标类型是什么，以及语句句柄上的游标是否使另一个游标对结果集所做的更改可见。 语句句柄上的游标可能会使无、某些或全部此类更改可见。 这是默认情况。

SQL_INSENSITIVE = 语句句柄上的所有游标都显示结果集，而不会反映任何其他游标对结果集所做的任何更改。 不区分光标是只读的。 这对应于静态游标，该游标具有只读并发性。

SQL_SENSITIVE = 语句句柄上的所有游标都可以看到其他游标对结果集所做的所有更改。

有关SQL_ATTR_CURSOR_SENSITIVITY与其他游标属性之间的关系的详细信息，请参阅 游标特征和游标类型。
SQL_ATTR_CURSOR_TYPE （ODBC 2.0） 一个指定游标类型的 SQLULEN 值：

SQL_CURSOR_FORWARD_ONLY = 光标仅向前滚动。

SQL_CURSOR_STATIC = 结果集中的数据是静态的。

SQL_CURSOR_KEYSET_DRIVEN = 驱动程序保存并使用SQL_ATTR_KEYSET_SIZE语句属性中指定的行数的键。

SQL_CURSOR_DYNAMIC = 驱动程序保存并仅使用行集中行的键。

默认值为SQL_CURSOR_FORWARD_ONLY。 在准备好 SQL 语句后，不能指定此属性。

如果数据源不支持指定的游标类型，驱动程序将替换其他游标类型并返回 SQLSTATE 01S02（选项值已更改）。 对于混合或动态游标，驱动程序按顺序替换键集驱动或静态游标。 对于键集驱动的游标，驱动程序将替换静态游标。

有关可滚动游标类型的详细信息，请参阅 可滚动游标类型。 有关SQL_ATTR_CURSOR_TYPE与其他游标属性之间的关系的详细信息，请参阅 游标特征和游标类型。
SQL_ATTR_ENABLE_AUTO_IPD （ODBC 3.0） 一个 SQLULEN 值，该值指定是否执行 IPD 的自动填充：

SQL_TRUE = 在调用 SQLPrepare 后启用 IPD 的自动填充。 SQL_FALSE = 在调用 SQLPrepare 后关闭 IPD 的自动填充。 （应用程序仍可以通过调用 来获取 IPD 字段信息SQLDescribeParam（如果受支持）。）语句属性SQL_ATTR_ENABLE_AUTO_IPD的默认值为SQL_FALSE。 有关详细信息，请参阅 IPD 的自动填充。
SQL_ATTR_FETCH_BOOKMARK_PTR （ODBC 3.0） 指向二进制书签值的 SQLLEN * 。 当使用 fFetchOrientation 等于 SQL_FETCH_BOOKMARK 调用 SQLFetchScroll 时，驱动程序将从此字段中选取书签值。 此字段默认为 null 指针。 有关详细信息，请参阅 按书签滚动。

此字段指向的值不用于通过书签删除、按书签更新或 SQLBulkOperations 中的书签操作提取，这些操作使用缓存在行集缓冲区中的书签。
SQL_ATTR_IMP_PARAM_DESC （ODBC 3.0） IPD 的句柄。 此属性的值是在最初分配语句时分配的描述符。 应用程序无法设置此属性。

可以通过调用 SQLGetStmtAttr 来检索此属性，但不能由对 SQLSetStmtAttr 的调用设置。
SQL_ATTR_IMP_ROW_DESC （ODBC 3.0） IRD 的句柄。 此属性的值是在最初分配语句时分配的描述符。 应用程序无法设置此属性。

可以通过调用 SQLGetStmtAttr 来检索此属性，但不能由对 SQLSetStmtAttr 的调用设置。
SQL_ATTR_KEYSET_SIZE （ODBC 2.0） 一个 SQLULEN，指定键集驱动游标的键集中的行数。 如果键集大小为 0（默认值），则游标完全由键集驱动。 如果键集大小大于 0，则游标是混合的（键集驱动的键集内和键集外部的动态）。 默认键集大小为 0。 有关键集驱动游标的详细信息，请参阅 Keyset-Driven 游标。

如果指定的大小超过最大键集大小，驱动程序将替换该大小并返回 SQLSTATE 01S02（选项值已更改）。

如果键集大小大于 0 且小于行集大小，则 SQLFetch 或 SQLFetchScroll 返回错误。
SQL_ATTR_MAX_LENGTH （ODBC 1.0） 一个 SQLULEN 值，该值指定驱动程序从字符或二进制列返回的最大数据量。 如果 ValuePtr 小于可用数据的长度， SQLFetch 或 SQLGetData 将截断数据并返回SQL_SUCCESS。 如果 ValuePtr 为 0（默认值），驱动程序将尝试返回所有可用数据。

如果指定的长度小于数据源可以返回的最小数据量或大于数据源可以返回的最大数据量，驱动程序将替换该值并返回 SQLSTATE 01S02（选项值已更改）。

可以在打开的游标上设置此属性的值;但是，设置可能不会立即生效，在这种情况下，驱动程序将返回 SQLSTATE 01S02（选项值已更改），并将属性重置为其原始值。

此属性旨在减少网络流量，并且仅当数据源（而不是驱动程序）在多层驱动程序中实现它时才应受支持。 应用程序不应使用此机制来截断数据;若要截断收到的数据，应用程序应在 SQLBindCol 或 SQLGetData 的 BufferLength 参数中指定最大缓冲区长度。
SQL_ATTR_MAX_ROWS （ODBC 1.0） 一个 SQLULEN 值，该值对应于要返回给 SELECT 语句的应用程序的最大行数。 如果 *ValuePtr 等于 0（默认值），驱动程序将返回所有行。

此属性旨在减少网络流量。 从概念上讲，在创建结果集并将结果集限制为第一个 ValuePtr 行时应用。 如果结果集中的行数大于 ValuePtr，则结果集将被截断。

SQL_ATTR_MAX_ROWS适用于语句上的所有结果集，包括目录函数返回的结果集。 SQL_ATTR_MAX_ROWS为游标行计数的值建立最大值。

如果驱动程序无法保证正确实现SQL_ATTR_MAX_ROWS，则驱动程序不应模拟 SQLFetch 或 SQLFetchScroll 的SQL_ATTR_MAX_ROWS行为（如果无法在数据源中实现结果集大小限制）。

驱动程序定义SQL_ATTR_MAX_ROWS是否适用于 SELECT 语句以外的语句（如目录函数）。

可以在打开的游标上设置此属性的值;但是，设置可能不会立即生效，在这种情况下，驱动程序将返回 SQLSTATE 01S02（选项值已更改），并将属性重置为其原始值。
SQL_ATTR_METADATA_ID （ODBC 3.0） 一个 SQLULEN 值，该值确定如何处理目录函数的字符串参数。

如果SQL_TRUE，则目录函数的字符串参数被视为标识符。 此情况并不重要。 对于非二元字符串，驱动程序将删除任何尾随空格，并将字符串折叠为大写。 对于带分隔符的字符串，驱动程序删除任何前导空格或尾随空格，并按字面取分隔符之间的任何内容。 如果其中一个参数设置为 null 指针，则该函数将返回 SQL_ERROR 和 SQLSTATE HY009（null 指针的使用无效）。

如果SQL_FALSE，则目录函数的字符串参数不被视为标识符。 此情况非常重要。 它们可以包含字符串搜索模式，具体取决于参数。

默认值为SQL_FALSE。

采用值列表的 SQLTables 的 TableType 参数不受此属性的影响。

还可以在连接级别设置SQL_ATTR_METADATA_ID。 （它和SQL_ATTR_ASYNC_ENABLE是唯一也是连接属性的语句属性。

有关详细信息，请参阅目录函数中的参数。
SQL_ATTR_NOSCAN （ODBC 1.0） 一个 SQLULEN 值，该值指示驱动程序是否应扫描 SQL 字符串以获取转义序列：

SQL_NOSCAN_OFF = 驱动程序扫描 SQL 字符串以获取转义序列（默认值）。

SQL_NOSCAN_ON = 驱动程序不会扫描 SQL 字符串以获取转义序列。 相反，驱动程序会将语句直接发送到数据源。

有关详细信息，请参阅 ODBC 中的转义序列。
SQL_ATTR_PARAM_BIND_OFFSET_PTR （ODBC 3.0） 一个 SQLULEN * 值，该值指向添加到指针的偏移量，以更改动态参数的绑定。 如果此字段为非 null，驱动程序将取消引用指针，将取消引用的值添加到描述符记录（SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR）中的每个延迟字段，并在绑定时使用新的指针值。 默认情况下，它设置为 null。

绑定偏移量始终直接添加到SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR字段。 如果偏移量更改为其他值，新值仍将直接添加到描述符字段中的值。 新偏移量不会添加到字段值加上任何以前的偏移量。

有关详细信息，请参阅 参数绑定偏移量。

设置此语句属性设置 APD 标头中的SQL_DESC_BIND_OFFSET_PTR字段。
SQL_ATTR_PARAM_BIND_TYPE （ODBC 3.0） 一个 SQLULEN 值，指示要用于动态参数的绑定方向。

此字段设置为SQL_PARAM_BIND_BY_COLUMN（默认值）以选择按列绑定。

若要选择行绑定，此字段设置为结构长度或将绑定到一组动态参数的缓冲区实例。 此长度必须包含所有绑定参数的空间以及结构或缓冲区的任何填充，以确保当绑定参数的地址随指定长度递增时，结果将指向下一组参数中相同参数的开头。 在 ANSI C 中使用 sizeof 运算符时，可以保证此行为。

有关详细信息，请参阅 绑定参数数组。

设置此语句属性设置 APD 标头中的SQL_DESC_ BIND_TYPE字段。
SQL_ATTR_PARAM_OPERATION_PTR （ODBC 3.0） 一个 SQLUSMALLINT * 值，该值指向 SQLUSMALLINT 值数组，用于在执行 SQL 语句期间忽略参数。 每个值都设置为SQL_PARAM_PROCEED（要执行参数）或SQL_PARAM_IGNORE（要忽略参数）。

通过将 APD 中SQL_DESC_ARRAY_STATUS_PTR指向的数组中的状态值设置为SQL_PARAM_IGNORE，可以在处理过程中忽略一组参数。 如果参数集的状态值设置为SQL_PARAM_PROCEED或数组中未设置任何元素，则会处理一组参数。

此语句属性可以设置为 null 指针，在这种情况下，驱动程序不返回参数状态值。 可以随时设置此属性，但在下次 调用 SQLExecDirect 或 SQLExecute 之前，不会使用新值。

如果没有绑定参数，则忽略此属性。

有关详细信息，请参阅 使用参数数组。

设置此语句属性设置 APD 标头中的SQL_DESC_ARRAY_STATUS_PTR字段。
SQL_ATTR_PARAM_STATUS_PTR （ODBC 3.0） 一个 SQLUSMALLINT * 值，该值指向 SQLUSMALLINT 值数组，该值在调用 SQLExecute 或 SQLExecDirect 后包含每个参数值行的状态信息。 仅当PARAMSET_SIZE大于 1 时，才需要此字段。

状态值可以包含以下值：

SQL_PARAM_SUCCESS：已成功为这组参数执行 SQL 语句。

SQL_PARAM_SUCCESS_WITH_INFO：已成功为这组参数执行 SQL 语句;但是，诊断数据结构中提供了警告信息。

SQL_PARAM_ERROR：处理这组参数时出错。 诊断数据结构中提供了其他错误信息。

SQL_PARAM_UNUSED：此参数集未使用，可能是因为一些以前的参数集导致错误中止了进一步处理，或者由于为由SQL_ATTR_PARAM_OPERATION_PTR指定的数组中的参数集设置了SQL_PARAM_IGNORE。

SQL_PARAM_DIAG_UNAVAILABLE：驱动程序将参数数组视为整体单元，因此不会生成此级别的错误信息。

此语句属性可以设置为 null 指针，在这种情况下，驱动程序不返回参数状态值。 可以随时设置此属性，但在下次 调用 SQLExecute 或 SQLExecDirect 之前，不会使用新值。 请注意，设置此属性可能会影响驱动程序实现的输出参数行为。

有关详细信息，请参阅 使用参数数组。

设置此语句属性设置 IPD 标头中的SQL_DESC_ARRAY_STATUS_PTR字段。
SQL_ATTR_PARAMS_PROCESSED_PTR （ODBC 3.0） 一个 SQLULEN * 记录字段，该字段指向一个缓冲区，用于返回已处理的参数集数，包括错误集。 如果这是空指针，则不返回数字。

设置此语句属性设置 IPD 标头中的SQL_DESC_ROWS_PROCESSED_PTR字段。

如果调用 填充此属性指向的缓冲区的 SQLExecDirect 或 SQLExecute 不会返回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，则缓冲区的内容是未定义的。

有关详细信息，请参阅 使用参数数组。
SQL_ATTR_PARAMSET_SIZE （ODBC 3.0） 一个 SQLULEN 值，该值指定每个参数的值数。 如果SQL_ATTR_PARAMSET_SIZE大于 1、SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR 和 APD 点到数组SQL_DESC_OCTET_LENGTH_PTR。 每个数组的基数等于此字段的值。

如果没有绑定参数，则忽略此属性。

有关详细信息，请参阅 使用参数数组。

设置此语句属性设置 APD 标头中的SQL_DESC_ARRAY_SIZE字段。
SQL_ATTR_QUERY_TIMEOUT （ODBC 1.0） 一个 SQLULEN 值，该值对应于等待 SQL 语句在返回到应用程序之前要执行的秒数。 如果 ValuePtr 等于 0（默认值），则不会超时。

如果指定的超时超过数据源中的最大超时或小于最小超时， 则 SQLSetStmtAttr 将替换该值并返回 SQLSTATE 01S02（选项值已更改）。

请注意，如果 SELECT 语句超时，应用程序不需要调用 SQLCloseCursor 来重复使用该语句。

此语句属性中设置的查询超时在同步和异步模式下有效。
SQL_ATTR_RETRIEVE_DATA （ODBC 2.0） SQLULEN 值：

SQL_RD_ON = SQLFetchScroll ，在 ODBC 3.x 中， SQLFetch 在将数据定位到指定位置后检索数据。 这是默认情况。

SQL_RD_OFF = SQLFetchScroll ，并且，在 ODBC 3.x 中， SQLFetch 在定位游标后不会检索数据。

通过将SQL_RETRIEVE_DATA设置为SQL_RD_OFF，应用程序可以验证行是否存在或检索行的书签，而不会产生检索行的开销。 有关详细信息，请参阅 滚动和提取行。

可以在打开的游标上设置此属性的值;但是，设置可能不会立即生效，在这种情况下，驱动程序将返回 SQLSTATE 01S02（选项值已更改），并将属性重置为其原始值。
SQL_ATTR_ROW_ARRAY_SIZE （ODBC 3.0） 一个 SQLULEN 值，该值指定每次调用 SQLFetch 或 SQLFetchScroll 返回的行数。 它也是 SQLBulkOperations 中批量书签操作中使用的书签数组中的行数。 默认值是 1秒。

如果指定的行集大小超过数据源支持的最大行集大小，驱动程序将替换该值并返回 SQLSTATE 01S02（选项值已更改）。

有关详细信息，请参阅 行集大小。

设置此语句属性设置 ARD 标头中的SQL_DESC_ARRAY_SIZE字段。
SQL_ATTR_ROW_BIND_OFFSET_PTR （ODBC 3.0） 一个 SQLULEN * 值，该值指向添加到指针的偏移量，用于更改列数据的绑定。 如果此字段为非 null，驱动程序将取消引用指针，将取消引用的值添加到描述符记录（SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR）中的每个延迟字段，并在绑定时使用新的指针值。 默认情况下，它设置为 null。

设置此语句属性可设置 ARD 标头中的SQL_DESC_BIND_OFFSET_PTR字段。
SQL_ATTR_ROW_BIND_TYPE （ODBC 1.0） 一个 SQLULEN 值，该值设置在关联语句上调用 SQLFetch 或 SQLFetchScroll 时要使用的绑定方向。 通过将值设置为SQL_BIND_BY_COLUMN来选择列式绑定。 通过将值设置为将结果列绑定到的缓冲区的长度或缓冲区的长度来选择行绑定绑定。

如果指定了长度，则它必须包含所有绑定列的空间以及结构或缓冲区的任何填充，以确保当绑定列的地址以指定长度递增时，结果将指向下一行中相同列的开头。 将 sizeof 运算符用于 ANSI C 中的结构或联合时，可以保证此行为。

列式绑定是 SQLFetch 和 SQLFetchScroll 的默认绑定方向。

有关详细信息，请参阅 绑定列以用于块游标。

设置此语句属性设置 ARD 标头中的SQL_DESC_BIND_TYPE字段。
SQL_ATTR_ROW_NUMBER （ODBC 2.0） 一个 SQLULEN 值，该值是整个结果集中当前行的数目。 如果无法确定当前行的数目或没有当前行，驱动程序将返回 0。

可以通过调用 SQLGetStmtAttr 来检索此属性，但不能由对 SQLSetStmtAttr 的调用设置。
SQL_ATTR_ROW_OPERATION_PTR （ODBC 3.0） 一个 SQLUSMALLINT * 值，该值指向 SQLUSMALLINT 值数组，用于在使用 SQLSetPos 进行大容量操作期间忽略行。 每个值都设置为SQL_ROW_PROCEED（要包含在大容量操作中的行）或SQL_ROW_IGNORE（要从大容量操作中排除的行）。 （调用期间 使用此数组无法忽略行SQLBulkOperations.）

此语句属性可以设置为 null 指针，在这种情况下，驱动程序不返回行状态值。 可以随时设置此属性，但在下次 调用 SQLSetPos 之前不会使用新值。

有关详细信息，请参阅 使用 SQLSetPos 更新行集中的行，以及 使用 SQLSetPos 删除行集中的行。

设置此语句属性可设置 ARD 中的SQL_DESC_ARRAY_STATUS_PTR字段。
SQL_ATTR_ROW_STATUS_PTR （ODBC 3.0） 一个 SQLUSMALLINT * 值，该值指向在调用 SQLFetch 或 SQLFetchScroll 后包含行状态值的 SQLUSMALLINT 值数组。 数组包含的元素数与行集中的行数相同。

此语句属性可以设置为 null 指针，在这种情况下，驱动程序不返回行状态值。 可以随时设置此属性，但在下次调用 SQLBulkOperations、SQLFetch、SQLFetch、SQLFetchScroll 或 SQLSetPos 之前，不会使用新值。

有关详细信息，请参阅 提取的行数和状态。

设置此语句属性可设置 IRD 标头中的SQL_DESC_ARRAY_STATUS_PTR字段。

此属性由 ODBC 2.x 驱动程序映射到对 SQLExtendedFetch 的调用中的 rgbRowStatus 数组。
SQL_ATTR_ROWS_FETCHED_PTR （ODBC 3.0） 一个 SQLULEN * 值，该值指向一个缓冲区，用于返回调用 SQLFetch 或 SQLFetchScroll 后提取的行数;调用 SQLSetPos 时执行的大容量操作所影响的行数，其参数为 SQL_REFRESH;或受 SQLBulkOperations 执行批量操作影响的行数。 此数字包括错误行。

有关详细信息，请参阅 提取的行数和状态。

设置此语句属性设置 IRD 标头中的SQL_DESC_ROWS_PROCESSED_PTR字段。

如果对填充此属性指向的缓冲区中的 SQLFetch 或 SQLFetchScroll 的调用不会返回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，则未定义缓冲区的内容。
SQL_ATTR_SIMULATE_CURSOR （ODBC 2.0） 一个 SQLULEN 值，该值指定模拟定位更新和删除语句的驱动程序是否保证此类语句仅影响一行。

为了模拟定位的更新和删除语句，大多数驱动程序都构造一个搜索的 UPDATE 或 DELETE 语句，其中包含一个 WHERE 子句，该子句指定当前行中每列的值。 除非这些列构成唯一键，否则此类语句可能会影响多行。

为了保证此类语句仅影响一行，驱动程序确定唯一键中的列，并将这些列添加到结果集中。 如果应用程序保证结果集中的列构成唯一键，则不需要驱动程序执行此操作。 这可以减少执行时间。

SQL_SC_NON_UNIQUE = 驱动程序不能保证模拟定位更新或删除语句仅影响一行;应用程序负责执行此操作。 如果语句影响多个行， SQLExecute、 SQLExecDirect 或 SQLSetPos 将返回 SQLSTATE 01001（游标操作冲突）。

SQL_SC_TRY_UNIQUE = 驱动程序尝试保证模拟定位更新或删除语句仅影响一行。 驱动程序始终执行此类语句，即使它们可能会影响多个行，例如没有唯一键时也是如此。 如果语句影响多个行， SQLExecute、 SQLExecDirect 或 SQLSetPos 将返回 SQLSTATE 01001（游标操作冲突）。

SQL_SC_UNIQUE = 驱动程序保证模拟定位更新或删除语句仅影响一行。 如果驱动程序无法保证给定语句的此项， SQLExecDirect 或 SQLPrepare 将返回错误。

如果数据源为定位更新和删除语句提供本机 SQL 支持，并且驱动程序不模拟游标，则当请求SQL_SC_UNIQUE SQL_SIMULATE_CURSOR时，将返回SQL_SUCCESS。 如果请求SQL_SC_TRY_UNIQUE或SQL_SC_NON_UNIQUE，则返回SQL_SUCCESS_WITH_INFO。 如果数据源提供SQL_SC_TRY_UNIQUE支持级别，并且驱动程序未提供，则SQL_SUCCESS返回SQL_SC_TRY_UNIQUE，SQL_SUCCESS_WITH_INFO返回SQL_SC_NON_UNIQUE。

如果数据源不支持指定的游标模拟类型，驱动程序将替换其他模拟类型并返回 SQLSTATE 01S02（选项值已更改）。 对于SQL_SC_UNIQUE，驱动程序按顺序替换SQL_SC_TRY_UNIQUE或SQL_SC_NON_UNIQUE。 对于SQL_SC_TRY_UNIQUE，驱动程序将替换SQL_SC_NON_UNIQUE。

默认值为SQL_SC_UNIQUE。

有关详细信息，请参阅 模拟定位更新和删除语句。
SQL_ATTR_USE_BOOKMARKS （ODBC 2.0） 一个 SQLULEN 值，该值指定应用程序是否将书签与游标一起使用：

SQL_UB_OFF = 关闭（默认值）

SQL_UB_VARIABLE = 应用程序将使用带有游标的书签，并且驱动程序将提供可变长度的书签（如果支持）。 ODBC 3.x 中已弃用SQL_UB_FIXED。 ODBC 3.x 应用程序应始终使用可变长度书签，即使使用 ODBC 2.x 驱动程序（仅支持 4 字节的固定长度书签）。 这是因为固定长度书签只是可变长度书签的特殊情况。 使用 ODBC 2.x 驱动程序时，驱动程序管理器会将SQL_UB_VARIABLE映射到SQL_UB_FIXED。

若要将书签与游标一起使用，应用程序必须在打开游标之前使用SQL_UB_VARIABLE值指定此属性。

有关详细信息，请参阅 检索书签。

[1] 仅当描述符是实现描述符，而不是应用程序描述符时，才能异步调用这些函数。

请参阅 “列明智绑定 ”和 “行-Wise 绑定”。

有关以下内容的信息 请参阅
取消语句处理 SQLCancel 函数
返回连接属性的设置 SQLGetConnectAttr 函数
返回语句属性的设置 SQLGetStmtAttr 函数
设置连接属性 SQLSetConnectAttr 函数
设置描述符的单个字段 SQLSetDescField 函数

另请参阅

ODBC API 参考
ODBC 头文件