Structuring your application for commit and backout

Before invoking commit or backout for a unit of recovery, your application program should complete all I/O for the unit of recovery. To commit data, all changes must be saved. If your application program neglects to save the changes, DFSMStvs ensures that they are saved for you.

Recommendation: For best performance, however, an application should not rely on DFSMStvs to save the changes. Also, it is possible that an attempt by DFSMStvs to save the data could fail. If a save attempt fails, DFSMStvs cannot guarantee that all of the data was put on DASD and will back out the unit of recovery, regardless of whether the user issued a commit or a backout.

Other considerations follow:

If your application program issues ENDREQs or CHECKs, ensure that the ENDREQs or CHECKs complete before invoking commit or backout processing.
Never invoke a commit or backout from the RLSWAIT exit or from OPEN or EOV exits.
Be aware that a commit or a backout normally releases all of the locks held by a unit of recovery.
An application can successfully close a data set while it has an in-flight unit of recovery that modified the data set, but this is not recommended. If this is the last close of the data set on this system, RLS converts all of the locks held by the unit of recovery for the data set from active locks to retained locks. This causes any other units of recovery that attempt to get those locks to receive a retained lock reject instead of waiting for the lock to become available. In addition, the data written to the data set during the unit of recovery is not committed or backed out until the unit of recovery issues a commit or backout. An implicit commit occurs when a job ends normally for in-flight units of recovery; an implicit backout occurs when a job abnormally ends for in-flight units of recovery.
Recommendation: Do an explicit commit before closing a data set.

If you close a data set that has active locks for an in-flight unit of recovery before it issues a commit or backout and your close is the last close on the system for the data set, RLS changes all of your active locks into retained locks. After that happens, another user who opens the data set and attempts to process any of the records that you have locked receives a retained lock rejection instead of waiting for the lock to become available.
DFSMStvs never invokes commit or backout processing directly for in-flight or in-doubt units of recovery during normal processing. (However, it might do so during restart processing for failed units of recovery.)
Applications can choose to attempt to commit data after a failure, such as an error that was returned by VSAM. However, if DFSMStvs determines that the error might have affected data integrity, it responds negatively during commit phase 1 (prepare). DFSMStvs then requires the unit of recovery to be backed out.
For example, an application might attempt to commit data after an I/O error on either the data set or the system undo log. Before the commit, DFSMStvs determines that the data is not in a consistent state and requires a backout instead.
Applications can choose to attempt to commit the data after a failure against a forward recovery log. This failure does not affect the success of the commit process.
Recommendation: After the data is committed, back up the data set before continuing. Without a backup, you might lose the ability to recover the data set because its forward recovery log is damaged.
Failures that occur during commit phase 1 (prepare) result in the unit of recovery being backed out. Failures that occur during commit phase 2 do not result in the unit of recovery being backed out. The commit is retried at a later time.
A failure that prevents completion of a sync point causes DFSMStvs to shunt those portions of the unit of recovery that DFSMStvs cannot finish processing. I/O errors or unavailability of a resource are examples of failures that prevent completion of a sync point.
All shunted transactions are automatically retried by DFSMStvs every 15 minutes until the retry is successful. For each transaction that is successfully retried, DFSMStvs issues message IGW892I. You can also manually retry a shunted transaction, using the access method services SHCDS command.

Because DFSMStvs automatically retries transactions that are in the shunt log, you need to make sure that the log does not contain anything that cannot be retried. For example, if you delete a data set for which recovery is owed, VSAM RLS releases all of the locks associated with the data set. Suppose you then allocate a data set with the same name as the deleted data set. If the shunt log still contains outstanding work for the deleted data set, DFSMS might automatically retry this work on the new data set of the same name, without any locks.

Recommendation: Before you delete a data set, use the the SHCDS PURGE command to rid the shunt log of any outstanding work for the data set.

Various levels of authorization are required to use the SHCDS parameters.