getVariant

  • Article

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

Important

This feature will be removed in a future version of Windows. Avoid using this feature in new development work, and plan to modify applications that currently use this feature. Instead, write a fully functional OLE DB provider using the native OLE DB interfaces.

Syntax

HRESULT getVariant (
   DBROWCOUNT      iRow,
   DB_LORDINAL     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 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

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.

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:

  • S_OK and a Variant of type VT_NULL

  • S_FALSE (and pVar will be ignored for any of the fFormatted types).

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.