Row Metadata

OLE DB Programmer's Reference

Like rowset columns, row object columns are identified by column IDs, which take the form of DBID structures. Column IDs must be unique within a row or rowset. This allows columns to be accessed by name, GUID, or PROPID.

If a row object is created from a row in a rowset, the columns of the row object must be a superset of the columns of the source rowset. That is, the row object can contain row-specific columns in addition to those that are already defined by the source rowset. The row schema of a row object is the set of all columns of the row object.

Getting Column Metadata

Applications cannot always detect what columns are available in a row object. This is particularly true of any number of general-purpose data binding tools. Therefore, it is useful to enumerate the names and types of the available columns in a row. To get column metadata for row object columns, consumers call IColumnsInfo2::GetColumnInfo (inherited from IColumnsInfo). This method returns metadata, including the types of the available columns in the row object.

For applications involving data stores that have large numbers of columns, IColumnsInfo2::GetColumnInfo may return a very large amount of metadata. In such cases, it is often useful to get column metadata for a restricted set of columns, based on a column name mask. OLE DB 2.5 introduces the IColumnsInfo2::GetRestrictedColumnInfo method, which can return column metadata based on an optional column mask.

Setting Column Metadata

To add or delete row-specific columns, the consumer calls IRowSchemaChange methods. IRowSchemaChange::DeleteColumns deletes columns from a row or, if the columns also belong to a source rowset, sets their values to NULL. IRowSchemaChange::AddColumns can be used to create the row schema or add columns to it.

Note   These methods cannot add or remove columns that are inherited from the parent rowset of the row object.

The AddColumns method is similar to IRowChange::SetColumns; however, IRowSchemaChange::AddColumns creates a column if it does not already exist, while IRowChange::SetColumns returns an error if it is called for a nonexistent column.

If a consumer deletes a column that is part of both a row and its source rowset, subsequent calls to access that column must return a null value until both the row and rowset are released. If a consumer deletes a column from a row and that column is not part of the source rowset, providers are free to delete the column from the row. Subsequent calls to access the deleted column can return the DBSTATUS_E_DOESNOTEXIST status code, indicating that the column does not exist.

1998-2001 Microsoft Corporation. All rights reserved.