IColumnsRowset::GetColumnsRowset

Returns a rowset containing metadata about each column in the current rowset. This rowset is known as the column metadata rowset and is read-only.

HRESULT GetColumnsRowset (
   IUnknown *      pUnkOuter,
   ULONG         cOptColumns,
   const DBID      rgOptColumns[],
   REFIID            riid,
   ULONG         cPropertySets,
   DBPROPSET   rgPropertySets[],
   IUnknown **      ppColRowset);

Parameters

pUnkOuter

[in]
A pointer to the controlling IUnknown interface if the column metadata rowset is being created as part of an aggregate. It is a null pointer if the rowset is not part of an aggregate.

cOptColumns

[in]
The number of the elements in rgOptColumns. If cOptColumns is zero, then rgOptColumns is ignored, and the provider returns all available columns in the columns rowset.

rgOptColumns

[in]
An array that specifies the optional columns to return. In addition to the optional columns listed below, the consumer can request provider-specific columns.

riid

[in]
The IID of the requested rowset interface. This interface is conceptually added to the list of required interfaces on the resulting rowset, and the method fails (E_NOINTERFACE) if that interface cannot be supported on the resulting rowset.

cPropertySets

[in]
The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets.

rgPropertySets

[in/out]
An array of DBPROPSET structures containing properties and values to be set. The properties specified in these structures must belong to the Rowset property group. If the same property is specified more than once in rgPropertySets, then it is provider-specific which value is used. If cPropertySets is zero, this argument is ignored.

For information about the properties in the Rowset property group that are defined by OLE DB, see "Rowset Properties" in Appendix C. For information about the DBPROPSET and DBPROP structures, see "DBPROPSET Structure" and "DBPROP Structure" in Chapter 11.

ppColRowset

[out]
A pointer to memory in which to return the requested interface pointer on the column metadata rowset. If an error occurs, the returned pointer is null. If GetColumnsRowset is called on a command that does not return rows, then the column metadata rowset will be empty.

Return Code

S_OK
The method succeeded. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK.

DB_S_ASYNCHRONOUS
The method has initiated asynchronous creation of the rowset. The consumer can call IDBAsynchStatus to poll for status or IConnectionPointContainer to obtain the IID_IDBAsynchNotify connection point. Attempting to call any other interfaces may fail and the full set of interfaces may not be available on the object until asynchronous initialization of the rowset has completed.

DB_S_ERRORSOCCURRED
The rowset was opened but one or more properties—for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_OPTIONAL—were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. The method can fail to set properties for a number of reasons, including:

The property was not supported by the provider.
The property was not in the Rowset property group.
The property set was not supported by the provider.
It was not possible to set the property.
colid in the DBPROP structure was invalid.
The data type in vValue in the DBPROP structure was not the data type of the property or was not VT_EMPTY.
The value in vValue in the DBPROP structure was invalid.
The property's value conflicted with an existing property.
A property was specified to be applied to all columns, but could not be applied to one or more columns.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
ppColRowset was a null pointer.

cPropertySets was greater than zero and rgPropertySets was a null pointer.

In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer.

cOptColumns was greater than zero and rgOptColumns was a null pointer.

E_NOINTERFACE
The column metadata rowset did not support the interface specified in riid.

E_UNEXPECTED
ITransaction::Commit or ITransaction::Abort was called and the object is in a zombie state. This error can be returned only when the method is called on a rowset.

DB_E_ABORTLIMITREACHED
The method failed because a resource limit has been reached. For example, a query used to implement the method timed out. No rowset is returned.

DB_E_BADCOLUMNID
An element of rgOptColumns was an invalid DBID.

DB_E_ERRORSOCCURRED
No rowset was returned because one or more properties—for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_REQUIRED or an invalid value—were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. None of the satisfiable properties are remembered. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED, except the reason that states that it was not possible to set the property.

