Commitment Control

The IBM i operating system provides a facility called "commitment control" that allows programs to define database transaction boundaries.

When a database transaction is in progress, all changes to the database are considered to be "temporary" until the transaction boundary is reached. At the boundary, the program may choose to COMMIT the changes to the database, or ROLLBACK the changes to the last completed transaction boundary (thus removing them from the database).

If the job should end before reaching the transaction boundary, the operating system will automatically ROLLBACK to the last completed transaction boundary, thus removing any incomplete transactions from the database. For interactive jobs, the job begins when the user signs on and finishes with the job ending abnormally, or the user signing off.

It is possible to define and use database files within LANSA that are under IBM i commitment control. However, before doing this you should consider the following points:

• Commitment control is a native part of the operating system  
  You should read all available IBM supplied documentation before attempting to use commitment control in LANSA. There is nothing special about the LANSA implementation of commitment control, it just uses the standard facilities provided by the operating system. Generally, when problems occur they can be traced to non-compliance with the operating system requirements, rather than to LANSA.

• Using commitment control may use up more computer resources  
  You should consider this feature of commitment control before attempting to implement it on a large scale.

• When a file is defined to LANSA, an I/O module is created for the file. All LANSA I/O to the file is via the I/O module. It is the I/O module that provides the commitment control support. When an I/O module performs one of the following operations against a file (even a logical file) it always uses the associated / underlying physical file. It is the physical file that LANSA defines as being under commitment control. This feature should be considered with regard to the records that are locked when using commitment control.
  Affected operations are:

• write

• update

• delete

• read with locking

• read via relative record number.

• When using commitment control you must begin journaling the associated physical file outside of LANSA. Refer to the IBM i operating system commands STRJRNPF (start journaling physical files) and ENDJRNPF (end journaling physical files) for details.

• When attempting to make operational changes to a file definition that is being journaled it may be necessary to end journaling beforehand. Failure to do this may cause the "make operational" batch job to fail because it cannot allocate the file for exclusive use.

• After making operational changes to a file definition that uses journaling it will be necessary to begin journaling again.

• LANSA does not directly support access path journaling. If you have this requirement please contact your product vendor.

If the commitment control options available when setting up a file definition are used, they specify that a file is under commitment control all the time in all applications. In this situation, the starting and ending of commitment control is the responsibility of the programmer.

• When using commitment control on the IBM i you must issue a STRCMTCTL command (start commitment control) before accessing LANSA. The STRCMTCTL command is part of the IBM i operating system.

• When using commitment control on the IBM i you must issue an ENDCMTCTL command (end commitment control) after exiting LANSA. The ENDCMTCTL command is part of the IBM i operating system.

• To selectively override commitment control for all files subject to modification by a function, specify FUNCTION OPTIONS(*NOPGMCOMMIT). The function will NOT be under commitment control - all individual file definition options regarding commitment control are overridden and superseded.

*PGMCOMMIT

To selectively use commitment control within just one function, you can use the FUNCTION OPTIONS(*PGMCOMMIT) command to specify function level commitment control is required. When this option is used, all files subject to modification by the function are automatically placed under commitment control. Commitment control is automatically started and ended by the program. All individual file definition options regarding commitment control are overridden and superseded when using this option.

• When a function fails through the *ABORT value for an RDML keyword or the execution of the ABORT RDML command, the user exit F@ENDCMT is called. As supplied, this consists of the IBM i command ENDCMTCTL. When this is executed with pending changes in an interactive job, the user is sent an inquiry message with the options to roll back the pending changes, cancel the ENDCMTCTL or commit the pending changes. When this is executed with pending changes in a non-interactive job, the pending changes are implicitly rolled back.

• When a function fails through any other reason, commitment control is left active with any pending changes. When the job ends, whether normally or abnormally, the pending changes are implicitly rolled back.

Under certain circumstances, LANSA automatically starts and ends commitment control using User Exit F@BGNCMT - Start Commitment Control and User Exit F@ENDCMT - End Commitment Control. This happens for:

• Functions with OPTIONS(*PGMCOMMIT).

• SuperServer jobs when Start Commitment Control is set to Y or 1.

• LANSA Open jobs when LceSetCommitmentOn has been called before opening the session.

• LANSA Open for .Net jobs when the Session's CommitmentControlOnServer property is True on connection.