共用方式為

IRowsetUpdate::Update

  • 發行項

Transmits any changes made to an existing row since it was last fetched or IRowsetUpdate::Update was called for it. Transmits a newly created row that is pending insert.

Syntax

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

Parameters

  • hReserved
    [in] Reserved for future use. Must be DB_NULL_HCHAPTER.

  • cRows
    [in] The count of rows to update. If cRows is nonzero, IRowsetUpdate::Update updates all pending changes in the rows specified in rghRows. If cRows is zero, IRowsetUpdate::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, IRowsetUpdate::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, IRowsetUpdate::Update guarantees not to transmit any value for the row to the data store.

    If rghRows includes a duplicate row, IRowsetUpdate::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 IRowsetUpdate::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 IRowsetUpdate::Update attempted to update. If rghRows is not a null pointer, 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, IRowsetUpdate::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, whether or not IRowsetUpdate::Update was successful at transmitting those changes to the data store. The consumer checks *prgRowStatus to determine which rows were updated. When rghRows is a null pointer, IRowsetUpdate::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 IRowsetUpdate::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.

    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 IRowsetUpdate::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 store. 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 store. 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. 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 IRowsetUpdate::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 hReserved 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 that had not yet returned, and the provider does not support reentrancy in this method.

Comments

IRowsetUpdate::Update transmits pending changes for the specified rows to the data store and clears their pending change status. That is, it transmits any changes made to an existing row since it was last fetched or IRowsetUpdate::Update was called for the row. New rows that are pending insert are also transmitted by the Update command. For more information about pending changes, see Changing Data.

The order in which IRowsetUpdate::Update processes rows is provider-specific. If Update encounters an error, it continues processing rows until it has attempted to update all specified rows and 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 IRowsetUpdate::Update again and the provider guarantees it will not transmit data to the data store 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 store.

If IRowsetUpdate::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 IRowsetUpdate::GetOriginalData and IRowsetUpdate::Undo, it discards them as part of IRowsetUpdate::Update.

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

See Also

Reference

IRowsetChange

IRowsetUpdate::Undo