OLE DB Simple Provider Toolkit

OLEDBSimpleProvider::getVariant

Retrieves the value of the cell at the indicated row and column into the preallocated Variant supplied in pVar.

getVariant uses the following enumeration:

typedef enum OSPFORMAT {
   OSPFORMAT_RAW = 0,
   OSPFORMAT_DEFAULT = 0,
   OSPFORMAT_FORMATTED = 1,
   OSPFORMAT_HTML = 2
};

The preceding values are defined in the following table.

Value Meaning
OSPFORMAT_RAW

OSPFORMAT_DEFAULT

 Underlying column type should be used to get the value (the default).
OSPFORMAT_FORMATTED Underlying column type should be converted to a string, and the string should be returned as a BSTR within the Variant. It is mandatory for OSP developers to support the fFormatted argument of getVariant with this value.
OSPFORMAT_HTML This value was originally intended to convert the underlying column type to an HTML string. In actual practice, the OSP mapping layer (Msdaosp.dll) does not use this value; however, for interoperability with Microsoft® Internet Explorer data binding, simple providers should support it. Provider writers should return data as Variant or BSTR; no HTML formatting is required. 
HRESULT getVariant (
   LONG        iRow,
   LONG        iColumn,
   OSPFORMAT   fFormatted,
   VARIANT    *pVar);

Parameters

iRow
[in]
Position of the specified row.
iColumn
[in]
Position of the specified column.
fFormatted
[in]
Enumerated value that determines the format in which to return the cell value's underlying column type. (See previous table and Comments.)
pVar
[out]
Based on the value specified in the pVar parameter, pVar will contain one of the following:
  • A value in the underlying type of the column.
  • A string corresponding to the underlying type of the column.
  • An HTML fragment corresponding to the underlying type of the column.

Return Codes

S_OK
The method succeeded.
E_FAIL
A provider-specific error occurred.

Comments

OLEDBSimpleProvider::getVariant does not support references.

For the fFormatted argument, it is mandatory for OSP developers to support getVariant with a value of OSPFORMAT_FORMATTED. The OSP implementation is responsible for type conversion, and in the case of Boolean values, the correctly formatted string must be either True or False.

When accessing column header names (row 0), or converting to OLE DB string types, for example DBTYPE_WSTR, the mapping layer uses OSPFORMAT_FORMATTED to return the cell value as a string.

When getting the value as a Variant, or when the OLE DB status value is set to DBSTATUS_S_ISNULL (meaning the value is not bound), the mapping layer calls getVariant with OSPFORMAT_RAW to return the Variant value or VT_EMPTY, respectively. Therefore simple providers should support both of these values.

When OSPFORMAT_HTML is requested, the provider may, at its option, return a plain string (for example, unadorned with HTML tags).

A data value of NULL is indicated by returning one of the following:

Do not use a value of -1 as an argument with the iRow and iColumn arguments of OLEDBSimpleProvider::getVariant. You must retrieve table cells individually; they cannot be retrieved a row or column at a time.

OLEDBSimpleProvider::getVariant is one of the few OSP methods that returns an object or variant. Take care to allocate a fresh variant that is not used elsewhere to return to the Microsoft Virtual Machine, which can free the object at any time.