Visual C++ 6 Unleashed

Visual C++ 6 Unleashed

By MICKEY WILLIAMS and David Bennett

Retrieving Column Information

After you have created a rowset object, you can retrieve information about the columns in the rowset, including the column IDs, data types, updatability, and other info. This capability is especially important if you don't quite know the column names or types, as you may not with a SELECT * command. This section describes how to retrieve column information from a recordset.

GetColumnInfo()

You can call the GetColumnInfo() method to retrieve information about the columns in the rowset. The prototype for GetColumnInfo() is shown here:

HRESULT GetColumnInfo (ULONG * pcColumns, DBCOLUMNINFO ** prgInfo,
                          OLECHAR ** ppStringsBuffer);

GetColumnInfo() returns the number of columns included in the rowset at pcColumns. In addition, it returns a pointer to an array of DBCOLUMNINFO structures—one for each column—at prgInfo, and returns a pointer to a buffer containing all string values associated with the columns (such as column names) at ppStringsBuffer. Both these buffers are allocated by OLE DB and should be freed with a call to IMalloc::Free() when you are finished with them.

DBCOLUMNINFO

When GetColumnInfo() is called, a pointer to an array of DBCOLUMNINFO structures is returned at prgInfo. This array includes a DBCOLUMNINFO structure for each column in the rowset, possibly including a bookmark column.

Note

A bookmark column is always returned, regardless of whether bookmarks were requested or how the rowset was created. Your applications should be prepared to handle these, even if that means simply ignoring the bookmark column.

The DBCOLUMNINFO structure returned from GetColumnInfo() is shown here:

typedef struct tagDBCOLUMNINFO {
   LPOLESTR      pwszName;
   ITypeInfo *   pTypeInfo;
   ULONG         iOrdinal;
   DBCOLUMNFLAGS dwFlags;
   ULONG         ulColumnSize;
   DBTYPE        wType;
   BYTE          bPrecision;
   BYTE          bScale;
   DBID          columnid;
} DBCOLUMNINFO;

The pwszName field points to a string containing the column name. The memory for this string is allocated by OLE DB in the block of memory specified by the pointer returned in ppStringsBuffer when GetColumnInfo() is called. This way, you can access each of the column names simply by using the pwszName pointer, but you need only call IMalloc::Free() for the one pointer returned in ppStringsBuffer.

In the current release, pTypeInfo is reserved and should always return NULL, whereas the iOrdinal field returns the ordinal for the column. The bookmark column is column 0, and the others are numbered in order, starting with 1. The column ID for the column is returned in the columnid field.

The dwFlags field contains a bitmap that describes the characteristics of the column and can contain a combination of the following values:

The ulColumnSize field contains the maximum length of the column's data. For columns of type DBTYPE_STR or DBTYPE_WSTR, this is given in characters (which are 2 bytes). For columns of type DBTYPE_BYTES, the maximum length is given in bytes. If there is not a maximum length, ulColumnSize is set to 0xFFFFFFFF.

The wType field gives the type of the column data, and the bPrecision field gives the maximum precision for columns with numeric data types. If the column does not hold a numeric value, bPrecision is set to 0xFFFFFFFF. In addition, the bScale field gives the number of digits to the right of the decimal point.

GetColumnsRowset()

In addition to GetColumnInfo(), you can retrieve more complete information about the columns in a rowset by calling GetColumnsRowset(). GetColumnsRowset() returns a rowset object, which can contain a wide variety of optional information about the columns, as well as the information returned by GetColumnInfo(). However, not all providers implement this functionality.

Share ThisShare This

Informit Network