SQLSetStmtAttr 函数

  • 项目

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

摘要
SQLSetStmtAttr 设置与语句相关的属性。

注意

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

语法

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

参数

StatementHandle
[输入]语句句柄。

Attribute
[输入]“注释”中列出的要设置的选项。

ValuePtr
[输入]要与 Attribute 关联的值。 根据 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 (长度 的结果) 宏置于 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时，可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值，该 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_STMT，句 柄 为 StatementHandle。 下表列出了 SQLSetStmtAttr 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 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) SQLExecute、 SQLExecDirect 或 SQLMoreResults 已为 StatementHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。 此函数是在检索所有流式处理参数的数据之前调用的。

(DM) 为 StatementHandle 调用了异步执行的函数，并在调用此函数时仍在执行。

(DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 已为 StatementHandle 调用并返回SQL_NEED_DATA。 在为所有数据执行时参数或列发送数据之前调用了此函数。
HY011 现在无法设置属性 属性已SQL_ATTR_CONCURRENCY、SQL_ ATTR_CURSOR_TYPE、SQL_ ATTR_SIMULATE_CURSOR或SQL_ ATTR_USE_BOOKMARKS，并且已准备好语句。
HY013 内存管理错误 无法处理函数调用，因为无法访问基础内存对象，可能是因为内存不足。
HY017 自动分配的描述符句柄使用无效 (DM) Attribute 参数已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) 为参数 Attribute 指定的值对驱动程序支持的 ODBC 版本无效。

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

Attribute 参数已SQL_ATTR_ASYNC_ENABLE，并且对 InfoType 为 SQL_ASYNC_MODE 的 SQLGetInfo 的调用将返回SQL_AM_CONNECTION。

已SQL_ATTR_ENABLE_AUTO_IPD Attribute 参数，并且SQL_FALSE了连接属性SQL_ATTR_AUTO_IPD的值。
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 (选项值) 更改。 例如，如果 Attribute 为 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 Mapping 下的“在连接级别设置语句选项”。

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

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

注意

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

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

当 (SQLAllocHandle) 分配语句时，会自动分配四个描述符句柄并与该语句相关联。 显式分配的描述符句柄可以与语句相关联，方法是调用具有 fHandleType 的 SQLAllocHandle SQL_HANDLE_DESC以分配描述符句柄，然后调用 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 税务局
SQL_ATTR_ROWS_FETCHED_PTR SQL_DESC_ROWS_PROCESSED_PTR 税务局

语句属性

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

属性 ValuePtr 内容
SQL_ATTR_APP_PARAM_DESC (ODBC 3.0) 用于在语句句柄上对 SQLExecute 和 SQLExecDirect 进行后续调用的 APD 的句柄。 此属性的初始值是最初分配语句时隐式分配的描述符。 如果此属性的值设置为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为只读。 其值与分配语句句柄时具有相同名称的连接级别属性的值相同。

调用 SQLSetStmtAttr 以在SQL_ASYNC_MODE InfoType 返回时设置SQL_ATTR_ASYNC_ENABLE SQL_AM_CONNECTION返回 SQLSTATE HYC00 (可选功能未) 实现。 有关详细信息，请参阅 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的当前值，则 SQL_ATTR_CURSOR_TYPE 的值将在执行时更改，SQLSTATE 01S02 (选项值更改) 调用 SQLExecDirect 或 SQLPrepare 时发出。

如果数据源不支持指定的并发，驱动程序将替换其他并发，并返回 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 的自动填充。 (应用程序仍可以通过调用 SQLDescribeParam 获取 IPD 字段信息（如果 supported）。) 语句属性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。 有关键集驱动的游标的详细信息，请参阅 键集驱动的游标。

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

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

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

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

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

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

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

如果无法在数据源上实现结果集大小限制，驱动程序不应模拟 SQLFetch 或 SQLFetchScroll (的SQL_ATTR_MAX_ROWS行为) 如果无法保证正确实现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。 (It 和 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 * 值，该值指向用于在执行 SQL 语句期间忽略参数的 SQLUSMALLINT 值数组。 每个值都设置为要) 执行参数的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和SQL_DESC_OCTET_LENGTH_PTR APD 指向数组。 每个数组的基数等于此字段的值。

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

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

设置此语句属性将设置 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 * 值，该值指向使用 SQLSetPos 执行批量操作期间用于忽略行的 SQLUSMALLINT 值数组。 每个值都设置为要包含在批量操作) 中的行的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、 SQLFetchScroll 或 SQLSetPos 时才会使用新值。

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

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

在调用 SQLExtendedFetch 时，ODBC 2.x 驱动程序将此属性映射到 rgbRowStatus 数组。
SQL_ATTR_ROWS_FETCHED_PTR (ODBC 3.0) 一个 SQLULEN * 值，该值指向要返回调用 SQLFetch 或 SQLFetchScroll 后提取的行数的缓冲区;由调用 SQLSetPos 执行的批量操作影响的行数，其 Operation 参数为 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 (Cursor 操作冲突) 。

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

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_SC_TRY_UNIQUE返回SQL_SUCCESS，并为SQL_SC_NON_UNIQUE返回SQL_SUCCESS_WITH_INFO。

如果数据源不支持指定的游标模拟类型，驱动程序将替换其他模拟类型，并返回 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 应用程序应始终使用可变长度书签，即使在使用仅支持 4 字节固定长度书签) 的 ODBC 2.x 驱动程序 (也是如此。 这是因为固定长度书签只是可变长度书签的特殊情况。 使用 ODBC 2.x 驱动程序时，驱动程序管理器会将SQL_UB_VARIABLE映射到SQL_UB_FIXED。

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

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

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

请参阅 列式绑定 和 按行绑定。

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

另请参阅

ODBC API 参考
ODBC 头文件