SQLColAttribute

You can use SQLColAttribute to retrieve an attribute of a result set column for either prepared or executed ODBC statements. Calling SQLColAttribute on prepared statements causes a roundtrip to SQL Server. The SQL Server Native Client ODBC driver receives result set column data as part of statement execution, so calling SQLColAttribute after the completion of SQLExecute or SQLExecDirect does not involve a server roundtrip.

Note

ODBC column identifier attributes are not available on all SQL Server result sets.

Field identifier	Description
SQL_COLUMN_TABLE_NAME	Available on result sets retrieved from statements that generate server cursors or on executed SELECT statements containing a FOR BROWSE clause.
SQL_DESC_BASE_COLUMN_NAME	Available on result sets retrieved from statements that generate server cursors or on executed SELECT statements containing a FOR BROWSE clause.
SQL_DESC_BASE_TABLE_NAME	Available on result sets retrieved from statements that generate server cursors or on executed SELECT statements containing a FOR BROWSE clause.
SQL_DESC_CATALOG_NAME	Database name. Available on result sets retrieved from statements that generate server cursors or on executed SELECT statements containing a FOR BROWSE clause.
SQL_DESC_LABEL	Available on all result sets. The value is identical to the value of the SQL_DESC_NAME field. The field is zero length only if a column is the result of an expression and the expression does not contain a label assignment.
SQL_DESC_NAME	Available on all result sets. The value is identical to the value of the SQL_DESC_LABEL field. The field is zero length only if a column is the result of an expression and the expression does not contain a label assignment.
SQL_DESC_SCHEMA_NAME	Owner name. Available on result sets retrieved from statements that generate server cursors or on executed SELECT statements containing a FOR BROWSE clause. Available only if the owner name is specified for the column in the SELECT statement.
SQL_DESC_TABLE_NAME	Available on result sets retrieved from statements that generate server cursors or on executed SELECT statements containing a FOR BROWSE clause.
SQL_DESC_UNNAMED	SQL_NAMED for all columns in a result set unless a column is the result of an expression that does not contain a label assignment as part of the expression. When SQL_DESC_UNNAMED returns SQL_UNNAMED, all ODBC column identifier attributes contain zero length strings for the column.

SQL Server Native Client ODBC driver uses the SET FMTONLY statement to reduce server overhead when SQLColAttribute is called for prepared but unexecuted statements.

For large value types, SQLColAttribute will return the following values:

Field identifier	Description of change
SQL_DESC_DISPLAY_SIZE	This is the maximum number of characters required to display data from the column. For large value type columns, the value returned is SQL_SS_LENGTH_UNLIMITED.
SQL_DESC_LENGTH	Returns the actual length of the column in the result set. For large value type columns, the value returned is SQL_SS_LENGTH_UNLIMITED.
SQL_DESC_OCTET_LENGTH	Returns the maximum length of a large value type column. SQL_SS_LENGTH_UNLIMITED is used to indicate unlimited size.
SQL_DESC_PRECISION	Returns the value SQL_SS_LENGTH_UNLIMITED for large value type columns.
SQL_DESC_TYPE	Returns SQL_VARCHAR, SQL_WVARCHAR, and SQL_VARBINARY for large value types.
SQL_DESC_TYPE_NAME	Returns "varchar", "varbinary", "nvarchar" for the large value types.

For all versions, column attributes are reported for only the first result set when multiple result sets are generated by a prepared batch of SQL statements.

The following column attributes are extensions exposed by the SQL Server Native Client ODBC driver. The SQL Server Native Client ODBC driver returns all values in the NumericAttrPtr parameter. The values are returned as SDWORD (signed long) except SQL_CA_SS_COMPUTE_BYLIST, which is a pointer to a WORD array.

