The API is designed for straightforward logic flows and clear transitions between the various states of the application client. This clean state transition catches logic flaws and program errors early in the development cycle, greatly enhancing the quality and reliability of the system.
For example, you cannot make a dsmSendObj call unless a transaction was started and a dsmBindMC call was previously made for the object that you are backing up.
Figure 1 displays the state diagram for performing backup or archive operations within a transaction. The arrow pointing from "In Send Object" to dsmEndTxn indicates that a dsmEndTxn call can be started after a call to dsmSendObj or dsmSendData. You might want to do this if an error condition occurred during the send of an object and you want to stop the entire operation. In this case, you must use a vote of DSM_VOTE_ABORT. In normal circumstances, however, call dsmEndSendObj before you end the transaction.
Figure 2 displays the flowchart for performing backup or archive operations within a transaction.
The primary feature in these two diagrams is the loop between the following API calls from within a transaction:
- dsmBindMC
- dsmSendObj
- dsmSendData
- dsmEndSendObj
The dsmBindMC call is unique in that you can start it from inside or outside of a transaction boundary. You can also start it from a different transaction, if required. The only requirement for the dsmBindMC call is that it is made prior to backing up or archiving an object. If the object that you are backing up or archiving is not associated with a management class, an error code is returned from dsmSendObj. In this situation, the transaction is ended by calling dsmEndTxn (this error condition is not shown in the flowchart).
The flowchart illustrates how an application would use multiple object transactions. It shows where decision points can be placed to determine if the object that is sent fits within the transaction or whether to start a new transaction.