SQLRowCount Function(SQLRowCount 函数)
一致性
引入的版本:ODBC 1.0 标准符合性:ISO 92
摘要
SQLRowCount 返回受 UPDATE、 INSERT 或 DELETE 语句影响的行数; SQLBulkOperations 中的SQL_ADD、SQL_UPDATE_BY_BOOKMARK或SQL_DELETE_BY_BOOKMARK操作;或 SQLSetPos 中的SQL_UPDATE或SQL_DELETE操作。
语法
SQLRETURN SQLRowCount(
SQLHSTMT StatementHandle,
SQLLEN * RowCountPtr);
参数
StatementHandle
[输入]语句句柄。
RowCountPtr
[输出]指向要在其中返回行计数的缓冲区。 对于 UPDATE、 INSERT 和 DELETE 语句,对于 SQLBulkOperations 中的SQL_ADD、SQL_UPDATE_BY_BOOKMARK和SQL_DELETE_BY_BOOKMARK操作,以及 SQLSetPos 中的SQL_UPDATE或SQL_DELETE操作,在 *RowCountPtr 中返回的值是受请求影响的行数;如果受影响的行数不可用,则返回 -1。
调用 SQLExecute、 SQLExecDirect、 SQLBulkOperations、 SQLSetPos 或 SQLMoreResults 时,诊断数据结构的SQL_DIAG_ROW_COUNT字段设置为行计数,并且行计数以依赖于实现的方式缓存。 SQLRowCount 返回缓存的行计数值。 缓存的行计数值在语句句柄设置回准备或分配的状态、重新执行语句或调用 SQLCloseCursor 之前有效。 请注意,如果自设置SQL_DIAG_ROW_COUNT字段后调用了函数, 则 SQLRowCount 返回的值可能与SQL_DIAG_ROW_COUNT字段中的值不同,因为任何函数调用都会将SQL_DIAG_ROW_COUNT字段重置为 0。
对于其他语句和函数,驱动程序可以定义 *RowCountPtr 中返回的值。 例如,某些数据源可能能够在提取行之前返回 SELECT 语句或目录函数返回的行数。
注意
许多数据源在提取结果集前无法返回行数;为了最大程度地实现互操作性,应用程序不应依赖于此行为。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。
诊断
当 SQLRowCount 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时,可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值,该 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_STMT, 句柄 为 StatementHandle。 下表列出了 SQLRowCount 通常返回的 SQLSTATE 值,并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR,除非另有说明。
SQLSTATE | 错误 | 说明 |
---|---|---|
01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
HY000 | 常规错误 | 发生错误,其中没有特定的 SQLSTATE,并且没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述了错误及其原因。 |
HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
HY010 | 函数序列错误 | (DM) 为 与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLRowCount 函数时,此异步函数仍在执行。 (DM) SQLExecute、 SQLExecDirect 或 SQLMoreResults 已为 StatementHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。 此函数是在检索所有流式处理参数的数据之前调用的。 (DM) 在为 StatementHandle 调用 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos 之前调用了函数。 (DM) 为 StatementHandle 调用了异步执行的函数,并在调用此函数时仍在执行。 (DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 已为 StatementHandle 调用并返回SQL_NEED_DATA。 在为所有数据执行时参数或列发送数据之前调用了此函数。 |
HY013 | 内存管理错误 | 无法处理函数调用,因为无法访问基础内存对象,可能是因为内存不足。 |
HY117 | 由于未知的事务状态,连接已挂起。 仅允许断开连接和只读函数。 | (DM) 有关挂起状态的详细信息,请参阅 SQLEndTran 函数。 |
HYT01 | 超过连接超时时间 | 在数据源响应请求之前,连接超时期限已过期。 连接超时期限是通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置的。 |
IM001 | 驱动程序不支持此函数 | (DM) 与 StatementHandle 关联的驱动程序不支持 函数。 |
注释
如果在语句句柄上执行的最后一个 SQL 语句不是 UPDATE、INSERT 或 DELETE 语句,或者上一次调用 SQLBulkOperations 中的 Operation 参数未SQL_ADD、SQL_UPDATE_BY_BOOKMARK或SQL_DELETE_BY_BOOKMARK,或者上一次调用 SQLSetPos 中的 Operation 参数未SQL_UPDATE或SQL_DELETE, RowCountPtr 的值由驱动程序定义。 有关详细信息,请参阅 确定受影响的行数。
相关函数
有关以下方面的信息 | 请参阅 |
---|---|
执行 SQL 语句 | SQLExecDirect 函数 |
执行准备好的 SQL 语句 | SQLExecute 函数 |