DB2 10.5 for Linux, UNIX, and Windows
DB2 10.5 for Linux, UNIX, and Windows
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.
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.
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 */| 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
|
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.
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.
| 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(). |
/* return a set of attributes for a column */
cliRC = SQLDescribeCol(hstmt,
(SQLSMALLINT)(i + 1),
colName,
sizeof(colName),
&colNameLen,
&colType,
&colSize,
&colScale,
NULL);