IRowChange::SetColumns

  • Article

Sets the values of one or more named columns of a row object.

Syntax

HRESULT SetColumns(
   DBORDINAL        cColumns,
   DBCOLUMNACCESS   rgColumns[ ]
);

Parameters

  • cColumns
    [in] Count of columns specified in the rgColumns array. If cColumns is zero, no columns are set.

  • rgColumns[ ]
    [in/out] A caller-supplied array of DBCOLUMNACCESS structures. The DBCOLUMNACCESS structure is described in the reference entry for IRow::GetColumns.

    For setting column values, the elements of each DBCOLUMNACCESS structure are used in the manner described in the following table.

    Element

    Description

    columnid

    Unique DBID that identifies the column to be accessed.

    wType

    Identifies the type of the value pointed to by pData.

    pData

    Caller-allocated pointer to storage of the data type specified by wType. On input, the area pointed to contains the value of the column specified by columnid. The caller must allocate and initialize the area of storage pointed to by pData. The provider should attempt to coerce the value from wType to the underlying value of the column. If wType is DBTYPE_VARIANT, the provider is responsible for allocating any variable-length storage pointed to by the VARIANT.

    NoteNote
    For more information about data type indicators (DBTYPE values), see "Type Indicators" in Appendix A: Data Types.

    cbMaxLen

    The maximum length of the caller-initialized memory pointed to by pData. The provider checks the length in bytes of variable-length data types against cbMaxLen. If the length is greater than cbMaxLen, this is an error and the provider sets the status to DBSTATUS_E_CANTCONVERTVALUE.

    bPrecision

    Indicates the precision of the value stored in *pData for data types equiring precision.

    bScale

    Indicates the scale of the value stored in *pData for data types requiring scale.

    dwStatus

    On input, dwStatus indicates whether pData or some other value should be used. When value DBSTATUS_S_ISNULL is used to set the column to null, other fields (wType, pData, cbDataLen) are ignored. On return, dwStatus indicates whether the field was successfully set. The following status values may apply when setting column values. For more information, see Status.

    • DBSTATUS_S_OK ? The column value was set.

    • DBSTATUS_E_DOESNOTEXIST ? The column does not exist on this row.

    • DBSTATUS_E_INTEGRITYVIOLATION ? The column is a calculated or derived value and cannot be directly modified.

    • DBSTATUS_E_PERMISSIONDENIED ? The column is defined as read-only, or the consumer has bound to the row in read-only mode.

    • DBSTATUS_E_UNAVAILABLE ? On input, the status was DBSTATUS_S_OK, IColumnsInfo::GetColumnInfo did not return DBCOLUMNFLAGS_ISLONG for this column, and pData was a null pointer.

    cbDataLen

    On input, the length of the data value pointed to by pData. Ignored for fixed-length types.

Return Code

  • S_OK
    The provider successfully set all of the columns.

  • E_INVALIDARG
    cColumns was not zero, and rgColumns was a null pointer.

  • E_OUTOFMEMORY
    The provider was unable to allocate sufficient memory for this operation.

  • DB_S_ERRORSOCCURRED
    The provider was able to set at least one column but was unable to set at least one column. The caller should examine dwStatus of each element of rgColumns to determine whether, and why, an individual column was not set.

  • DB_E_DELETEDROW
    The row is either a pending delete row or a row for which a deletion had already been transmitted to the data store.

  • DB_E_ERRORSOCCURRED
    An error occurred while setting data for one or more columns, and data was not successfully set for any columns. The caller should examine dwStatus of each element of rgColumns to determine why each individual column was not set.

  • DB_E_NEWLYINSERTED
    The value of the DBPROP_CHANGEINSERTEDROWS property on the source rowset was VARIANT_FALSE, and the method was called on a row for which the insertion has been transmitted to the data store.

  • DB_SEC_E_PERMISSIONDENIED
    The provider was unable to set any columns because of a permission failure.

  • E_FAIL
    A provider-specific error occurred. No columns were set.

  • E_UNEXPECTED
    ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state.

Comments

IRowChange::SetColumns sets the columns named in columnid of the rgColumns array with the values pointed to by pData.

If a named column exists in the row, the provider attempts to coerce the value pointed to by pData from wType to the underlying type of the column.

If a named column does not exist, the provider should return either DB_S_ERRORSOCCURRED (if at least one column was set) or DB_E_ERRORSOCCURRED (if no columns were set) and set the corresponding status value dwStatus to a DBSTATUS value of DBSTATUS_E_DOESNOTEXIST.

Providers are not required to support column creation. If a provider does support column creation, it should implement IRowSchemaChange.

IRowChange::SetColumns may not change the underlying type of a column. The provider should attempt to coerce the value pointed to by pData to the defined type of the column. If the provider cannot perform the coercion, the provider should return either DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED and set the dwStatus to DBSTATUS_E_CANTCONVERTVALUE.

If a row does not have a source rowset or if changes to the source rowset are immediate, changes to all row column values are also immediate. If a row has a source rowset and changes to this rowset are deferred, changes to all row column values are also deferred. IRowsetUpdate::Update commits pending changes for row columns as well as for rowset columns.

If the provider supports type conversions to or from the row types described by the DBCOLUMNINFO structure, it should implement IConvertType on the row. This interface is used to report whether a given conversion is supported. It is recommended that providers delegate conversions to the OLE DB Data Conversion library, Oledb32.dll. For more information, see Data Conversion Library in Appendix H: Data Type Conversion Interfaces.

When setting row column data values from a consumer's storage object, the provider is responsible for releasing the storage object. When the provider has finished using the consumer's storage object, it calls IUnknown::Release to release the pointer. If the consumer wants to ensure access to its storage object after IRowChange::SetColumns returns, it must call IUnknown::AddRef on the pointer before calling SetColumns.