DB2 Version 9.7 for Linux, UNIX, and Windows

SQLRowCount function (CLI) - Get row count

Purpose

Specification:

CLI 1.1

ODBC 1.0

ISO CLI

SQLRowCount() returns the number of rows in a table that were affected by an UPDATE, an INSERT, a DELETE, or a MERGE statement issued against the table, or a view based on the table.

You must call SQLExecute() or SQLExecDirect() before calling SQLRowCount().

Syntax

SQLRETURN   SQLRowCount (
               SQLHSTMT     StatementHandle,   /* hstmt */
               SQLLEN       *RowCountPtr);     /* pcrow */

Function arguments

Table 1. SQLRowCount arguments
Data type	Argument	Use	Description
SQLHSTMT	`StatementHandle`	input	Statement handle
SQLLEN *	`RowCountPtr`	output	Pointer to location where the number of rows affected is stored. If the SQL_ATTR_PARC_BATCH connection attribute is set to SQL_PARC_BATCH_ENABLE, the location size must be the size of an array. See the Usage section for details.

Usage

If the last issued statement referenced by the input statement handle was not an UPDATE, an INSERT, a DELETE, or a MERGE statement or if the statement did not run successfully, the function sets the contents of StatementHandle to -1.

If you use the SQLRowCount() function on a non-scrollable SELECT-only cursor, the function sets the contents of RowCountPtr to -1. The number of rows is not available until all of the data has been fetched. You can use the CLI statement attribute SQL_ATTR_ROWCOUNT_PREFETCH to enable the client to request the full row count before fetching the data.

Restriction: The SQL_ATTR_ROWCOUNT_PREFETCH attribute is not supported when the cursor contains LOBs or XML.

If the SQL_ATTR_PARC_BATCH connection attribute is set to SQL_PARC_BATCH_ENABLE, then the SQL_ATTR_PARAMOPT_ATOMIC attribute must be set to SQL_ATOMIC_NO and the RowCountPtr argument must be pointing to an array of type SQLLEN *. The length of this array must be equal to SQL_ATTR_PARAMSET_SIZE. Upon successful execution of non-atomic update, delete or insert operations, the number of rows in a table that were affected by each parameter set is stored in this array.

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

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 2. SQLRowCount SQLSTATEs
SQLSTATE	Description	Explanation
40003 08S01	Communication link failure.	The communication link between the application and data source failed before the function completed.
58004	Unexpected system failure.	Unrecoverable system error.
HY001	Memory allocation failure.	DB2® CLI is unable to allocate memory required to support execution or completion of the function. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information on process-level memory limitations.
HY010	Function sequence error.	The function was called before calling SQLExecute() or SQLExecDirect() for the `StatementHandle`.
HY013	Unexpected memory handling error.	DB2 CLI was unable to access memory required to support execution or completion of the function.

Authorization

None.