The scope of a commitment definition determines which programs will use that commitment definition, and how locks acquired during transactions are scoped.
The interface that starts the commitment definition determines the scope of the commitment definition. There are four possible scopes for a commitment definition, which fall under two general categories:
Commitment definitions with job-scoped locks
- Activation-group-level commitment definition
- Job-level commitment definition
- Explicitly named commitment definition
Commitment definitions with transaction-scoped locks
- Transaction scoped commitment definition
Commitment definitions with job-scoped locks can be used only by programs that run in the job that started the commitment definitions. In comparison, more than one job can use commitment definitions with transaction-scoped locks.
Applications typically use either activation-group-level or job-level commitment definitions. These commitment definitions are created either explicitly with the Start Commitment Control (STRCMTCTL) command, or implicitly by the system when an SQL application runs with an isolation level other than *NONE.
Activation-group-level commitment definition
The most common scope is to the activation group. The activation-group-level commitment definition is the default scope when the STRCMTCTL command explicitly starts the commitment definition, or when an SQL application that runs with an isolation level other than No Commit implicitly starts the commitment definition. Only programs that run within that activation group use that commitment definition. Many activation-group-level commitment definitions can be active for a job at one time. However, each activation-group-level commitment definition can be associated only with a single activation group. The programs that run within that activation group can associate their committable changes only with that activation-group-level commitment definition.
When iSeries™ Navigator, the Work with Commitment Definitions (WRKCMTDFN) command, the Display Job (DSPJOB) command, or the Work with Job (WRKJOB) command displays an activation-group-level commitment definition, these fields display the following information:
- The commitment definition field displays the name of the activation group. It shows the special value *DFTACTGRP to indicate the default activation group.
- The activation group field displays the activation group number.
- The job field displays the job that started the commitment definition.
- The thread field displays *NONE.
Job-level commitment definition
A commitment definition can be scoped to the job only by issuing STRCMTCTL CMTSCOPE(*JOB). Any program running in an activation group that does not have an activation-group-level commitment definition started uses the job-level commitment definition, if it has already been started by another program for the job. You can only start a single job-level commitment definition for a job.
When iSeries Navigator, the Work with Commitment Definitions (WRKCMTDFN) command, the Display Job (DSPJOB) command, or the Work with Job (WRKJOB) command displays a job-level commitment definition, these fields display the following information:
- The commitment definition field displays the special value *JOB.
- The activation group field displays a blank.
- The job field displays the job that started the commitment definition.
- The thread field displays *NONE.
For a given activation group, the programs that run within that activation group can use only a single commitment definition. Therefore, programs that run within an activation group can either use the job-level or the activation-group-level commitment definition, but not both at the same time. In a multi-threaded job that does not use SQL server mode, transactional work for a program will be scoped to the appropriate commitment definition with respect to the activation group of the program, regardless of which thread performs it. If multiple threads use the same activation group, they must cooperate to perform the transactional work and ensure that commits and rollbacks occur at the correct time.
Even when the job-level commitment definition is active for the job, a program can still start the activation-group-level commitment definition if no program running within that activation group has performed any commitment control requests or operations for the job-level commitment definition. Otherwise, you must first end the job-level commitment definition before you can start the activation-group-level commitment definition. Commitment control requests or operations for the job-level commitment definition that can prevent the activation-group-level commitment definition from being started include:
- Opening (full or shared) a database file under commitment control.
- Using the Add Commitment Resource (QTNADDCR) API to add an API commitment resource.
- Committing a transaction.
- Rolling back a transaction.
- Adding a remote resource under commitment control.
- Using the Change Commitment Options (QTNCHGCO) API to changing commitment options.
- Bringing the commitment definition to a rollback required state using the Rollback Required (QTNRBRQD) API.
- Sending a user journal entry that includes the current commit cycle identifier by using the Send Journal Entry (QJOSJRNE) API with the Include Commit Cycle Identifier parameter.
Likewise, if the programs within an activation group are currently using the activation-group-level commitment definition, the commitment definition must first be ended before programs running within that same activation group can use the job-level commitment definition.
When opening a database file, the open scope for the opened file can be either to the activation group or to the job with one restriction: if a program is opening a file under commitment control and the file is scoped to the job, then the program making the open request must use the job-level commitment definition.
Explicitly-named commitment definition
Explicitly-named commitment definitions are started by the system when it needs to perform its own commitment control transactions without affecting any transactions used by an application. An example of a function that starts these types of commitment definitions is the problem log. An application cannot start explicitly-named commitment definitions.
When iSeries Navigator, the Work with Commitment Definitions (WRKCMTDFN) command, the Display Job (DSPJOB) command, or the Work with Job (WRKJOB) command display an explicitly-named commitment definition, these fields display the following information:
- The commitment definition field displays the name given to it by the system.
- The activation group field displays a blank.
- The job field displays the job that started the commitment definition.
- The thread field displays *NONE.
Transaction-scoped commitment definitions
Transaction-scoped commitment definitions are started with the XA APIs for Transaction Scoped Locks.
These APIs use commitment control protocols that are thread based or SQL connection based, and not activation group based. In other words, the APIs are used to associate the commitment definition with a particular thread or SQL connection while the transactional work is performed, and to commit or rollback the transactions. The system attaches these commitment definitions to the threads that perform the transactional work, with respect to the API protocols. They can be used by threads in different jobs.
When iSeries Navigator, the Work with Commitment Definitions (WRKCMTDFN) command, the Display Job (DSPJOB) command, or the Work with Job (WRKJOB) command display a transaction-scoped commitment definition, these fields display the following information:
- The commitment definition field displays the special value *TNSOBJ.
- The activation group field displays a blank.
The job field displays the job that started the commitment
definition. Or, if the commitment definition is currently attached to a thread,
the thread's job is displayed.
- The thread field displays the thread to which the commitment definition is attached (or *NONE if the commitment definition is not currently attached to any thread).