This interface provides the ability to reserve and checkout versions of versionable objects (initially Document Versions) in DMA. It also provides a method to revoke (cancel) reservations and checkouts.
This interface is only present when the IdmaConnection interface is also present. The operations are specific to persistent objects and don’t apply to any other forms of Version Series object.
Support for this method is optional.
Syntax
DmaRC IdmaVersionSeries::SetCheckOutNext (
Dmapv pReservation)
Parameters
Name | Mode | Description |
pReservation | input | Pointer to an interface of a new, unsaved reservation object |
Records the intention to reserve the right to check-in the next new current versionable object in this series.
Following ExecuteChange on the Version Series the persistent state of the Version Series is updated and a new Reservation object and a new working Versionable object are created in the persistent store.
The Reservation property of the persistent Version Series object will be updated to refer to the new Reservation object.
The Reserved For property of the persistent Reservation object will refer to the Version Series object, the New Version property will refer to the working Versionable object and any extended properties will be set to reflect the extended properties of the Reservation object at the time of the ExecuteChange call.
The working Versionable object is a clone of the current Versionable object in the version series. The Reservation and cloned versionable object can be found through navigation from the "Reservation" property of the Version Series
When the versionable object is "cloned", the versionable object and all dependent persistable subordinate objects are copied recursively. Cloning sets the navigation properties to null but preserves other properties with the exception of the OIID which is given a new value.
The major purpose in providing Checkout in addition to Reserve is to allow the Document Space to optimize the work associated with ‘cloning’ the Document Version, particularly the content data.
A reservation can be resolved with a check-in, or can be revoked. Revoking a reservation created by SetCheckOutNext does not delete the NewVersion object.
Return Values
Name | Description |
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_CONFLICTING_OPERATION | The call on this primary intentional method logically conflicts with a prior call on a different primary intentional method. |
DMARC_NO_MEMORY | (E_OUTOFMEMORY) Insufficient memory to complete the operation. |
DMARC_NOT_SUPPORTED | This method is not supported in the context of this session or object. |
DMARC_OK | (S_OK) Success. |
DMARC_RESERVATION_PENDING | The connection is already holding a request for a reservation. There cannot be more than one at a time. |
Deferred Return Values
Name | Description |
DMARC_NO_CURRENT_VERSION | The version series has no current version. |
DMARC_OBJECT_LOCKED | The lock(s) on the persistent object prohibit the attempted operation. |
DMARC_OBJECT_MODIFIED | The object has been modified since it was retrieved. |
DMARC_RESERVATION_EXISTS | The version series is already holding a reservation. |
DMARC_RESERVATION_NOT_ALLOWED | The condition of the version series does not permit a reservation, though no reservation is currently present. |
This method must be supported in every implementation of this interface.
Syntax
DmaRC IdmaVersionSeries::SetReserveNext (
Dmapv pReservation)
Parameters
Name | Mode | Description |
pReservation | input | Pointer to an interface of a new, unsaved reservation object |
Records the intention to reserve the right to check-in the next new current versionable object in this series.
Following ExecuteChange on the Version Series the persistent state of the Version Series is updated and a new Reservation object is created in the persistent store.
The Reservation property of the persistent Version Series object will be updated to refer to the new Reservation object.
The Reserved For property of the persistent Reservation object will refer to the Version Series object, the New Version property (if supported) will be NULL, and any extended properties will be set to reflect the extended properties of the Reservation object at the time of the ExecuteChange call.
Unlike SetCheckOutNext, SetReserveNext does not create a clone of the versionable object.
A reservation can be resolved with a check-in, or can be revoked.
Return Values
Name | Description |
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_CONFLICTING_OPERATION | The call on this primary intentional method logically conflicts with a prior call on a different primary intentional method. |
DMARC_NO_MEMORY | (E_OUTOFMEMORY) Insufficient memory to complete the operation. |
DMARC_OK | (S_OK) Success. |
DMARC_RESERVATION_PENDING | The connection is already holding a request for a reservation. There cannot be more than one at a time. |
Deferred Return Values
Name | Description |
DMARC_ACCESS_DENIED | (E_ACCESSDENIED) The requester has insufficient access rights to perform the requested operation. |
DMARC_OBJECT_LOCKED | The lock(s) on the persistent object prohibit the attempted operation. |
DMARC_OBJECT_MODIFIED | The object has been modified since it was retrieved. |
DMARC_RESERVATION_EXISTS | The version series is already holding a reservation. |
DMARC_RESERVATION_NOT_ALLOWED | The condition of the version series does not permit a reservation, though no reservation is currently present. |
This method must be supported in every implementation of this interface.
Syntax
DmaRC IdmaVersionSeries::SetRevoke ( )
Records the intention to cancel an existing CheckOut or Reservation for the Version Series object. On successful completion of this method and one of the ExecuteChange(s) methods the Reservation property of the series is set to NULL and the Reservation object formerly pointed to is deleted.
If the Reservation was created by SetCheckOutNext, the cloned NewVersion object (created as a result of that method call) is NOT deleted. If the NewVersion should be deleted, then the application must explicitly delete the object (which is pointed to by the Reservation’s NewVersion property).
This method will not fail because there is a SetRevoke already pending.
Return Values
Name | Description |
DMARC_CONFLICTING_OPERATION | The call on this primary intentional method logically conflicts with a prior call on a different primary intentional method. |
DMARC_OK | (S_OK) Success. |
Deferred Return Values
Name | Description |
DMARC_NO_RESERVATION | The Version Series is not holding a reservation at this time. |