setVariant

  • Article

Sets the value of the cell at the row and column indicated to the value of the Variant supplied in pVar in the type requested by the value of fFormatted.

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 setVariant (
   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 table below.)

  • pVar
    [in/out] Based on the value specified in the pVar parameter, pVar will contain one of the following:

    • A value with 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
    The value could not be set, or the provider was read-only.

Comments

setVariant 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 set the value (the default).

OSPFORMAT_FORMATTED

The input string is placed into the cell based on provider-specific heuristics.

OSPFORMAT_HTML

Provider-specific. The input string optionally can be in HTML format.

setVariant does not support references.

setVariant requires the following notifications:

With any formatting option, it is the provider's responsibility to perform the appropriate coercion to the underlying type of the column. In cases where the coercion cannot be successfully completed, an appropriate error code should be returned.

With the value OSPFORMAT_FORMATTED, the provider is free to interpret the input string however it sees fit. Alternatively, the provider may attempt to parse the input string and heuristically determine an appropriate data type and value to place into the cell ? for example, when updating formatted spreadsheet cells.

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

A data value of NULL is indicated by passing a Variant of type VT_NULL in pVar for any of the fFormatted types.

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

For more information and programming considerations about sending and receiving notifications, see Notifications (OLE DB).