Commit method

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.

Don'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:

• A lock is not required for the first-ever commit operation of a newly created object.
• A lock is not required for objects of classes that don't support locking.

The Commit method has no parameters.

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.

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:

• Another deferred Obj-Delete (or Obj-Save) method is performed on the instance
• An Obj-Save-Cancel is performed
• A Rollback method is performed

If 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...")

• pxObjClass
• pxInsName
• pzInsKey
• pyClassName

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.

In a J2EE application server setting, the JTA transaction aspects of this method depend on how the Process Commander system is deployed. If your system is deployed appropriately in the Enterprise tier of a J2EE 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).

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.

When you include the Commit method in an activity, design the processing so that the Commit method occurs only after errors are intercepted, checked, and corrected. If a Commit method fails, it is unlikely that processing can continue in any reasonable way, so it is important to include a transition in the Commit step that checks the status.

Even when processing can continue after Commit failure, design your activity (after debugging and fixing the cause of the failure) to collect any required user input that corrects the problems, and re-perform any Obj-Save methods that preceded the Commit call.

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

• Elapsed time writing to the database (property Code-Pega-PAL.pxCommitElapsed)
• Database Commit Count (property Code-Pega-PAL.pxCommitCount)
• Database Rows Committed (property Code-Pega-PAL.pxCommitRowCount)

If your system accesses the PegaRULES database using an updated JDBC 2.0 driver, enabling an optional driver capability for batched updates may improve database performance. This benefit also applies to external databases when they are accessed as external classes.

Not all JDBC 2.0 drivers correctly implement this capability. As of May 2007, Pegasystems has verified this capability with specific drivers including UDB 9.1 and Z/OS DB2. Other vendors are reportedly addressing compliance. Contact Global Customer Support for the latest information.

To allow Process Commander to use SQL prepared statements to batch updates for improved performance on row inserts, updates, and deletes:

1. To enable this feature for every SQL database, add the following line to the prconfig.xml file:

<env name="database/batchUpdates" value="nn" />

        where nn is a positive integer setting a maximum count for the number of rows to be batched.

2. To enable this feature for a single SQL database that is configured through the prconfig.xml file, add the following line:

<env name="database/databases/zzzzzz/batchUpdates" value="nn" />

        where nn is a positive integer setting a maximum count for the number of rows to be batched and zzzzzz is the name of the datasource. (You can't use this option when the database is configured on the Database form or through application server datasources.)

3. Redeploy and restart.

Typically, set a value between 5 and 30; vendor documentation and experimentation may provide guidance for a good value. Setting this value to 0 or 1 is equivalent to no batching.

When enabled, this feature applies to all processing — including any Commit operations of two or more objects — but may improve the performance of bulk processing by as much as 20 percent.

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