The terms commit and rollback include all methods of commit and rollback available on the system, such as:
A commitment resource is any part of the system that is used by a process and placed under commitment control. When a part of the system is put under commitment control by the Add Commitment Resource (QTNADDCR) API, that resource can be referred to as an API commitment resource.
API commitment resources are processed by the system during:
When commitment control is started using the Start Commitment Control (STRCMTCTL) command, the system creates a commitment definition that is scoped to a particular activation group or to the job as indicated on the commit scope (CMTSCOPE) keyword.
Each group of committable changes is intended to be an atomic operation. Each group can be committed (changes are made permanent to the system) or rolled back (changes are permanently removed from the system) and is referred to as a logical unit of work. The first logical unit of work begins when commitment control is started. Each commit and rollback completes the current logical unit of work and starts a new one.
A commitment definition saves internal control information pertaining to the resources under commitment control. This internal control information is maintained as the state of those commitment resources changes, until that commitment definition is ended using the End Commitment Control (ENDCMTCTL) command. A commitment definition generally includes:
The Example Using Selective Commitment Control APIs shows how some of the commitment control APIs can be used together. First, the Retrieve Commitment Information (QTNRCMTI) API is used by the high-level language (HLL) program to determine if commitment control is active within the activation group for the HLL program. If the activation-group-level commitment definition is already active, then the status retrieved by the API will be with respect to that activation-group-level commitment definition. If the activation-group-level commitment definition is not active, but the job-level commitment definition is active, then the status retrieved by the API will be with respect to the job-level commitment definition. If status is being retrieved for the job-level commitment definition, then information from a second status field returned by the API can be used to determine whether programs that have run within the activation group have already used the job-level commitment definition. If no program running within the activation group has used the job-level commitment definition, then an activation-group-level commitment definition may be started by the HLL program.
Example Using Selective Commitment Control APIs
Note: Programs running within a single activation group may use the activation-group-level or the job-level commitment definition, but cannot use both definitions concurrently. Two programs running within different activation groups may each use a separate activation-group-level commitment definition, or one or both programs may use the job-level commitment definition.
Once a commitment definition has been established for the HLL program, the Add Commitment Resource (QTNADDCR) API is used to add one or more commitment resources to the commitment definition. When a commit or rollback operation is performed to complete a transaction for this commitment definition, the system performs the commit or rollback operation for all record-level and object-level resources. It also calls an exit program, as identified by the HLL program when the API commitment resource was added, for each API commitment resource.
The Example Using Selective Commitment Control APIs shows one call to each exit program during commit and rollback operations. This is the case for one-phase resources. For two-phase resources, up to three calls are made during commit operations, and up to two calls are made during rollback operations. See Add Commitment Resource (QTNADDCR) API for more information about one-phase and two-phase commitment resources.
After all the desired logical units of work are completed by the HLL program, the Remove Commitment Resource (QTNRMVCR) API must be used to remove each of the commitment resources added to the commitment definition before the commitment definition can be ended by the End Commitment Control (ENDCMTCTL) command. However, if an activation-group-level commitment definition is being used and the activation group is ended when the HLL program returns, then any API commitment resources are implicitly removed by the system and the activation-group-level commitment definition is automatically ended by the system. Prior to the system implicitly removing the API commitment resources and automatically ending the activation-group-level commitment definition, an implicit commit or rollback operation is performed by the system if pending changes exist for the commitment definition, with the appropriate exit program calls made for any API commitment resources. An implicit commit is performed by the system if the activation group is ending normally. An implicit rollback is performed by the system if the activation group is ending abnormally.
Note: The implicit end performed by the system for activation-group-level commitment definitions does not apply for the default activation group. This is because the default activation group is never ended when a program running within it returns. The default activation group persists for the life of the job.
Regardless of the scope for a particular commitment definition, any pending changes for a commitment definition at process end or during IPL recovery processing are always rolled back. This is true unless the process or system ended in the middle of a commit operation for that commitment definition. In that case, the commit operation is completed for the commitment definition.
[ Back to top | Journal and Commit APIs | APIs by category ]