DB_E_NOAGGREGATION
pUnkOuter was not a null pointer and the column's rowset does not support aggregation.

pUnkOuter was non-null and riid was not IID_Unknown.

DB_E_NOCOMMAND
No command text was set. This error can be returned only when this method is called from the command object.

DB_E_NOTPREPARED
The command exposed ICommandPrepare and the command text was set, but the command was not prepared. This error can be returned only when this method is called from the command object.

DB_E_NOTREENTRANT
The provider called a method from IRowsetNotify in the consumer and the method has not yet returned.

DB_SEC_E_PERMISSIONDENIED
The consumer did not have sufficient permission to create the column metadata rowset.

Comments

This method makes no logical change to the state of the object.

GetColumnsRowset creates a rowset containing metadata about a rowset. Unlike IColumnsInfo::GetColumnInfo, it provides all of the metadata, but it is more complex to implement and use.

The rows in the column metadata rowset describe the columns in the underlying rowset. The column metadata rowset contains one row for each column in the rowset. This includes the columns of the base table and any pseudo-columns generated by the provider or data source, such as bookmarks and row IDs.

The order of the rows is the order in which the columns appear in the rowset (column ordinal order). This is the same order as they appear in IColumnsInfo. The order is usually predictable from the ordering of requested columns in the command text; if the command text does not specify an order, such as SELECT * FROM MyTable, then the order is determined by the provider, such as when the command is prepared.

Each column in the column metadata rowset describes a single attribute, such as the name or data type, of a column in the original rowset. The order of the required columns is the same as the order in which they are listed below. The order of the optional columns is arbitrary, although they must be after the required columns. That is, the optional columns in the column metadata rowset can occur in any order after the required columns.

The column metadata rowset always includes the required columns. It contains only those optional columns which are requested.

GetColumnsRowset can be called for rowsets created by GetColumnsRowset.

Calling GetColumnsRowset on a command before the command is executed may be an expensive operation.

Required Metadata Columns

The column metadata rowset always contains the following columns; these columns return the same information as GetColumnInfo.

Column ID	Type indicator	Description
DBCOLUMN_IDNAME	DBTYPE_WSTR	Column name. This column, together with the DBCOLUMN_GUID and DBCOLUMN_PROPID columns, form the ID of the column. One or more of these columns will be NULL depending on which elements of the DBID structure the provider uses. The column ID of a base table should be invariant under views.
DBCOLUMN_GUID	DBTYPE_GUID	Column GUID.
DBCOLUMN_PROPID	DBTYPE_UI4	Column property ID.
DBCOLUMN_NAME	DBTYPE_WSTR	The name of the column; this might not be unique. If this cannot be determined, a NULL is returned. The name can be different from the value returned in DBCOLUMN_IDNAME if the column has been renamed by the command text. This name always reflects the most recent renaming of the column in the current view or command text. If GetColumnsRowset is called for a column metadata rowset (the rowset returned by GetColumnsRowset), the name of each column is the name of the column ID constant. For example, the name of the DBCOLUMN_SCALE column is "DBCOLUMN_SCALE".
DBCOLUMN_NUMBER	DBTYPE_UI4	The ordinal of the column. This is zero for the bookmark column of the row, if any. Other columns are numbered starting with one. This column cannot contain a NULL value.
DBCOLUMN_TYPE	DBTYPE_UI2	The indicator of the column's data type. If the data type of the column varies from row to row, this must be DBTYPE_VARIANT. This column cannot contain a NULL value. For a list of valid type indicators, see "Type Indicators" in Appendix A.
DBCOLUMN_TYPEINFO	DBTYPE_ IUNKNOWN	Reserved for future use. Providers should return a null pointer in pTypeInfo.
DBCOLUMN_ COLUMNSIZE	DBTYPE_UI4	The maximum possible length of a value in the column. For columns that use a fixed-length data type, this is the size of the data type. For columns that use a variable-length data type, this is one of the following: The maximum length of the column in characters, for DBTYPE_STR and DBTYPE_WSTR, or bytes, for DBTYPE_BYTES, if one is defined. For example, a CHAR(5) column in an SQL table has a maximum length of 5. The maximum length of the data type in characters, for DBTYPE_STR and DBTYPE_WSTR, or bytes, for DBTYPE_BYTES, if the column does not have a defined length. ~0 (bitwise, the value is not 0; that is, all bits are set to 1) if neither the column nor the data type has a defined maximum length. For data types that do not have a length, this is set to ~0 (bitwise, the value is not 0; that is, all bits are set to 1).
DBCOLUMN_ PRECISION	DBTYPE_UI2	If DBCOLUMN_TYPE is a numeric data type, this is the maximum precision of the column. The precision of columns with a data type of DBTYPE_DECIMAL or DBTYPE_NUMERIC depends on the definition of the column. For the precision of all other numeric data types, see "Precision of Numeric Data Types" in Appendix A. If DBCOLUMN_TYPE is not a numeric data type, this is NULL.
DBCOLUMN_SCALE	DBTYPE_I2	If DBCOLUMN_TYPE is DBTYPE_DECIMAL or DBTYPE_NUMERIC, this is the number of digits to the right of the decimal point. Otherwise, this is NULL.
DBCOLUMN_FLAGS	DBTYPE_UI4	A bitmask that describes column characteristics. The DBCOLUMNFLAGS enumerated type specifies the bits in the bitmask. For more information, see IColumnsInfo::GetColumnInfo. This column cannot contain a NULL value.

