SQLDescribeCol and SQLColAttribute

SQLDescribeCol and SQLColAttribute are used to retrieve result set metadata. The difference between these two functions is that SQLDescribeCol always returns the same five pieces of information (a column’s name, data type, precision, scale, and nullability), while SQLColAttribute returns a single piece of information requested by the application. However, SQLColAttribute can return a much richer selection of metadata, including a column’s case sensitivity, display size, updatability, and searchability.

Many applications, especially ones that only display data, only require the metadata returned by SQLDescribeCol. For these applications, it is faster to use SQLDescribeCol than SQLColAttribute because the information is returned in a single call. Other applications, especially ones that update data, require the additional metadata returned by SQLColAttribute and so use both functions. In addition, SQLColAttribute supports driver-specific metadata; for more information, see “Driver-Specific Data Types, Descriptor Types, Information Types, Diagnostic Types, and Attributes” in Chapter 17, “Programming Considerations.”

An application can retrieve result set metadata at any time after a statement has been prepared or executed and before the cursor over the result set is closed. Very few applications require result set metadata after the statement is prepared and before it is executed. If possible, applications should wait to retrieve metadata until after the statement is executed. The reason is that some data sources cannot return metadata for prepared statements and emulating this capability in the driver is often a slow process. For example, the driver might generate a zero row result set by replacing the WHERE clause of a SELECT statement with the clause WHERE 1 = 2 and executing the resulting statement.

Metadata is often expensive to retrieve from the data source. Because of this, drivers should cache any metadata they retrieve from the server and hold it for as long as the cursor over the result set is open. Also, applications should request only the metadata they absolutely need.