IRowsetUpdate::Update

Transmits any changes made to a row since it was last fetched or Update was called for it.

HRESULT Update (
   HCHAPTER            hChapter,
   ULONG               cRows,
   const HROW            rghRows[],
   ULONG *               pcRows,
   HROW **               prgRows,
   DBROWSTATUS**   prgRowStatus);

Parameters

hChapter

[in]
The chapter handle. For nonchaptered rowsets, hChapter is ignored.

cRows

[in]
The count of rows to update. If cRows is nonzero, Update updates all pending changes in the rows specified in rghRows. If cRows is zero, Update ignores rghRows and updates all pending changes to all rows in the rowset.

rghRows

[in]
An array of handles of the rows to update.

If rghRows includes a row that does not have any pending changes, Update does not return an error. Instead, the row remains unchanged and hence has no pending changes after Update returns—which is the intention of Update—and the row status value associated with that row is DBROWSTATUS_S_OK. Furthermore, Update guarantees not to transmit any value for the row to the data source.

If rghRows includes a duplicate row, Update behaves as follows. If the row handle is valid, no errors occur and *prgRowStatus contains DBROWSTATUS_S_OK for each occurrence. If the row handle is invalid, *prgRowStatus contains the appropriate error for each occurrence.

pcRows

[out]
A pointer to memory in which to return the number of rows Update attempted to update. If this is a null pointer, no count of rows is returned. If the method fails with an error other than DB_E_ERRORSOCCURRED, *pcRows is set to zero.

prgRows

[out]
A pointer to memory in which to return an array containing the handles of all the rows Update attempted to update. If rghRows is not a null pointer, then the elements of this array are in one-to-one correspondence with those in rghRows. For example, if a row appears twice in rghRows, it appears twice in *prgRows. When rghRows is not a null pointer, Update does not add to the reference count of the rows it returns in *prgRows; the reason is that the consumer already has these row handles.

If rghRows is a null pointer, the elements of this array are handles of all the rows that had pending changes, regardless of whether Update was successful at transmitting those changes to the data source. The consumer checks *prgRowStatus to determine which rows were updated. When rghRows is a null pointer, Update adds to the reference count of the rows it returns in *prgRows; the reason is that the consumer is not guaranteed to already have these row handles. A side effect of this is that rows with a reference count of zero, but with pending changes at the time Update is called, are brought back into existence; that is, their reference count is increased to 1 and they must be rereleased.

The rowset allocates memory for the array of handles and returns the address to this memory; the consumer releases this memory with IMalloc::Free when it no longer needs the handles. This argument is ignored if pcRows is a null pointer, and must not be a null pointer otherwise. If *pcRows is zero on output or the method fails with an error other than DB_E_ERRORSOCCURRED, the provider does not allocate any memory and ensures that *prgRows is a null pointer on output.

prgRowStatus

[out]
A pointer to memory in which to return an array of row status values. The elements of this array correspond one-to-one with the elements of rghRows (if rghRows is not a null pointer) or *prgRows (if rghRows is a null pointer). If no errors or warnings occur while updating a row, the corresponding element of *prgRowStatus is set to DBROWSTATUS_S_OK. If an error or warning occurs while updating a row, the corresponding element is set as specified in DB_S_ERRORSOCCURRED. If prgRowStatus is a null pointer, no row status values are returned. For information about the DBROWSTATUS enumerated type, see "Arrays of Errors" in Chapter 13.

The rowset allocates memory for the row status values and returns the address to this memory; the consumer releases this memory with IMalloc::Free when it no longer needs the row status values. This argument is ignored if cRows is zero and pcRows is a null pointer. If Update does not attempt to update any rows or the method fails with an error other than DB_E_ERRORSOCCURRED, the provider does not allocate any memory and ensures that *prgRowStatus is a null pointer on output.

Return Code

S_OK
The method succeeded. The changes in all rows were successfully updated. The following values can be returned in *prgRowStatus:

• The changes in the row were successfully updated. The corresponding element of *prgRowStatus contains DBROWSTATUS_S_OK.
  
  
• Updating or deleting a single row caused more than one row to be updated or deleted in the data source. For more information, see DBPROP_REPORTMULTIPLECHANGES in "Rowset Properties" in Appendix C. The corresponding element of *prgRowStatus contains DBROWSTATUS_S_MULTIPLECHANGES.

DB_S_ERRORSOCCURRED
An error occurred while updating a row, but at least one row was successfully updated. Successes can occur for the reasons listed under S_OK. The following errors can occur:

