SQLNumParams() - Get number of parameters in an SQL statement

SQLNumParams() returns the number of parameter markers that are in an SQL statement.

ODBC specifications for SQLNumParams()

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

Syntax

SQLRETURN   SQLNumParams     (SQLHSTMT          hstmt,
                              SQLSMALLINT  FAR  *pcpar);

Function arguments

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

Table 2. SQLNumParams() arguments
Data type Argument Use Description
SQLHSTMT hstmt input Specifies a statement handle.
SQLSMALLINT * pcpar output Points to a buffer that returns the number of parameters in the statement.

Usage

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

You can call this function only after you prepare the statement associated with the hstmt argument. If the statement does not contain any parameter markers, the buffer to which the pcpar argument points is set to 0.

Return codes

After you call SQLNumParams(), 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. SQLNumParams() SQLSTATEs
SQLSTATE Description Explanation
08S01 Communication link failure. The communication link between the application and data source fails before the function completes.
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. The pcpar argument specifies a null pointer.
HY010 Function sequence error. This SQLSTATE is returned for one or more of the following reasons:
  • SQLNumParams() is called before SQLPrepare() for the statement to which the hstmt argument refers.
  • SQLNumParams() 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 SQLNativeSql() for a related example on an application that prints a translated vendor escape clause.