Methods for performing operations on a batch of scratchpad objects.
This method must be supported in every implementation of this interface.
Syntax
DmaRC IdmaBatch::ExecuteChanges (
Dmapv pICallback,
Dmapv plListOfObj,
pDmaIndex32 piIndex,
DmaInteger32 lProtectionLevel,
DmaBoolean bRefreshFlag)
Parameters
Name | Mode | Description |
pICallback | input | (optional) Pointer to callback interface. |
plListOfObj | input | An interface pointer to a list object whose elements are the scratchpad objects that are to have their changes reflected in the database. |
piIndex | output | If the transaction fails, this parameter is set to the index of the object in the list that aborted the transaction. If the transaction succeeds, the value of this parameter is set to -1. |
lProtectionLevel | input | Sets the protection level against concurrent updates. The value of this parameter must be one of DMA_MODIFY_PROTECTED or DMA_MODIFY_UNPROTECTED . The same level of protection applies to all scratchpad objects in the collection. The rules for this parameter are the same as for the ExecuteChange method of the IdmaConnection interface. |
bRefreshFlag | input | If RefreshFlag is TRUE, the snapshots in the scratchpad objects are updated according to the rules for IdmaConnection::Refresh. |
The ExecuteChanges method is defined relative to the IdmaConnection:: ExecuteChange method. The most important difference between the two methods is that, instead of operating on a single object, ExecuteChanges operates on a list of objects as a batch. The ExecuteChanges method makes the changes that ExecuteChange would have made to each object in the list. ExecuteChanges always performs all of the changes to the persistent store within a single transaction. If the change for any object fails, the entire transaction is aborted and backed out of the persistent store. If the change fails, none of the objects are refreshed, even if the bRefreshFlag is set to DMA_TRUE.
If there is any serial sequence of calls to IdmaConnection:: ExecuteChange on the objects in the pListOfObj list that would accomplish the desired final effect to the persistent store (assuming no concurrent updates to the persistent store), then the objects in the pListOfObj list are required to be in such an order, and ExecuteChanges applies the changes in order of increasing list index.
If there is no such sequence, then ExecuteChanges will attempt to make all the changes to the objects in increasing list index order. However, there may be transient inconsistent or illegal states during the execution of the transaction which can be tolerated as long as the final state is valid. If the final state is invalid, the transaction fails. For example, if the document space requires all documents to be contained directly, there is no series of ExecuteChange calls that will succeed in creating a new document. However, ExecuteChanges can succeed, if the document object is followed by the relationship object in the pListOfObj list.
ExecuteChanges does not affect any locks, except in the case that the current connection holds a write lock on a persistent object that ExecuteChanges deletes. In that case, the write lock is deleted as well.
Refer to the description of IdmaConnection:: ExecuteChange for the operation of the Create Pending, Delete Pending, and Update Pending properties, and for the effect of the protection level parameter.
In addition to the result codes listed below, the return code of this method can reflect any of the failures that can occur as a result of a create, update, or delete.
Return Values
Name | Description |
DMARC_ABORT | The progress callback indicated that the method should be aborted. |
DMARC_BAD_OBJECT | An inappropriate object was passed as parameter to this function. For example, the object does not support a required interface or is of an inappropriate class. |
DMARC_BAD_PARAMETER | (E_INVALIDARG) Invalid input parameter. |
DMARC_BAD_REFERENCE | The object cannot be saved because it references another object which is not persistent. |
DMARC_CONSTRAINT_VIOLATED | The operation violates a constraint of the implementation. |
DMARC_FOREIGN_OBJECT | An object is not from the current document space. |
DMARC_LIST_BOUNDS_ERROR | The number of elements in a list is outside the permitted range. |
DMARC_MISSING_REFERENCE | The object cannot be saved because required reference to it is absent. For example, it may be required to be in a container and no appropriate relationship object exists. |
DMARC_NOT_AUTHENTICATED | The user is not authenticated. |
DMARC_NOT_UNIQUE | A uniqueness requirement has been violated. |
DMARC_OK | (S_OK) Success. |
DMARC_PROTECTION_LEVEL_NOT_SUPPORTED | The desired protection level is not supported by the doc space. |
DMARC_READ_ONLY | Method failed because an object or property is read-only. |
DMARC_REQUIRED_VALUE_ABSENT | A required property value has not been set. |
DMARC_STALE_METADATA | The metadata in the persistent store has been changed so that it does not match the client's current copy of the metadata. |