Call Level Interface Guide and Reference

SQLDescribeParam - Return Description of a Parameter Marker

Purpose

Specification: DB2 CLI 5.0 ODBC 1.0 ISO CLI

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

Syntax

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

Function Arguments

Table 48. 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.
SQLUINTEGER * 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.
One of the following:

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.

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.
SQLUINTEGER *	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. One of the following: 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, input/output, or 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_STILL_EXECUTING
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 49. 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 DB2 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 was unable to allocate memory required to support execution or completion of the function.
HY008 Operation was cancelled Asynchronous processing was enabled for the StatementHandle. The function was called and, before it completed execution, SQLCancel() was called on the StatementHandle. Then the function was called again on the StatementHandle.
The function was called and, before it completed execution, SQLCancel() was called on the StatementHandle from a different thread in a multithread application.
HY010 Function sequence error. The function was called prior to 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.

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 DB2 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 was unable to allocate memory required to support execution or completion of the function.
HY008	Operation was cancelled	Asynchronous processing was enabled for the `StatementHandle`. The function was called and, before it completed execution, `SQLCancel()` was called on the `StatementHandle`. Then the function was called again on the `StatementHandle`. The function was called and, before it completed execution, `SQLCancel()` was called on the `StatementHandle` from a different thread in a multithread application.
HY010	Function sequence error.	The function was called prior to 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.

Restrictions

None.

Example

See the README file in the sqllib\samples\cli (or sqllib/samples/cli) subdirectory for a list of appropriate samples.

References

[ Top of Page | Previous Page | Next Page ]