SQLDescribeCol

Purpose

SQLDescribeCol() returns the result descriptor information (column name, type, precision) for the indicated column in the result set generated by a SELECT statement.

If the application only needs one attribute of the descriptor information, the SQLColAttributes() function can be used in place of SQLDescribeCol().

Either SQLPrepare() or SQLExecDirect() must be called before calling this function.

This function (or SQLColAttributes()) is typically called before SQLBindCol().

Syntax

SQLRETURN SQLDescribeCol (SQLHSTMT       hstmt,
                          SQLSMALLINT    icol,
                          SQLCHAR        *szColName,
                          SQLSMALLINT    cbColNameMax,
                          SQLSMALLINT    *pcbColName,
                          SQLSMALLINT    *pfSqlType,
                          SQLINTEGER     *pcbColDef,
                          SQLSMALLINT    *pibScale,
                          SQLSMALLINT    *pfNullable);

Function arguments

Table 1. SQLDescribeCol arguments
Data type	Argument	Use	Description
SQLCHAR *	szColName	Output	Pointer to column name buffer.
SQLHSTMT	hstmt	Input	Statement handle.
SQLINTEGER *	pcbColDef	Output	Precision of column as defined in the database. If fSqlType denotes a graphic SQL data type, then this variable indicates the maximum number of double-byte characters the column can hold.
SQLSMALLINT *	pcbColName	Output	Bytes available to return for szColName argument. Truncation of column name (szColName) to cbColNameMax - 1 bytes occurs if pcbColName is greater than or equal to cbColNameMax.
SQLSMALLINT *	pfNullable	Output	Indicates whether NULLS are allowed for this column SQL_NO_NULLS. SQL_NULLABLE.
SQLSMALLINT *	pfSqlType	Output	SQL data type of column.
SQLSMALLINT *	pibScale	Output	Scale of column as defined in the database (only applies to SQL_DECIMAL, SQL_NUMERIC, SQL_TIMESTAMP).
SQLSMALLINT	cbColNameMax	Input	Size of szColName buffer.
SQLSMALLINT	icol	Input	Column number to be described.

Usage

Columns are identified by a number and are numbered sequentially from left to right starting with 1, and can be described in any order.

A valid pointer and buffer space must be made available for the szColName argument. If a null pointer is specified for any of the remaining pointer arguments, DB2^® UDB CLI assumes that the information is not needed by the application and nothing is returned.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

If SQLDescribeCol() returns either SQL_ERROR, or SQL_SUCCESS_WITH_INFO, one of the following SQLSTATEs can be obtained by calling the SQLError() function.

Table 2. SQLDescribeCol SQLSTATEs
SQLSTATE	Description	Explanation
01004	Data truncated	The column name returned in the argument szColName is longer than the value specified in the argument cbColNameMax. The argument pcbColName contains the length of the full column name. (Function returns SQL_SUCCESS_WITH_INFO.)
07005 *	Not a SELECT statement	The statement associated with the hstmt did not return a result set. There were no columns to describe. (Call `SQLNumResultCols()` first to determine if there are any rows in the result set.)
07009	Column number that is not valid	The value specified for the argument icol is less than 1. The value specified for the argument icol is greater than the number of columns in the result set.
40003 *	Statement completion unknown	The communication link between the CLI and the data source fails before the function completes processing.
58004	System error	Unrecoverable system error.
HY001	Memory allocation failure	The driver is unable to allocate memory required to support the processing or completion of the function.
HY009	Argument value that is not valid	The length specified in argument cbColNameMax is less than 1. The argument szColName or pcbColName is a null pointer.
HY010	Function sequence error	The function is called before calling `SQLPrepare()` or `SQLExecDirect()` for the hstmt.
HY013 *	Memory management problem	The driver is unable to access memory required to support the processing or completion of the function.
HYC00	Driver not capable	The SQL data type of column icol is not recognized by DB2 UDB CLI.

SQLDescribeCol - Describe column attributes