Column IDs

OLE DB Programmer's Reference

Consumers use column IDs primarily when executing commands on data stores for which there are no stable column ordinals. Because column IDs are relatively slow to use on a repeated basis, consumers use column ordinals to identify columns in DBBINDING structures. (For more information about DBBINDING structures, see "DBBINDING Structures" in Chapter 6: Getting and Setting Data.) A consumer calls IColumnsInfo::MapColumnIDs to retrieve a column ordinal from a column ID:

typedef struct tagDBID {    union {       GUID guid;       GUID * pguid;       } uGuid;       DBKIND eKind;    union {       LPOLESTR pwszName;       ULONG ulPropid;       } uName; } DBID;

The values of DBKIND are described in the following table.

Value	Meaning
DBKIND_GUID_NAME	Use the guid and pwszName elements.
DBKIND_GUID_PROPID	Use the guid and ulPropid elements.
DBKIND_NAME	Use only the pwszName element; ignore the uGuid element.
DBKIND_PGUID_NAME	Use the pGuid and pwszName elements.
DBKIND_PGUID_PROPID	Use the pGuid and ulPropid elements.
DBKIND_PROPID	Use only the ulPropid element; ignore the uGuid element.
DBKIND_GUID	Use only the guid element; ignore the uName element.

The members of a DBID are represented in schema rowset columns as follows.

DBID eKind	Schema columns
DBKIND_GUID_NAME	_GUID and _NAME column values must be provided.
DBKIND_GUID_PROPID	_GUID and _PROPID column values must be provided.
DBKIND_NAME	_NAME column value must be provided.
DBKIND_PGUID_NAME	_GUID and _NAME column values must be provided.
DBKIND_PGUID_PROPID	_GUID and _PROPID column values must be provided.
DBKIND_PROPID	_PROPID column value must be provided.
DBKIND_GUID	_GUID column value must be provided.

Consumers should treat table and column names within DBID structures as case-sensitive.

If a provider implements row objects, column IDs must be unique within a row object.

OLE DB providers never return pGuid-style bindings. They are provided as a convenient shortcut for consumers supplying bindings all covered by the same GUID (for example, when creating bindings to access data).

The value DB_NULLID is defined as the DBID structure containing all zeroes. Because pwszName is a NULL pointer for DB_NULLID, you should not attempt to free this string.

When constructing DBIDs to identify tables, indexes, or columns, consumers use the non-NULL columns in the appropriate schema rowset to determine the DBKIND value of the DBID. For example, when specifying a table ID, a consumer would call IDBSchemaRowset::GetRowset and examine the TABLES schema rowset. On discovering that TABLE_NAME has a value and TABLE_GUID is NULL, the consumer specifies DBKIND_NAME for the table ID. In methods that take column DBIDs as parameters, the validation of the DBID should include a check on the validity of the DBID's eKind.

It should not be assumed that DBIDs used for row and rowset columns are the same as DBIDs constructed from the COLUMNS schema rowset for base columns. Nor is there currently a property that reports whether a provider's row or rowset DBIDs match the column IDs constructed from base schema information. However, many OLE DB relational providers are implemented so that they are the same. Following are the important scenarios:

• Consumers should be able to construct DBIDs from the appropriate COLUMN_NAME, COLUMN_GUID, and COLUMN_PROPID columns of the COLUMNS schema rowset. These DBIDs should be usable in schema-modifying methods, such as IAlterTable::AlterColumn and ITableDefinition::DropColumn, that require column IDs.

  For providers that use DBIDs of type DBKIND_NAME, consumers should be able to construct column DBIDs from the DBCOLUMN_BASECOLUMNNAME column of the column metadata rowset returned by IColumnsRowset::GetColumnsRowset.

• If providers implement row or rowset DBIDs that are the same as the DBIDs constructed in the first scenario, the DBIDs in the DBCOLUMNINFO's columnid element could also be used in schema-modifying methods.
• If a row or rowset DBID is different from a base column ID as constructed in the first scenario, consumers should not expect DBIDs obtained from IColumnsInfo::GetColumnInfo to work in schema-modifying methods. Providers should match DBIDs based on the DBID's eKind; for example, DBIDs of type DBKIND_GUID_NAME should match both the GUID and name parts.

1998-2001 Microsoft Corporation. All rights reserved.