SQLDescribeParam function (CLI) - Return description of a parameter marker

Returns the description of a parameter marker associated with a prepared SQL statement.

Specification:

  • CLI 5.0
  • ODBC 1.0
  • ISO CLI

The description of a parameter marker is also available in the fields of the IPD.

If deferred prepared is enabled, and this is the first call to SQLDescribeParam(), SQLNumResultCols(), or SQLDescribeCol(), the call will force a PREPARE of the SQL statement to be flowed to the server.

Syntax

SQLRETURN   SQLDescribeParam (
               SQLHSTMT          StatementHandle,     /* hstmt */
               SQLUSMALLINT      ParameterNumber,     /* ipar */
               SQLSMALLINT       *DataTypePtr,        /* pfSqlType */
               SQLULEN           *ParameterSizePtr,   /* pcbParamDef */
               SQLSMALLINT       *DecimalDigitsPtr,   /* pibScale */
               SQLSMALLINT       *NullablePtr);       /* pfNullable */

Function arguments

Table 1. SQLDescribeParam arguments
Data type Argument Use Description
SQLHSTMT StatementHandle input Statement handle.
SQLUSMALLINT ParameterNumber input Parameter marker number ordered sequentially in increasing parameter order, starting at 1.
SQLSMALLINT * DataTypePtr output Pointer to a buffer in which to return the SQL data type of the parameter. This value is read from the SQL_DESC_CONCISE_TYPE record field of the IPD.

When ColumnNumber is equal to 0 (for a bookmark column), SQL_BINARY is returned in *DataTypePtr for variable-length bookmarks.
SQLULEN * ParameterSizePtr output Pointer to a buffer in which to return the size of the column or expression of the corresponding parameter marker as defined by the data source.
SQLSMALLINT * DecimalDigitsPtr output Pointer to a buffer in which to return the number of decimal digits of the column or expression of the corresponding parameter as defined by the data source.
SQLSMALLINT * NullablePtr output Pointer to a buffer in which to return a value that indicates whether the parameter allows NULL values. This value is read from the SQL_DESC_NULLABLE field of the IPD.
The ODBC specification lists following returned values. However, the CLI driver only returns SQL_NULLABLE_UNKNOWN return value.
  • SQL_NO_NULLS: The parameter does not allow NULL values (this is the default value).
  • SQL_NULLABLE: The parameter allows NULL values.
  • SQL_NULLABLE_UNKNOWN: Cannot determine if the parameter allows NULL values.
Note: The CLI driver returns SQL_NULLABLE_UNKNOWN.

Usage

Parameter markers are numbered in increasing order as they appear in the SQL statement, starting with 1.

SQLDescribeParam() does not return the type (input, input/output, or output) of a parameter in an SQL statement. Except in calls to stored procedures, all parameters in SQL statements are input parameters. To determine the type of each parameter in a call to a stored procedure, call SQLProcedureColumns().

Return codes

  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_STILL_EXECUTING
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

Table 2. SQLDescribeParam SQLSTATEs
SQLSTATE Description Explanation
01000 Warning. Informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
07009 Invalid descriptor index. The value specified for the argument ParameterNumber less than 1.

The value specified for the argument ParameterNumber was greater than the number of parameters in the associated SQL statement.

The parameter marker was part of a non-DML statement.

The parameter marker was part of a SELECT list.
08S01 Communication link failure. The communication link between CLI and the data source to which it was connected failed before the function completed processing.
21S01 Insert value list does not match column list. The number of parameters in the INSERT statement did not match the number of columns in the table named in the statement.
HY000 General error. An error occurred for which there was no specific SQLSTATE. The error message returned by SQLGetDiagRec() in the *MessageText buffer describes the error and its cause.
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 about process-level memory limitations.
HY008 Operation was Canceled. Asynchronous processing was enabled for StatementHandle. The function was called and before it completed execution, SQLCancel() was called on StatementHandle from a different thread in a multithreaded application. Then the function was called again on StatementHandle.
HY010 Function sequence error. The function was called before calling SQLPrepare() or SQLExecDirect() for the StatementHandle.

An asynchronously executing function (not this one) was called for the StatementHandle and was still executing when this function was called.

SQLExecute() SQLExecDirect(), SQLBulkOperations(), or SQLSetPos() was called for the StatementHandle and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns.
HY013 Unexpected memory handling error. The function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions.
HYC00 Driver not capable. The schema function stored procedures are not accessible on the server. Install the schema function stored procedures on the server and ensure they are accessible.

Restrictions

None.