SQLGetStmtAttr 函数
一致性
引入的版本：ODBC 3.0 标准符合性：ISO 92
摘要
SQLGetStmtAttr 返回语句属性的当前设置。
注意
有关驱动程序管理器在 ODBC 3 时将此函数映射到的内容的详细信息。x 应用程序正在使用 ODBC 2。x 驱动程序，请参阅 映射替换函数以实现应用程序的向后兼容性。
语法
SQLRETURN SQLGetStmtAttr(
SQLHSTMT StatementHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
参数
StatementHandle
[输入]语句句柄。
Attribute
[输入]要检索的属性。
ValuePtr
[输出]指向缓冲区的指针，该缓冲区将返回特性中指定的 属性值。
如果 ValuePtr 为 NULL， StringLengthPtr 仍将返回总字节数 (不包括字符数据的 null 终止字符数，) ValuePtr 指向的缓冲区中可以返回。
BufferLength
[输入]如果 Attribute 是 ODBC 定义的属性，并且 ValuePtr 指向字符串或二进制缓冲区，则此参数的长度应为 *ValuePtr。 如果 Attribute 是 ODBC 定义的属性，并且 *ValuePtr 是整数，则忽略 BufferLength 。 如果在 *ValuePtr 中返回的值是调用 SQLGetStmtAttrW) 时 (的 Unicode 字符串， 则 BufferLength 参数必须是偶数。
如果 Attribute 是驱动程序定义的属性，则应用程序通过设置 BufferLength 参数向驱动程序管理器指示属性的性质。 BufferLength 可以具有以下值：
如果 *ValuePtr 是指向字符串的指针，则 BufferLength 是字符串的长度或SQL_NTS。
如果 *ValuePtr 是指向二进制缓冲区的指针，则应用程序会将SQL_LEN_BINARY_ATTR (长度 的结果) 宏放在 BufferLength 中。 这会在 BufferLength 中放置一个负值。
如果 *ValuePtr 是指向字符串或二进制字符串以外的值的指针，则 BufferLength 应具有值SQL_IS_POINTER。
如果 *ValuePtr 包含固定长度的数据类型，则 BufferLength 视情况SQL_IS_INTEGER或SQL_IS_UINTEGER。
StringLengthPtr
[输出]指向缓冲区的指针，该缓冲区返回的总字节数 (不包括 null 终止字符) 可在 *ValuePtr 中返回。 如果属性值是字符串，并且可返回的字节数大于或等于 BufferLength，则 *ValuePtr 中的数据将被截断为 BufferLength 减去 null 终止字符的长度，并由驱动程序以 null 结尾。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。
诊断
当 SQLGetStmtAttr 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过调用 SQLGetDiagRec 和 SQL_HANDLE_STMT HandleofStatementHandle 来获取关联的 SQLSTATE 值。 下表列出了 SQLGetStmtAttr 通常返回的 SQLSTATE 值，并解释了此函数上下文中的每个值：表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATE 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 01004 | 字符串数据，右截断 | *ValuePtr 中返回的数据被截断为 BufferLength 减去 null 终止字符的长度。 非结构化字符串值的长度在 *StringLengthPtr 中返回。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 24000 | 游标状态无效 | 参数 属性 SQL_ATTR_ROW_NUMBER且游标未打开，或者游标位于结果集开始之前或结果集末尾之后。 |
| HY000 | 常规错误 | 发生错误，其中没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec 在参数 MessageText 中返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY010 | 函数序列错误 | (DM) 为与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLGetStmtAttr 函数时，此异步函数仍在执行。 (DM) 为 StatementHandle 调用了异步执行的函数，并在调用此函数时仍在执行。 (DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 已为 StatementHandle 调用，并返回SQL_NEED_DATA。 在针对所有数据执行参数或列发送数据之前调用了此函数。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为无法访问基础内存对象，可能是由于内存不足。 |
| HY090 | 无效的字符串或缓冲区长度 | (DM) *ValuePtr 是一个字符串，BufferLength 小于零，但不等于 SQL_NTS。 |
| HY092 | 无效的属性/选项标识符 | 为参数 Attribute 指定的值对驱动程序支持的 ODBC 版本无效。 |
| HY109 | 游标位置无效 | Attribute 参数已SQL_ATTR_ROW_NUMBER并且行已被删除或无法提取。 |
| HY117 | 由于事务状态未知，连接已暂停。 仅允许断开连接和只读函数。 | (DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYC00 | 未实现可选功能 | 为参数 Attribute 指定的值是驱动程序支持的 ODBC 版本的有效 ODBC 语句属性，但驱动程序不支持。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置。 |
| IM001 | 驱动程序不支持此函数 | (DM) 对应于 StatementHandle 的 驱动程序不支持 函数。 |
注释
有关语句属性的一般信息，请参阅 语句属性。
对 SQLGetStmtAttr 的 调用在 *ValuePtr 中返回 Attribute 中指定的语句属性的值。 该值可以是 SQLULEN 值，也可以是以 null 结尾的字符串。 如果值是 SQLULEN 值，则某些驱动程序可能只写入缓冲区的较低 32 位或 16 位，并保留高阶位不变。 因此，应用程序应使用 SQLULEN 的缓冲区，并在调用此函数之前将值初始化为 0。 此外，不使用 BufferLength 和 StringLengthPtr 参数。 如果值为以 null 结尾的字符串，则应用程序在 BufferLength 参数中指定该字符串的最大长度，驱动程序在 *StringLengthPtr 缓冲区中返回该字符串的长度。
允许调用 SQLGetStmtAttr 的应用程序使用 ODBC 2。x 驱动程序，对 SQLGetStmtAttr 的 调用在驱动程序管理器中映射到 SQLGetStmtOption。
以下语句属性是只读的，因此可由 SQLGetStmtAttr 检索，但不能由 SQLSetStmtAttr 设置：
SQL_ATTR_IMP_PARAM_DESC
SQL_ATTR_IMP_ROW_DESC
SQL_ATTR_ROW_NUMBER
有关可设置和检索的属性列表，请参阅 SQLSetStmtAttr。
相关函数
| 有关以下方面的信息 | 请参阅 |
|---|---|
| 返回连接属性的设置 | SQLGetConnectAttr 函数 |
| 设置连接属性 | SQLSetConnectAttr 函数 |
| 设置语句属性 | SQLSetStmtAttr 函数 |