SQLNumResultCols() - Get number of result columns

SQLNumResultCols() returns the number of columns in the result set that is associated with the input statement handle. SQLPrepare() or SQLExecDirect() must be called before you call SQLNumResultCols(). After you call SQLNumResultCols(), you can call SQLColAttribute() or one of the bind column functions.

ODBC specifications for SQLNumResultCols()

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

Syntax

SQLRETURN   SQLNumResultCols (SQLHSTMT          hstmt,
                              SQLSMALLINT FAR   *pccol);

Function arguments

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

Table 2. SQLNumResultCols() arguments
Data type Argument Use Description
SQLHSTMT hstmt input Specifies a statement handle.
SQLSMALLINT * pccol output Points to a buffer that returns the number of columns in the result set.

Usage

You call this function to determine how many SQLBindCol() or SQLGetData() calls are necessary for the SQL result set that is associated with a statement handle.

The function sets the output argument to zero if the last statement or function executed on the input statement handle did not generate a result set.

Return codes

After you call SQLNumResultCols(), 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. SQLNumResultCols() 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.
HY009 Invalid use of a null pointer. pccol is a null pointer.
HY010 Function sequence error. This SQLSTATE is returned for one or more of the following reasons:
  • The function is called prior to calling SQLPrepare() or SQLExecDirect() for the hstmt.
  • The function is called during a data-at-execute operation. (That is, the function is called during a procedure that uses the SQLParamData() or SQLPutData() functions.)
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.