IdmaConnection

This interface provides access to the persistent state of an independently persistent scratchpad object. It exploits the logical connection to the document space in order to apply and remove locks, refresh the snapshot of the persistent state and to apply updates to the persistent state.

IdmaConnection::ApplyLock

Support for this method is optional.

Syntax
DmaRC IdmaConnection::ApplyLock (
DmaInteger32 lLockType)

Parameters

Lock an object in the persistent store in one of several modes. This permits client applications to operate while maintaining the proper level of data integrity on the object's persistent store. There is no requirement to use a lock in order to modify an object. If it is not possible to acquire the requested lock on the object, the status of the connections lock will not be altered, and a result code indicating the reason for failure will be returned. This function will not wait for a lock to become available, it will return as soon as it is determined that a lock can or cannot be acquired.

Valid values for lLockType include: DMA_LOCK_READ, DMA_LOCK_WRITE and DMA_LOCK_EXIST. DMA_LOCK_READ puts a read lock on this object. This prevents other connections from getting an write lock on the object. DMA_LOCK_WRITE puts an exclusive write lock on the object. This prevents other connections from getting a write lock or a read lock on the object. DMA_LOCK_EXIST puts a existence lock on the object. The object cannot be deleted when an existence lock is held, even if deletion attempted by connection holding a write lock. This does not affect acquisition of read or write locks.

A lock is owned by a scratchpad object. A scratchpad object may own at most one lock on its related persistent object. If the scratchpad object already owns a lock of any type on its persistent object, the Lock method will return an error regardless of the value of the lLockType parameter, and the object's old lock will be unaffected.

A lock is removed following any of the events listed below:

-- Invocation of IdmaConnection::RemoveLock on the same scratchpad object.

-- The final IUnknown::Release invocation on the same scratchpad object.

-- Termination of the logical document space connection via which the scratchpad object was obtained

Return Values

IdmaConnection::ExecuteChange

Support for this method is optional.

Syntax
DmaRC IdmaConnection::ExecuteChange (
Dmapv pICallback,
DmaInteger32 lProtectionLevel,
DmaBoolean bRefreshFlag)

Parameters

The ExecuteChange method makes the appropriate changes to the persistent object, whatever they may be: initially create a persistent object, update an existing persistent object, or delete an existing persistent object. The action is determined by the values of the three properties CreatePending, UpdatePending, and DeletePending.

The object is created if CreatePending is TRUE and DeletePending is FALSE.

The existing persistent object is modified if CreatePending is FALSE, UpdatePending is TRUE, and DeletePending is FALSE.

The existing object is deleted if CreatePending is FALSE, and DeletePending is TRUE.

If all three are FALSE, or if both CreatePending and DeletePending are TRUE, the method is a no-op as far as the document space persistent state is concerned, regardless of the value of lProtectionLevel. There shall be no updates to the persistent store as a result of such a no-op, but the bRefreshFlag parameter still has the usual effect on the scratchpad object state.

Here are details on the meaning of the value of the lProtectectionLevel parameter. Each value of the protection level parameter is optionally supported. However, if the ExecuteChange method is supported, then at least one value of the protection level parameter must be supported.

For the creation case, the value of this parameter is irrelevant. The create will succeed, unless there is some unrelated problem, e.g., out of disk space, duplicate key value, etc.

For the deletion case, if the value if this parameter is DMA_MODIFY_PROTECTED, then the delete will fail if the persistent object does not exist and have the same property values as the original property values in the snapshot. The other values of this parameter have no effect on deletions.

For the case of updating an existing object, ExecuteChange fails with DMARC_OBJECT_DELETED if the independently persistent object to be updated does not exist in the persistent store, regardless of the value of the protection level parameter. Otherwise, when updating an existing independently persistent object, each value of the protection level parameter results in different behavior as follows:

