SQLDescribeParam - Return description of a parameter marker

Purpose

SQLDescribeParam() returns the description of a parameter marker associated with a prepared SQL statement. This information is also available in the fields of the implementation parameter descriptor (IPD).

Syntax

SQLRETURN   SQLDescribeParam (SQLHSTMT          StatementHandle,
                              SQLSMALLINT       ParameterNumber,
                              SQLSMALLINT       *DataTypePtr,
                              SQLINTEGER        *ParameterSizePtr,
                              SQLSMALLINT       *DecimalDigitsPtr,
                              SQLSMALLINT       *NullablePtr);

Function arguments

Table 1. SQLDescribeParam arguments
Data type Argument Use Description
SQLHSTMT StatementHandle Input Statement handle.
SQLINTEGER * 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 * DataTypePtr Output Pointer to a buffer in which to return the SQL data type of the parameter.
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.
  • 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.
SQLSMALLINT ParameterNumber Input Parameter marker number ordered sequentially in increasing parameter order, starting at 1.

Usage

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

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

Return codes

Error conditions

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

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

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

The parameter marker is part of a SELECT list.
08S01 Communication link failure The communication link between DB2® UDB CLI and the data source to which it is connected fails before the function completes processing.
21S01 Insert value list does not match column list The number of parameters in the INSERT statement does not match the number of columns in the table named in the statement.
HY000 General error  
HY001 Memory allocation failure DB2 UDB CLI is unable to allocate memory required to support the processing or completion of the function.
HY008 Operation cancelled.  
HY009 Argument value that is not valid The argument DataTypePtr, ParameterSizePtr, DecimalDigitsPtr, or NullablePtr is a null pointer.
HY010 Function sequence error The function is called before calling SQLPrepare() or SQLExecDirect() for the StatementHandle.
HY013 Unexpected memory handling error The function call cannot be processed because the underlying memory objects can not be accessed, possibly because of low memory conditions.

Restrictions

None.

References

Parent topic: DB2 UDB CLI functions