• Updating a row was canceled during notification. The row was not updated and the corresponding element of rgRowStatus contains DBROWSTATUS_E_CANCELED.
  
  
• The rowset was using optimistic concurrency, a row was being updated or deleted, and the value of a column in that row has been changed since it was last fetched. The error in the corresponding element of *prgRowStatus contains DBROWSTATUS_E_CONCURRENCYVIOLATION.
  
  
• An element of rghRows referred to a row for which a deletion had been transmitted to the data source. The error in the corresponding element of *prgRowStatus contains DBROWSTATUS_E_DELETED.
  
  
• A row was being inserted or updated and a value specified for that row violated the integrity constraints for the column or table. The error in the corresponding element of *prgRowStatus contains DBROWSTATUS_E_INTEGRITYVIOLATION.
  
  
• A row was being deleted, and doing so violated the integrity constraints for the column or table. The error in the corresponding element of *prgRowStatus contains DBROWSTATUS_E_INTEGRITYVIOLATION.
  
  
• An element of rghRows was invalid. The error in the corresponding element of *prgRowStatus contains DBROWSTATUS_E_INVALID.
  
  
• The consumer did not have sufficient permission to update, delete, or insert a row. This error can be returned only if the value of the DBPROP_ROWRESTRICT property is VARIANT_TRUE. The error in the corresponding element of *prgRowStatus contains DBROWSTATUS_E_PERMISSIONDENIED.
  
  
• The update, delete, or insert failed due to reaching a limit on the server, such as a query execution timing out. The error in the corresponding element of *prgRowStatus contains DBROWSTATUS_E_LIMITREACHED.
  
  
• A column value did not meet the schema requirements for the column. The error in the corresponding element of *prgRowStatus contains DBROWSTATUS_E_SCHEMAVIOLATION.
  
  
• The values for two or more columns did not meet the multiple-column schema requirements for those columns. The error in the corresponding element of *prgRowStatus contains DBROWSTATUS_E_SCHEMAVIOLATION.
  
  
• A row was being inserted, no value was specified for a column, the column does not have a default, and the column is non-nullable. The error in the corresponding element of *prgRowStatus contains DBROWSTATUS_E_SCHEMAVIOLATION.
  
  
• The consumer encountered a recoverable, provider-specific error, such as an RPC failure when transmitting the change to a remote server. The corresponding element of *prgRowStatus contains DBROWSTATUS_E_FAIL.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
cRows was not zero and rghRows was a null pointer.

pcRows was not a null pointer and prgRows was a null pointer on input.

E_OUTOFMEMORY
The provider was unable to allocate sufficient memory in which to return either the handles of the rows Update attempted to update or the array of row status values.

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

DB_E_BADCHAPTER
The rowset was chaptered and hChapter was invalid.

The rowset was single-chaptered and the specified chapter was not the currently open chapter. The consumer must use the currently open chapter or release the currently open chapter before specifying a new chapter.

DB_E_ERRORSOCCURRED
Errors occurred while updating all of the rows. The provider allocates memory for *prgRows and *prgRowStatus and the consumer checks the values in *prgRowStatus to determine why the pending changes were not updated. The consumer frees this memory when it no longer needs the information. Errors can occur for the reasons listed under DB_S_ERRORSOCCURRED.

DB_E_NOTREENTRANT
The provider called a method from IRowsetNotify in the consumer and the method has not yet returned.

Comments

Update transmits pending changes for the specified rows to the data source and clears their pending change status. That is, it transmits any changes made to the row since it was last fetched or Update was called for the row. For more information about pending changes, see "Changing Data" in Chapter 5.

The order in which Update processes rows is provider-specific. If Update encounters an error, it continues processing rows until it has attempted to update all specified rows, then it returns the appropriate warning. This might leave the rowset in a state where changes have been transmitted for some rows but not others. When the consumer repairs the cause of the error, it can call Update again and the provider guarantees it will not transmit data to the data source for those rows for which data was already successfully transmitted.

If any consumer of the rowset is using notifications, the provider sends notifications that pending changes for the specified rows are being transmitted to the data source.

If Update is called for a row that has a reference count of zero and exists only because the row has a pending change, Update releases the row and all its resources. The only exception to this is when the handle to the row is returned in *prgRows, in which case the reference count is set to 1.

If the provider cached original values to implement GetOriginalData and Undo, it discards them as part of Update.

If the rowset is released with IUnknown::Release before Update is called, all pending changes are lost.

See Also

IRowsetChange, IRowsetUpdate::Undo