IColumnsRowset::GetColumnsRowset

OLE DB Programmer's Reference

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,    DBORDINAL     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, 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, 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 14: Properties.
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 IColumnsRowset::GetColumnsRowset is called on a command that does not return rows, 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_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED.

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:

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 that was specified to be applied to all columns could not be applied to one or more columns.
The property was not supported by the provider.
The property set was not supported by the provider.
It was not possible to set the property.
The property was not in the Rowset property group.

DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop. Of course, the properties-in-error are not available, but for any properties that could not be set, the provider should report that status in the property array passed to IColumnsRowset::GetColumnsRowset (assuming that property failures can all be determined ahead of rowset population).

DB_S_NOTSINGLETON

The provider supports returning row objects on IColumnsRowset::GetColumnsRowset, and the consumer requested a row object but the result was not a singleton. A row object of the first row of the rowset is returned if the provider supports returning the row object. Because returning this result may be expensive, providers are not required to do so. If DB_S_ERRORSOCCURRED also applies to the execution of this method, it takes precedence over DB_S_NOTSINGLETON.

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.

DB_E_NOAGGREGATION

pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support aggregation of the rowset object being created.

pUnkOuter was not a null pointer, and riid was not IID_IUnknown.

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_NOTFOUND

The provider supports the return of singleton row objects on a method that typically returns a rowset, a row was requested via riid or DBPROP_IRow, and no rows existed in the rowset.

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 that had not yet returned, and the provider does not support reentrancy in this method.

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.

IColumnsRowset::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 object, 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, the order is determined by the provider—for example, 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 that are requested.

IColumnsRowset::GetColumnsRowset can be called for rowsets created by GetColumnsRowset.

Calling IColumnsRowset::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 IColumnsInfo::GetColumnInfo.

Column ID	Type indicator	Description
DBCOLUMN_IDNAME	DBTYPE_WSTR	Column name. This column, together with the DBCOLUMN_GUID and DBCOLUMN_PROPID columns, forms the ID of the column. One or more (but not all) 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 IColumnsRowset::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 in bytes (for DBTYPE_BYTES and DBTYPE_VARNUMERIC), 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 in bytes (for DBTYPE_BYTES and DBTYPE_VARNUMERIC), if the column does not have a defined length. ~0 (bitwise, the value is not 0; 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; 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 store 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 store. 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 or if the rowset column is derived, but not identical to, a column in the data store. The default of this column is NULL.
DBCOLUMN_BASESCHEMANAME	DBTYPE_WSTR	The name of the schema in the data store 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 or view in the data store 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. 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 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 whether the column has a default value or whether 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 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 in the rowset that, taken together, uniquely identify the row. The set of columns with DBCOLUMN_KEYCOLUMN set to VARIANT_TRUE must uniquely identify a row in the rowset. There is no requirement that this set of columns is a minimal set of columns. This set of columns may be generated from a base table primary key, a unique constraint or a unique index. VARIANT_FALSE—The column is not required to uniquely identify the row.
DBCOLUMN_BASETABLEVERSION	DBTYPE_UI8	Version number of the table in the data store 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.
DBCOLUMN_DERIVEDCOLUMNNAME	DBTYPE_WSTR	The name of the column in the data store from which this rowset column is derived if, for example, derived from a single-column expression or an invertible function. Mutually exclusive with DBCOLUMN_BASECOLUMNNAME. The default of this column is NULL.

Required Metadata Columns

Optional Metadata Columns

See Also