SQLDescribeCol function (CLI) - Return a set of attributes for a column

Returns a set of commonly used descriptor information (column name, type, precision, scale, nullability) for the indicated column in the result set generated by a query.

Specification:

CLI 1.1
ODBC 1.0
ISO CLI

This information is also available in the fields of the IRD.

If the application needs only one attribute of the descriptor information, or needs an attribute not returned by SQLDescribeCol(), the SQLColAttribute() function can be used in place of SQLDescribeCol().

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

This function (or SQLColAttribute()) is usually called before a bind column function (SQLBindCol(), SQLBindFileToCol()) to determine the attributes of a column before binding it to an application variable.

Unicode equivalent: This function can also be used with the Unicode character set. The corresponding Unicode function is SQLDescribeColW(). See Unicode functions (CLI) for information about ANSI to Unicode function mappings.

Syntax

SQLRETURN   SQLDescribeCol (
               SQLHSTMT          StatementHandle,    /* hstmt */
               SQLUSMALLINT      ColumnNumber,       /* icol */
               SQLCHAR           *ColumnName,        /* szColName */
               SQLSMALLINT       BufferLength,       /* cbColNameMax */
               SQLSMALLINT       *NameLengthPtr,     /* pcbColName */
               SQLSMALLINT       *DataTypePtr,       /* pfSqlType */
               SQLULEN           *ColumnSizePtr,     /* pcbColDef */
               SQLSMALLINT       *DecimalDigitsPtr,  /* pibScale */
               SQLSMALLINT       *NullablePtr);      /* pfNullable */

Function arguments

Table 1. SQLDescribeCol arguments
Data type	Argument	Use	Description
SQLHSTMT	StatementHandle	input	Statement handle
SQLUSMALLINT	ColumnNumber	input	Column number to be described. Columns are numbered sequentially from left to right, starting at 1. This can also be set to 0 to describe the bookmark column.
SQLCHAR *	ColumnName	output	Pointer to column name buffer. This value is read from the SQL_DESC_NAME field of the IRD. This is set to NULL if the column name cannot be determined.
SQLSMALLINT	BufferLength	input	Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) needed to store the * ColumnName buffer.
SQLSMALLINT *	NameLengthPtr	output	Pointer to a buffer in which to return the total number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function), excluding the null-termination character, available to return in * ColumnName. Truncation of column name (* ColumnName) to BufferLength - 1 SQLCHAR or SQLWCHAR elements occurs if NameLengthPtr is greater than or equal to BufferLength.
SQLSMALLINT *	DataTypePtr	output	Base SQL data type of column. To determine if there is a User Defined Type associated with the column, call SQLColAttribute() with fDescType set to SQL_COLUMN_DISTINCT_TYPE. Refer to the Symbolic SQL Data Type column of the symbolic and default data types table for the data types that are supported.
SQLULEN *	ColumnSizePtr	output	Precision of column as defined in the database. If fSqlType denotes a graphic or DBCLOB SQL data type, then this variable indicates the maximum number of double-byte characters the column can hold.
SQLSMALLINT *	DecimalDigitsPtr	output	Scale of column as defined in the database (only applies to SQL_DECIMAL, SQL_NUMERIC, SQL_TYPE_TIMESTAMP). Refer to the data type scale table for the scale of each of the SQL data types.
SQLSMALLINT *	NullablePtr	output	Indicates whether NULLS are allowed for this column SQL_NO_NULLS SQL_NULLABLE

Usage

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

Column numbers start at 1 if bookmarks are not used (SQL_ATTR_USE_BOOKMARKS statement attribute set to SQL_UB_OFF).
The ColumnNumber argument can be set to 0 to describe the bookmark column if bookmarks are used (the statement attribute is set to SQL_UB_ON).

If a null pointer is specified for any of the pointer arguments, CLI assumes that the information is not needed by the application and nothing is returned.

If the column is a User Defined Type, SQLDescribeCol() only returns the built-in type in DataTypePtr. Call SQLColAttribute() with fDescType set to SQL_COLUMN_DISTINCT_TYPE to obtain the User Defined Type.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_STILL_EXECUTING
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 SQLGetDiagRec() or SQLGetDiagField() function.

Table 2. SQLDescribeCol SQLSTATEs
SQLSTATE	Description	Explanation
01004	Data truncated.	The column name returned in the argument * ColumnName was longer than the value specified in the argument BufferLength. The argument * NameLengthPtr contains the length of the full column name. (Function returns SQL_SUCCESS_WITH_INFO.)
07005	The statement did not return a result set.	The statement associated with the StatementHandle 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	Invalid descriptor index	The value specified for ColumnNumber was equal to 0, and the SQL_ATTR_USE_BOOKMARKS statement attribute was SQL_UB_OFF. The value specified for the argument ColumnNumber was greater than the number of columns in the result set.
40003 08S01	Communication link failure.	The communication link between the application and data source failed before the function completed.
58004	Unexpected system failure.	Unrecoverable system error.
HY001	Memory allocation failure.	Db2® CLI is unable to allocate memory required to support execution or completion of the function. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations.
HY008	Operation was Canceled.	Asynchronous processing was enabled for StatementHandle. The function was called and before it completed execution, `SQLCancel()` was called on StatementHandle from a different thread in a multithreaded application. Then the function was called again on StatementHandle.
HY010	Function sequence error.	The function was called before calling SQLPrepare() or SQLExecDirect() for the StatementHandle. The function was called while in a data-at-execute (SQLParamData(), SQLPutData()) operation. The function was called while within a BEGIN COMPOUND and END COMPOUND SQL operation.
HY013	Unexpected memory handling error.	Db2 CLI was unable to access memory required to support execution or completion of the function.
HY090	Invalid string or buffer length.	The length specified in argument BufferLength less than 1.
HYC00	Driver not capable.	The SQL data type of column ColumnNumber is not recognized by CLI.
HYT00	Timeout expired.	The timeout period expired before the data source returned the result set. The timeout period can be set using the SQL_ATTR_QUERY_TIMEOUT attribute for `SQLSetStmtAttr()`. Note: This SQLSTATE applies only to .Net applications.

Restrictions

The following ODBC defined data types are not supported:

SQL_BIT
SQL_TINYINT

Example

    /* return a set of attributes for a column */
    cliRC = SQLDescribeCol(hstmt,
                           (SQLSMALLINT)(i + 1),
                           colName,
                           sizeof(colName),
                           &colNameLen,
                           &colType,
                           &colSize,
                           &colScale,
                           NULL);