SQLDescribeCol--Return a set of attributes for a column

Purpose

Specification: DB2 CLI 1.1 ODBC 1.0 ISO CLI

SQLDescribeCol() 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.

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

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

Syntax 

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

Function arguments

Tabulka 38. 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 one.
SQLCHAR * ColumnName output Pointer to column name buffer. This is set to NULL if the column name cannot be determined.
SQLSMALLINT BufferLength input Size of ColumnName buffer.
SQLSMALLINT * NameLengthPtr output Bytes available to return for ColumnName argument. Truncation of column name (ColumnName) to BufferLength - 1 bytes occurs if NameLengthPtr is greater than or equal to BufferLength.
SQLSMALLINT * DataTypePtr output Base SQL data type of column.
SQLUINTEGER * ColumnSizePtr output Precision of column as defined in the database.
SQLSMALLINT * DecimalDigitsPtr output Scale of column as defined in the database (applies only to SQL_DECIMAL).
SQLSMALLINT * NullablePtr output Indicates whether NULLs are allowed for this column. Either:

SQL_NO_NULLS

SQL_NULLABLE

Usage

Columns are identified by a number, are numbered sequentially from left to right, and might be described in any order. Column numbers start at one.

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

Return codes

Diagnostics

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

Tabulka 39. SQLDescribeCol SQLSTATEs

SQLSTATE Description Explanation
01004 Data truncated. The column name returned in the argument ColumnName is 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 is equal to or less than 0. The value specified for the argument ColumnNumber is 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.
HY002 Invalid column number. The value specified for the argument ColumnNumber is less than one, or the value specified for the argument ColumnNumber is greater than the number of columns in the result set.
HY090 Invalid string or buffer length. The length specified in argument BufferLength is less than one.
HY010 Function sequence error. The function is called prior to calling SQLPrepare() or SQLExecDirect() for the StatementHandle.
HY013 Unexpected memory handling error. DB2 CLI is unable to access memory required to support execution or completion of the function.
HYC00 Driver not capable. The SQL data type of column ColumnNumber is not recognized by DB2 CLI.

Restrictions

DB2 Everyplace supports only the following ODBC defined data types:

Související odkazy