getVariant

MDAC 2.5 SDK - OLE DB Providers
OSP 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_RAWOSPFORMAT_DEFAULT	Underlying column type should be used to set or 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	Underlying column type should be converted to an HTML string.

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 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.