-- If the value of the protection level parameter is DMA_MODIFY_UNPROTECTED, then an attempt is made to update the independently persistent object in the persistent store to reflect the changes made to the scratchpad object. The implementation is free to assume that no concurrent updates have been made to the independently persistent object or any of its subobjects, providing only that the independently persistent object still exists. The updates are performed at the finest possible granularity and do not affect any part of the persistent state which is unmodified in the scratchpad object. In the case of lists, only the minimal insertions, deletions, and replacements need be performed. Thus, for example, if a property or list element was deleted from the scratchpad object, it will be deleted from the persistent object, and none of the rest of the state of the persistent object will be altered. In the case of dependently persistent subobjects, this is recursively true. For purposes of this paragraph, "subobject" includes list elements. If any changes to the persistent object have been made in the persistent store that conflict with any changes made to the scratchpad, then the result is undefined. Some modifications may no longer be applicable, and, if this situation is detected, these modifications may be quietly discarded or an error may be returned, at the option of the implementation. Since this value of the protection level parameter provides no protection against concurrent updates to the persistent store, it is recommended that locking be used to protect against concurrent updates (if locking is supported), or, even better, that the protection level value DMA_MODIFY_PROTECTED be used instead (if it is supported).

-- If the value of the protection level parameter is DMA_MODIFY_PROTECTED, the result is effectively the same as if an atomic combination of IsCurrent and DMA_MODIFY_UNPROTECTED were performed: If the independently persistent object is not current in the sense of IsCurrent, then the update fails with DMARC_OBJECT_MODIFIED. Otherwise, it is known that neither the independently persistent object nor any of its dependently persistent subobjects has changed. In that case, the changes made to the scratchpad are applied to the persistent object. The updates are performed at the finest possible granularity and do not affect any part of the state of the persistent object which is unmodified in the scratchpad. It is recommended that clients use this value of the protection level parameter, if it is supported, in preference to using DMA_MODIFY_UNPROTECTED. This value of the protection level parameter provides concurrency protection when updating an object while avoiding the additional overhead that would be incurred by use of the locking and unlocking methods (assuming locking is supported).”

Many more return values are possible from this method than are listed below. They are detailed in individual method descriptions -- see especially any method with "Set" in its name.

Return Values

IdmaConnection::ExecuteRefresh

Support for this method is optional.

Syntax
DmaRC IdmaConnection::ExecuteRefresh ( )

Refreshes the scratchpad object with an up to date snapshot from the persistent store. If successful, any changes made to the scratchpad object prior to this call will be discarded.

If the persistent object no longer exists, the error DMARC_OBJECT_DELETED is returned, and the scratchpad object is unchanged.

If the persistent object exists and is successfully retrieved, the CreatePending, UpdatePending, and DeletePending properties are set to FALSE, FALSE, FALSE. All scalar properties of the scratchpad object are set to match the current state of the persistent store, with the usual consistency guarantees. All object-valued properties are reset to the unbound state.

Return Values

IdmaConnection::IsCurrent

Support for this method is optional.

Syntax
DmaRC IdmaConnection::IsCurrent (
pDmaBoolean pbIsCurrent)

Parameters

Returns DMA_TRUE if the persistent state of the object has not been changed since the IdmaConnection interface was delivered, or the last call to IdmaConnection::ExecuteRefresh, whichever is later.

The method may be conservative and return DMA_FALSE for the value of *pbIsCurrent if there is good reason to believe that the independently persistent object or one of its dependently persistent subobjects may have changed, but determining with certainty whether the object has actually changed is considered to be too expensive. For example, a difference in the value of a change count or epoch field in the independently persistent object is considered to be a sufficiently good reason to believe that the object may have changed. It is not necessary to actually check whether the old and new values of all properties and all other parts of the persistent state have changed. (For example, that might be considered too expensive in the case of content elements and large binary properties.) Note, therefore, that DMA_FALSE might be returned for *pbIsCurrent, even though a property was set to its original value, resulting in no net change. In contrast, being pessimistic and always returning DMA_FALSE for *pbIsCurrent is not acceptable.

Return Values

IdmaConnection::RemoveLock

Support for this method is optional.

Syntax
DmaRC IdmaConnection::RemoveLock ( )

Remove the lock that is held by this connection on the persistent object, making it available to other connections. If there is no lock held on this connection the return code DMARC_NOT_LOCKED will be returned.

Return Values

IdmaConnection::SetDeletePending

Support for this method is optional.

Syntax
DmaRC IdmaConnection::SetDeletePending (
DmaBoolean bDeleteFlag)

Parameters

The value of the DeletePending property is set in the current scratchpad object. This preconditions it so that if the DeletePending property is TRUE, IdmaConnection:: ExecuteChange or IdmaBatch:: ExecuteChanges will delete the persistent object.

Successful operation of this method does not depend on the value of the Delete Pending property.

Return Values

Deferred Return Values