SQLRowCount() - Get row count

SQLRowCount() returns the number of rows in a table that were affected by an UPDATE, INSERT, DELETE, or MERGE statement. You can call SQLRowCount() against a table or against a view that is based on the table. SQLExecute() or SQLExecDirect() must be called before SQLRowCount() is called.

ODBC specifications for SQLRowCount()

Table 1. SQLRowCount() specifications
ODBC specification level In X/Open CLI CAE specification? In ISO CLI specification?
1.0 Yes Yes

Syntax

For 31-bit applications, use the following syntax:

SQLRETURN   SQLRowCount      (SQLHSTMT          hstmt,
                              SQLINTEGER FAR   *pcrow);

For 64-bit applications, use the following syntax:

SQLRETURN   SQLRowCount      (SQLHSTMT          hstmt,
                              SQLLEN     FAR   *pcrow);

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. SQLRowCount() arguments
Data type Argument Use Description
SQLHSTMT hstmt input Statement handle
SQLINTEGER *(31-bit) or SQLLEN * (64-bit)1 pcrow output Pointer to location where the number of rows affected is stored.
Notes:
  1. For 64-bit applications, the data type SQLINTEGER, which was used in previous versions of Db2, is still valid. However, for maximum application portability, using SQLLEN is recommended.

Usage

If the last executed statement referenced by the input statement handle is not an UPDATE, INSERT, DELETE, or MERGE statement, or if it did not execute successfully, then the function sets the contents of pcrow to -1.

If SQLRowCount() is executed after the SQLExecDirect() or SQLExecute() of an SQL statement other than INSERT, UPDATE, DELETE, or MERGE, it results in return code 0 and pcrow is set to -1.

Any rows in other tables that might be affected by the statement (for example, cascading deletes) are not included in the count.

If SQLRowCount() is executed after a built-in function (for example, SQLTables()), it results in return code -1 and SQLSTATE HY010.

Return codes

After you call SQLRowCount(), it returns one of the following values:
  • SQL_SUCCESS
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

The following table lists each SQLSTATE that this function generates, with a description and explanation for each value.

Table 3. SQLRowCount() SQLSTATEs
SQLSTATE Description Explanation
08S01 Communication link failure. The communication link between the application and data source fails before the function completes.
58004 Unexpected system failure. Unrecoverable system error.
HY001 Memory allocation failure. Db2 ODBC is not able to allocate the required memory to support the execution or the completion of the function.
HY010 Function sequence error. The function is called prior to calling SQLExecute() or SQLExecDirect() for the hstmt.
HY013 Unexpected memory handling error. Db2 ODBC is not able to access the memory that is required to support execution or completion of the function.

Example

Refer to the function SQLDescribeCol() for a related example.