You are here: Reference > Activity methods > Commit

  Commit method

Methods and instructions by function

Use this method to commit all uncommitted database changes. This method writes all the instances specified by one or more earlier Obj-Save methods to the PegaRULES database (for internal classes) and to external databases (for external classes).

Basics

The Commit method operates on Thread pages that can operate across multiple instances. After an object instance is saved into the database, it is persistent.

Use the Rollback method or the Obj-Save-Cancel method to cancel a previous Obj-Save before commit.

NoteDon't use the Commit method in an activity that has an Activity Type of Utility, Route, Assign, Notify, or Integrator. Flow processing performs commits automatically when the flow ends and when an assignment is created or completed. To avoid interference with this approach, do not use Commit in the flow-related activities in your application. (When you save an activity that uses Commit, if the Applies To key part of the activity is derived from the Work- base class, a warning message appears).

Most database updates require that the requestor hold a lock on the object. Typically a requestor acquires this lock when the requestor first opens the object with the Obj-Open, Obj-Open-By-Handle, or Obj-Refresh-and-Lock method. Note these two exceptions:

Parameters

The Commit method has no parameters.

Results

The system commits all deferred write operations (including deletes) for this requestor in the queue to the database. If any of the writes fail, they all fail.

Commit operations can trigger the execution of Declare Trigger rules. The system updates indexes as required by executing Declare Index rules.

All locks held by the requestor Thread (except those that were acquired with the ReleaseOnCommit box not selected in the Obj-Open method) are released.

Any clipboard pages which hold objects retrieved through linked property processing are deleted, as potentially stale.

Checking the method status

This method updates the pxMethodStatus property. See How to test method results using a transition.

When a deferred — that is, non-immediate — Obj-Save or Obj-Delete method fails, the next Commit method will also fail unless one of the following is performed successfully before the Commit method is attempted again:

CautionIf during the database save, any of the four properties listed below contain a value that is wider than the corresponding database column, the Commit method fails. The system associates the message Database-ColumnTruncated with the property in error. (This message begins "Property Zzzzz has been truncated...")

If any property other than these four properties contains a value that is longer than the width of the database column, the system associates a warning message Database-BadTableMapping-KeyPropertyTooBig with the property and returns a warning status. The database is updated and data for the column is truncated to fit. The system changes the last character of the truncated value to a plus sign (+) character, as a more enduring indication of this problem in case the warning message is missed or ignored.

Java EE two-phase Commit support

In a Java EE application server setting, the JTA transaction aspects of this method depend on how the PRPC system is deployed. If your system is deployed appropriately in the Enterprise tier of a Java EE application server, a Commit operation can be processed as a full Java Transaction API (JTA) transaction. This is useful when objects are saved to more than one database,

For example a single Commit operation may update both the PegaRULES database and an external database (made visible through the External Database Table wizard).

Troubleshooting deferred write operations

As a debugging aid, the standard HTML rule @baseclass.DeferredOps interrogates system internals and presents an ordered list of deferred (uncommitted) database operations for the current Thread. In a step immediately before a Commit method, your activity can display this HTML rule using the Show-Page method, to see what will be committed.

Design consideration and notes

Performance statistics

Three statistics in the Full Details display of the Performance tool report on Commit operations from your requestor session

Additional resources

For more information about JTA operation, see Distributed Transactions and PegaRULES Process Commander, a file on the PDN.

Definitions external class, Java Transaction API, two-phase commit
Related topics About Declare Index rules
About Declare Trigger rules
Obj-Save method
Obj-Save-Cancel method
Rollback method
Understanding locking and transactions during flow executions

UpMethods and instructions by function