MDAC 2.5 SDK - ODBC Programmer's Reference
Chapter 21: ODBC API Reference

SQLDescribeCol

Conformance

Version Introduced: ODBC 1.0
Standards Compliance: ISO 92

Summary

SQLDescribeCol returns the result descriptor—column name, type, column size, decimal digits, and nullability—for one column in the result set. This information also is available in the fields of the IRD.

Syntax

SQLRETURN SQLDescribeCol(
     SQLHSTMT     StatementHandle,
     SQLSMALLINT     ColumnNumber,
     SQLCHAR *     ColumnName,
     SQLSMALLINT     BufferLength,
     SQLSMALLINT *     NameLengthPtr,
     SQLSMALLINT *     DataTypePtr,
     SQLUINTEGER *     ColumnSizePtr,
     SQLSMALLINT *     DecimalDigitsPtr,
     SQLSMALLINT *     NullablePtr);

Arguments

StatementHandle

[Input]
Statement handle.

ColumnNumber

[Input]
Column number of result data, ordered sequentially in increasing column order, starting at 1. The ColumnNumber argument can also be set to 0 to describe the bookmark column.

ColumnName

[Output]
Pointer to a buffer in which to return the column name. This value is read from the SQL_DESC_NAME field of the IRD. If the column is unnamed or the column name cannot be determined, the driver returns an empty string.

BufferLength

[Input]
Length of the *ColumnName buffer, in characters.

NameLengthPtr

[Output]
Pointer to a buffer in which to return the total number of bytes (excluding the null-termination byte) available to return in *ColumnName. If the number of bytes available to return is greater than or equal to BufferLength, the column name in *ColumnName is truncated to BufferLength minus the length of a null-termination character.

DataTypePtr

[Output]
Pointer to a buffer in which to return the SQL data type of the column. This value is read from the SQL_DESC_CONCISE_TYPE field of the IRD. This will be one of the values in the "SQL Data Types" section of Appendix D, "Data Types," or a driver-specific SQL data type. If the data type cannot be determined, the driver returns SQL_UNKNOWN_TYPE.

In ODBC 3.x, SQL_TYPE_DATE, SQL_TYPE_TIME, or SQL_TYPE_TIMESTAMP is returned in *DataTypePtr for date, time, or timestamp data, respectively; in ODBC 2.x, SQL_DATE, SQL_TIME, or SQL_TIMESTAMP is returned. The Driver Manager performs the required mappings when an ODBC 2.x application is working with an ODBC 3.x driver or when an ODBC 3.x application is working with an ODBC 2.x driver.

When ColumnNumber is equal to 0 (for a bookmark column), SQL_BINARY is returned in *DataTypePtr for variable-length bookmarks. (SQL_INTEGER is returned if bookmarks are used by an ODBC 3.x application working with an ODBC 2.x driver or by an ODBC 2.x application working with an ODBC 3.x driver.)

For more information on these data types, see "SQL Data Types" in Appendix D, "Data Types." For information about driver-specific SQL data types, see the driver's documentation.

ColumnSizePtr

[Output]
Pointer to a buffer in which to return the size of the column on the data source. If the column size cannot be determined, the driver returns 0. For more information on column size, see "Column Size, Decimal Digits, Transfer Octet Length, and Display Size" in Appendix D, "Data Types."

DecimalDigitsPtr

[Output]
Pointer to a buffer in which to return the number of decimal digits of the column on the data source. If the number of decimal digits cannot be determined or is not applicable, the driver returns 0. For more information on decimal digits, see "Column Size, Decimal Digits, Transfer Octet Length, and Display Size" in Appendix D, "Data Types."

NullablePtr

[Output]
Pointer to a buffer in which to return a value that indicates whether the column allows NULL values. This value is read from the SQL_DESC_NULLABLE field of the IRD. The value is one of the following:

SQL_NO_NULLS: The column does not allow NULL values.

SQL_NULLABLE: The column allows NULL values.

SQL_NULLABLE_UNKNOWN: The driver cannot determine if the column allows NULL values.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

When SQLDescribeCol returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_STMT and a Handle of StatementHandle. The following table lists the SQLSTATE values commonly returned by SQLDescribeCol and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

SQLDescribeCol can return any SQLSTATE that can be returned by SQLPrepare or SQLExecute when called after SQLPrepare and before SQLExecute, depending on when the data source evaluates the SQL statement associated with the statement handle.

For performance reasons, an application should not call SQLDescribeCol before executing a statement.

Comments

An application typically calls SQLDescribeCol after a call to SQLPrepare and before or after the associated call to SQLExecute. An application can also call SQLDescribeCol after a call to SQLExecDirect. For more information, see "Result Set Metadata" in Chapter 10, "Retrieving Results (Basic)."

SQLDescribeCol retrieves the column name, type, and length generated by a SELECT statement. If the column is an expression, *ColumnName is either an empty string or a driver-defined name.

Note   ODBC supports SQL_NULLABLE_UNKNOWN as an extension, even though the X/Open and SQL Access Group Call Level Interface specification does not specify the option for SQLDescribeCol.

Related Functions