SQLDescribeParam() - Describe parameter marker

SQLDescribeParam() retrieves the description of a parameter marker that is associated with a prepared statement. This function is supported only for Db2 for z/OS® data sources. Before you call this function, you must call either SQLPrepare() or SQLExecDirect().

ODBC specifications for SQLDescribeParam()

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

Syntax

For 31-bit applications, use the following syntax:

SQLRETURN  SQLDescribeParam  (SQLHSTMT          hstmt,
                              SQLUSMALLINT      ipar,
                              SQLSMALLINT FAR     *pfSqlType,
                              SQLUINTEGER FAR     *pcbColDef,
                              SQLSMALLINT FAR     *pibScale,
                              SQLSMALLINT FAR     *pfNullable);

For 64-bit applications, use the following syntax:

SQLRETURN  SQLDescribeParam  (SQLHSTMT          hstmt,
                              SQLUSMALLINT      ipar,
                              SQLSMALLINT FAR     *pfSqlType,
                              SQLULEN     FAR     *pcbColDef,
                              SQLSMALLINT FAR     *pibScale,
                              SQLSMALLINT FAR     *pfNullable);

Function arguments

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

Table 2. SQLDescribeParam() arguments
Data type Argument Use Description
SQLHSTMT hstmt input Specifies a statement handle.
SQLUSMALLINT ipar input Specifies the parameter marker number. (Parameters are ordered sequentially from left to right in a prepared SQL statement, starting at 1.)
SQLSMALLINT * pfSqlType output Specifies the base SQL data type.
SQLUINTEGER * (31-bit) or SQLULEN *(64-bit) 1 pcbColDef output Returns the precision of the parameter marker.
SQLSMALLINT * pibScale output Returns the scale of the parameter marker.
SQLSMALLINT * pfNullable output Indicates whether the parameter allows null values. This argument returns one of the following values:
  • SQL_NO_NULLS: The parameter does not allow null values; this is the default.
  • SQL_NULLABLE: The parameter allows null values.
  • SQL_NULLABLE_UNKNOWN: The driver cannot determine whether the parameter allows null values.
Notes:
  1. For 64-bit applications, the data type SQLUINTEGER, which was used in previous versions of Db2, is still valid. However, for maximum application portability, using SQLULEN is recommended.

Usage

For distinct types, SQLDescribeParam() returns both base data types for the input parameter.

SQLDescribeParam() does not return an indication of whether a parameter in an SQL statement is for input, input/output, or output. 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

After you call SQLDescribeParam(), it returns one of the following values:
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE
  • SQL_NO_DATA_FOUND

Diagnostics

The following table lists each SQLSTATE that this function generates, with a description and explanation for each value.

Table 3. SQLDescribeParam() SQLSTATEs
SQLSTATE Description Explanation
01000 Warning. Informational message that indicates an internal commit is issued on behalf of the application as part of the processing that sets the specified connection attribute.
HY000 General error. An error occurred for which no specific SQLSTATE is defined. The error message that is returned by SQLGetDiagRec() in the argument MessageText describes the error and its cause.
HY001 Memory allocation failure. Db2 ODBC is not able to allocate the required memory to support the execution or the completion of the function.
HY010 Function sequence error. The function is called during a data-at-execute operation. (That is, the function is called during a procedure that uses the SQLParamData() or SQLPutData() functions.)
HY093 Invalid parameter number. The specified value for the ipar argument is less than 1 or it is greater than the number of parameters that the associated SQL statement requires.
HYC00 Driver not capable. The data source is not Db2 for z/OS or Db2 for Linux®, UNIX, and Windows.