IDBSchemaRowset

OLE DB Programmer's Reference

IDBSchemaRowset is an optional interface on sessions. It is used to provide advanced schema information.

Consumers can get information about a data store without knowing its structure by using the IDBSchemaRowset methods. For example, the data store might be one of the following types:

• A Microsoft SQL Server database that organizes each database into a set of schemas that contain the tables and queries for each schema.
• A Microsoft Access 2.0 database that has a container of tables and a container of queries.
• A Microsoft Access for Windows 95 database that enables users to define folders to group tables into an arbitrary hierarchy.

The schemas of each of the preceding data stores can be exposed to the consumer by using the methods of IDBSchemaRowset.

Schema rowsets in OLE DB are identified by GUIDs and have predefined restriction columns. The restrictions allow the consumer to limit the set of rows returned by the schema rowset but does not define the format for those restrictions.

IDBSchemaRowset::GetSchemas returns to the consumer a list of schema rowsets, identified by their GUIDs, that are accessible by IDBSchemaRowset::GetRowset. Also returned is a pointer to descriptions of the restriction columns supported for that schema rowset.

IDBSchemaRowset::GetRowset allows the consumer to retrieve the specified schema rowset by passing in the GUID identifying the rowset and the count of restriction columns or an array of restriction values. Each schema rowset will return all of the columns in the order indicated by that rowset's respective table in Appendix B: Schema Rowsets.

Specifying restriction columns allows the consumer to limit the returned rowset to only those rows in the data store whose columns and values match the values specified in rgRestrictions. These values are applied in the same order as the restriction columns.

Note   The number of restriction columns for each schema rowset is defined as a constant prefixed with CRESTRICTIONS_ in the header files. Restriction values are treated as literals rather than as search patterns. For example, the restriction value "A_C" matches "A_C" but not "ABC".

Programming considerations

At a minimum, providers that implement IDBSchemaRowset must support the passing of the restrictions according to the VARIANT types indicated in the following table. Providers are allowed to support restrictions passed as other types but must convert as dictated by the OLE DB specification.

Restriction column OLE DB type	VARIANT type of passed restriction
DBTYPE_BOOL	VT_BOOL
DBTYPE_DATE	VT_DATE
DBTYPE_GUID	VT_BSTR (string in registry format: "{xxxxxxxx-xxxx...}")
DBTYPE_I2	VT_I2
DBTYPE_I8	VT_I8
DBTYPE_UI2	VT_UI2
DBTYPE_UI4	VT_UI4
DBTYPE_UI8	VT_UI8
DBTYPE_WSTR	VT_BSTR

All providers must support the TABLES, COLUMNS, and PROVIDER_TYPES schema rowsets, identified by the following GUIDs: DBSCHEMA_TABLES, DBSCHEMA_COLUMNS, and DBSCHEMA_PROVIDER_TYPES.

Providers can return provider-specific columns after the last column defined by OLE DB. Other OLE DB models, such as OLE DB for OLAP, can define their own schema rowsets to meet specific needs.

Provider writers should pay particular attention to rowset construction and data retrieval performance, because these methods will be used frequently by consumers.

Although the OLE DB schema rowsets define a minimum content of the system schema, consumers can also look at the schema tables in the database and thus discover other schema tables and attributes beyond the minimum set.

It is suggested that consumers precompile and store the specialized queries used for processes such as command planning and execution-time plan validation. Storage engines may have specialized optimizations associated with those plans.

Providers must return all of the schema rowset columns. If they cannot return the information in a column, they must return an appropriate value, usually NULL. Providers can return provider-specific columns after the last column defined by OLE DB.

For more information about schema rowsets, see Appendix B: Schema Rowsets.

Method	Description
GetRowset	Returns the specified schema rowset and its column restrictions, if requested.
GetSchemas	Returns a list of schema rowsets accessible by IDBSchemaRowset::GetRowset and the restriction columns supported.

1998-2001 Microsoft Corporation. All rights reserved.