Optional Metadata Columns

The following columns are optional; if the column metadata rowset does not contain one of them, the consumer can safely use the default value. The default value is the value the consumer should assume if the provider does not support that information. It is also the value the column metadata rowset returns when the provider does have support, but does not specify that information for a particular column. The provider can also have optional, provider-specific columns.

Column ID	Type indicator	Description
DBCOLUMN_ BASECATALOGNAME	DBTYPE_WSTR	The name of the catalog in the data source that contains the column. NULL if the base catalog name cannot be determined. The default of this column is NULL.
DBCOLUMN_ BASECOLUMNNAME	DBTYPE_WSTR	The name of the column in the data source. This might be different than the column name returned in the DBCOLUMN_NAME column if an alias was used. NULL if the base column name cannot be determined. The default of this column is NULL.
DBCOLUMN_ BASESCHEMANAME	DBTYPE_WSTR	The name of the schema in the data source that contains the column. NULL if the base schema name cannot be determined. The default of this column is NULL.
DBCOLUMN_ BASETABLENAME	DBTYPE_WSTR	The name of the table in the data source that contains the column. NULL if the base table name cannot be determined. The default of this column is NULL.
DBCOLUMN_CLSID	DBTYPE_GUID	If all objects in the column all have the same class ID, this is that class ID. If the column may contain objects with different class IDs, or if the column is not of DBTYPE_IUNKNOWN, this is set to NULL. The default of this column is NULL.
DBCOLUMN_ COLLATINGSEQUENCE	DBTYPE_I4	The locale ID (LCID) that defines the collating sequence for the column. For more information, see the OLE documentation. The default of this column is the code page installed on the local machine.
DBCOLUMN_ COMPUTEMODE	DBTYPE_I4	Whether a column is computed. One of the following: DBCOMPUTEMODE_COMPUTED: The column is computed, such as Salary/12. DBCOMPUTEMODE_DYNAMIC: The column is computed and IRowset::GetData returns the value of the column based on the current values of its component columns, which might have been changed with IRowsetChange::SetData or IRowsetChange::InsertRow. DBCOMPUTEDMODE_NOTCOMPUTED: The column is not computed. This is the default.
DBCOLUMN_ DATETIMEPRECISION	DBTYPE_UI4	The datetime precision—number of digits in the fractional seconds portion—if the column is a datetime or interval type. The default of this column is derived from the value in column DATETIME_PRECISION in the COLUMNS schema rowset.
DBCOLUMN_ DEFAULTVALUE	DBTYPE_ VARIANT	The column default value if declared statically. Dynamic initialization is handled by notifications. NULL if the default value cannot be determined. For a list of possible values, see the COLUMN_DEFAULT in "COLUMNS Rowset" in Appendix B. The default of this column is NULL.
DBCOLUMN_ DOMAINCATALOG	DBTYPE_WSTR	The name of the catalog containing the column's domain. NULL if the domain catalog name cannot be determined. The default of this column is NULL.
DBCOLUMN_ DOMAINSCHEMA	DBTYPE_WSTR	The name of the schema containing the column's domain. NULL if the domain schema name cannot be determined. The default of this column is NULL.
DBCOLUMN_ DOMAINNAME	DBTYPE_WSTR	The name of the domain of which the column is a member. NULL if the domain name cannot be determined. The default of this column is NULL.
DBCOLUMN_ HASDEFAULT	DBTYPE_BOOL	VARIANT_TRUE: The column has a default value. VARIANT_FALSE: The column does not have a default value. NULL: The provider could not determine if the column has a default value or if a default value does not make sense for the column. For example, it is a computed, derived, or nonupdatable column. The default of this column is VARIANT_FALSE.
DBCOLUMN_ ISAUTOINCREMENT	DBTYPE_BOOL	VARIANT_TRUE: The column assigns values to new rows in fixed increments. VARIANT_FALSE: The column does not assign values to new rows in fixed increments. The default of this column is VARIANT_FALSE.
DBCOLUMN_ ISCASESENSITIVE	DBTYPE_BOOL	VARIANT_TRUE if the order of the column is case sensitive and if searches on the column are case sensitive. Otherwise, VARIANT_FALSE. The default of this column is VARIANT_TRUE.
DBCOLUMN_ ISSEARCHABLE	DBTYPE_UI4	An integer indicating the searchability of a column. For more information, see the SEARCHABLE column in "PROVIDER_TYPES Rowset" in Appendix B. The default of this column is derived from the value of the SEARCHABLE column in the PROVIDER_TYPES schema rowset.
DBCOLUMN_ ISUNIQUE	DBTYPE_BOOL	VARIANT_TRUE: No two rows in the base table—the table returned in DBCOLUMN_BASETABLENAME—can have the same value in this column. DBCOLUMN_ISUNIQUE is guaranteed to be VARIANT_TRUE if the column constitutes a key by itself, or if there is a constraint of type UNIQUE that applies only to this column. VARIANT_FALSE: The column can contain duplicate values in the base table. The default of this column is VARIANT_FALSE.
DBCOLUMN_ MAYSORT	DBTYPE_BOOL	VARIANT_TRUE: The column can be sorted. VARIANT_FALSE: The column cannot be sorted.
DBCOLUMN_ OCTETLENGTH	DBTYPE_UI4	The maximum length in octets (bytes) of the column, if the column is a character or binary type. A value of zero means the column has no maximum length. NULL for all other types of columns. The default of this column is derived from the value of the CHARACTER_OCTET_LENGTH column in the COLUMNS schema rowset.
DBCOLUMN_KEYCOLUMN	DBTYPE_BOOL	VARIANT_TRUE—The column is one of a set of columns required in order to uniquely identify the row. VARIANT_FALSE—The column is not required to uniquely identify the row. If the DBPROP_UNIQUEROW property is set to VARIANT_TRUE, then the set of columns with DBCOLUMN_KEYCOLUMN set to VARIANT_TRUE uniquely identifies a row in the rowset.
DBCOLUMN_BASETABLEVERSION	DBTYPE_UI8	Version number of the table in the data source that contains the column. This number is assumed to change every time the table definition is modified. The way in which this number is generated is provider specific.