Field identifier	Value returned
SQL_CA_SS_COLUMN_HIDDEN*	TRUE if the column referenced is part of a hidden primary key created to support a Transact-SQL SELECT statement containing FOR BROWSE.
SQL_CA_SS_COLUMN_ID	Ordinal position of a COMPUTE clause result column within the current Transact-SQL SELECT statement.
SQL_CA_SS_COLUMN_KEY*	TRUE if the column referenced is part of a primary key for the row and the Transact-SQL SELECT statement contains FOR BROWSE.
SQL_CA_SS_COLUMN_OP	Integer specifying the aggregate operator responsible for the value in a COMPUTE clause column. Definitions of the integer values are in sqlncli.h.
SQL_CA_SS_COLUMN_ORDER	Ordinal position of the column within an ODBC or Transact-SQL SELECT statement's ORDER BY clause.
SQL_CA_SS_COLUMN_SIZE	Maximum length, in bytes, required to bind a data value retrieved from the column to a SQL_C_BINARY variable.
SQL_CA_SS_COLUMN_SSTYPE	Native data type of data stored in the SQL Server column. Definitions of the type values are in sqlncli.h.
SQL_CA_SS_COLUMN_UTYPE	Base data type of the SQL Server column's user-defined data type. Definitions of the type values are in sqlncli.h.
SQL_CA_SS_COLUMN_VARYLEN	TRUE if the column's data can vary in length, FALSE otherwise.
SQL_CA_SS_COMPUTE_BYLIST	Pointer to an array of WORD (unsigned short) specifying the columns used in the BY phrase of a COMPUTE clause. If the COMPUTE clause does not specify a BY phrase, a NULL pointer is returned. The first element of the array contains the count of BY list columns. Additional elements are the column ordinals.
SQL_CA_SS_COMPUTE_ID	computeid of a row that is the result of a COMPUTE clause in the current Transact-SQL SELECT statement.
SQL_CA_SS_NUM_COMPUTES	Number of COMPUTE clauses specified in the current Transact-SQL SELECT statement.
SQL_CA_SS_NUM_ORDERS	Number of columns specified in an ODBC or Transact-SQL SELECT statement's ORDER BY clause.

*   Available if statement attribute SQL_SOPT_SS_HIDDEN_COLUMNS is set to SQL_HC_ON.

SQL Server 2005 introduced driver-specific descriptor fields to provide additional information to denote the XML schema collection name, the schema name, and the catalog name, respectively. These properties do not require quotation marks or an escape character if they contain non-alphanumeric characters. The following table lists these new descriptor fields:

Column name	Type	Description
SQL_CA_SS_XML_SCHEMACOLLECTION_CATALOG_NAME	CharacterAttributePtr	The name of the catalog where an XML schema collection name is defined. If the catalog name cannot be found, then this variable contains an empty string. This information is returned from the SQL_DESC_SS_XML_SCHEMACOLLECTION_CATALOG_NAME record field of the IRD, which is a read-write field.
SQL_CA_SS_XML_SCHEMACOLLECTION_SCHEMA_NAM E	CharacterAttributePtr	The name of the schema where an XML schema collection name is defined. If the schema name cannot be found, then this variable contains an empty string. This information is returned from the SQL_DESC_SS_XML_SCHEMACOLLECTION_SCHEMA_NAME record field of the IRD, which is a read-write field.
SQL_CA_SS_XML_SCHEMACOLLECTION_NAME	CharacterAttributePtr	The name of an XML schema collection. If the name cannot be found, then this variable contains an empty string. This information is returned from the SQL_DESC_SS_XML_SCHEMACOLLECTION_NAME record field of the IRD, which is a read-write field.

Also, SQL Server 2005 introduced new driver-specific descriptor fields to provide additional information for either a user-defined type (UDT) column of a result set or a UDT parameter of a stored procedure or parameterized query. These properties do not require quotation marks or an escape character if they contain non-alphanumeric characters. The following table lists these new descriptor fields:

Column Name	Type	Description
SQL_CA_SS_UDT_CATALOG_NAME	CharacterAttributePtr	The name of the catalog containing the UDT.
SQL_CA_SS_UDT_SCHEMA_NAME	CharacterAttributePtr	The name of the schema containing the UDT.
SQL_CA_SS_UDT_TYPE_NAME	CharacterAttributePtr	The name of the UDT.
SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME	CharacterAttributePtr	The assembly qualified name of the UDT.

The existing descriptor field identifier SQL_DESC_TYPE_NAME is used to indicate the name of the UDT. The SQL_DESC_TYPE field for a UDT type column is SQL_SS_UDT.

SQLColAttribute Support for Enhanced Date and Time Features

For the values returned for date/time types, see the "Information Returned in IRD Fields" section in Parameter and Result Metadata.

For more information, see Date/Time Improvements (ODBC).

SQLColAttribute Support for Large CLR UDTs

SQLColAttribute supports large CLR user-defined types (UDTs). For more information, see Large CLR User-Defined Types (ODBC).

SQLColAttribute Support for Sparse Columns

SQLColAttribute queries the new implementation row descriptor (IRD) field, SQL_CA_SS_IS_COLUMN_SET, to determine if a column is a column_set column.

For more information, see Sparse Columns Support (ODBC).

See Also

Concepts

ODBC API Implementation Details

SQLSetStmtAttr

Other Resources

SQLColAttribute Function