IRowsetNotify::OnFieldChange

OLE DB Programmer's Reference

Notifies the consumer of any change to the value of a column.

HRESULT OnFieldChange (    IRowset       *pRowset,    HROW           hRow,    DBORDINAL      cColumns,    DBORDINAL      rgColumns[],    DBREASON       eReason,    DBEVENTPHASE   ePhase,    BOOL           fCantDeny);

Parameters

pRowset: [in]
A pointer to the rowset, because the consumer may be receiving notifications from multiple rowsets and this identifies which one is calling.
hRow: [in]
The handle of the row in which the column value was changed. After this method returns, the reference count of this row will be unchanged unless the consumer explicitly changes it. This is different from other methods that return rows to the consumer, in which the provider explicitly increments the reference count. Therefore, if the consumer wants to guarantee that this row handle is valid after this method returns, it must call IRowset::AddRefRows for the row while it is processing this method.
cColumns: [in]
The count of columns in rgColumns.
rgColumns: [in]
An array of columns in the row for which the value was changed.
eReason: [in]
The reason for the change as indicated by the value of DBREASON. If this value is not recognized by the method, the method returns S_OK or DB_S_UNWANTEDREASON.
ePhase: [in]
The phase of this notification.
fCantDeny: [in]
When this flag is set to TRUE, the consumer cannot veto the event by returning S_FALSE because the provider cannot undo the event.

Return Code

S_OK: The method succeeded.
S_FALSE: The notification, expressed by the value of DBREASON or DBEVENTPHASE or both, is vetoed by reason of logical objection or a failure to be able to implement.
DB_S_UNWANTEDPHASE: The consumer is not interested in receiving this phase for this reason. The provider can optimize by making no further calls with this reason and phase. The phases for other reasons are unaffected.
DB_S_UNWANTEDREASON: The consumer is not interested in receiving any phases for this reason. The provider can optimize by making no further calls with this reason.
E_FAIL: A consumer-specific error occurred. The provider continues the operation.

Comments

Possible reasons are DBREASON_COLUMN_SET and DBREASON_COLUMN_RECALCULATED.

All notification phases can occur for a DBREASON_COLUMN_SET change. The new value is visible beginning with the DBEVENTPHASE_SYNCHAFTER notification phase. For a DBREASON_COLUMN_RECALCULATED change, only the DBEVENTPHASE_DIDEVENT notification phase occurs.

Providers call IRowsetNotify::OnFieldChange once for all of the columns set in a single call to IRowsetChange::SetData, and once for all of the changes to calculated columns of a row based on an update to that row. Setting a column to its current value can, but is not required to, generate a notification for that column.

Unless the consumer returns S_FALSE, the provider continues the operation. This is true even if the consumer returns E_FAIL or any other error code.

Providers are not required to send notifications for ignored columns—that is, columns where status is set to DBSTATUS_S_IGNORE. However, many providers send such notifications even though no work is done. In those cases, the provider must also send a completion notification with the DBEVENTPHASE_DIDEVENT phase. The DBEVENTPHASE_FAILEDTODO notification phase is not an appropriate completion notification for ignored columns.

See Also