SQLDescribeParam - Return description of a parameter marker

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.

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.
SQLSMALLINT	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.
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 *	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 implementation parameter descriptor. 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.

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

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

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® for i 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 for i CLI is unable to allocate memory required to support the processing or completion of the function.
HY008	Operation canceled.
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.