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 终止字符,) 值Ptr 指向的缓冲区中返回。

BufferLength
[输入]如果 Attribute 是 ODBC 定义的属性, ValuePtr 指向字符串或二进制缓冲区,则此参数应为 *ValuePtr 的长度。 如果 Attribute 是 ODBC 定义的属性,并且 *ValuePtr 是整数,则忽略 BufferLength 。 如果在调用 SQLGetStmtAttrW () 时,在 *ValuePtr 中返回的值是 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
[输出]指向缓冲区的指针,用于返回总字节数 (不包括可用于 在 *ValuePtr 中返回的 null 终止字符) 。 如果属性值是一个字符串,并且可用于返回的字节数大于或等于 BufferLength则 *ValuePtr 中的数据将被截断为 BufferLength 减去 null 终止字符的长度,并且由驱动程序以 null 结尾。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

诊断

当 SQLGetStmtAttr 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时,可以通过使用 handleType of SQL_HANDLE_STMT 和 StatementHandle句柄调用 SQLGetDiagRec 来获取关联的 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。 参数 MessageTextSQLGetDiagRec 返回的错误消息描述错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY010 函数序列错误 (DM) 为与 StatementHandle 关联的连接句柄调用异步执行函数。 调用 SQLGetStmtAttr 函数时,此异步函数仍在执行。

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

(DM) SQLExecuteSQLExecDirectSQLBulkOperationsSQLSetPos 已针对 StatementHandle 调用并返回SQL_NEED_DATA。 在为所有数据执行参数或列发送数据之前调用此函数。
HY013 内存管理错误 无法处理函数调用,因为基础内存对象无法访问,可能是由于内存条件低。
HY090 字符串或缓冲区长度无效 (DM) *ValuePtr 是一个字符串,BufferLength 小于零,但不等于SQL_NTS。
HY092 属性/选项标识符无效 为参数 属性 指定的值对于驱动程序支持的 ODBC 版本无效。
HY109 游标位置无效 Attribute 参数SQL_ATTR_ROW_NUMBER并且行已被删除或无法提取。
HY117 连接因未知事务状态而挂起。 仅允许断开连接和只读函数。 (DM) 有关挂起状态的详细信息,请参阅 SQLEndTran 函数
HYC00 未实现可选功能 为参数 属性 指定的值是驱动程序支持的 ODBC 版本的有效 ODBC 语句属性,但驱动程序不支持。
HYT01 超过连接超时时间 在数据源响应请求之前,连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr 设置,SQL_ATTR_CONNECTION_TIMEOUT。
IM001 驱动程序不支持此函数 (DM) 与 StatementHandle 对应的驱动程序不支持该函数。

注释

有关语句属性的一般信息,请参阅 语句属性

SQLGetStmtAttr 的调用在 *ValuePtr 中返回 属性中指定的语句属性的值。 该值可以是 SQLULEN 值或以 null 结尾的字符串。 如果该值是 SQLULEN 值,则某些驱动程序可能只写入低 32 位或 16 位缓冲区,并使高阶位保持不变。 因此,应用程序应使用 SQLULEN 的缓冲区,并在调用此函数之前将值初始化为 0。 此外,不使用 BufferLengthStringLengthPtr 参数。 如果值为 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 函数

另请参阅

ODBC API 参考
ODBC 头文件