Use the Obj-Delete method to delete a database instance corresponding to a clipboard page and optionally to delete the clipboard page too. You can cause the deletion to occur immediately, or (more commonly) defer deletion until a later execution of a Commit method.
This method can operate on objects of both internal classes (corresponding to rows in a table in the PegaRULES database) and external classes (corresponding to rows in an external relational database).
The Obj-Delete method uses the class of the page to obtain the appropriate Rule-Obj-Class instance. It uses the table name, key fields, and other aspects of the class rule to mark the instance for deletion. Unless you check the Immediate check box on the activity form, the database deletion does not occur until the system next processes the Commit method.
You can reverse or cancel a previously executed Obj-Delete method by using the Obj-Save-Cancel method (like the method Obj-Save can be reversed), unless the Immediate box is selected or the Commit method has already occurred.
If you use the Obj-Delete method in an activity with Activity Type of Trigger, do not check the Immediate check box.
Do not use Obj-Delete method on instances in a class derived from the Index- base class. Use only Declare Index rules to delete these instances.
Use the Obj-Delete-By-Handle method, not the Obj-Delete method, when the object is not open on your clipboard and the object handle (pzInsKey value) is known. The Obj-Delete-By-Handle method combines the Obj-Open-By-Handle method and the Obj-Delete method in a single step, making your activity shorter.
This method has two parameters:
Parameter |
Description |
| Remove |
If selected, the system deletes the page identified in the Step Page column of this step from your clipboard and marks the corresponding persistent instance for deletion. |
| Immediate |
If selected, the system deletes the database instance immediately (commits this deletion). To delete the database instance immediately from the database, select this box. If this box is cleared, the database instance is deleted by the next Commit operation. |
The system finds the clipboard page identified in the Step Page column of the current step and checks whether it the current requestor holds a lock on the corresponding object.
If the object is not locked (and the class rule allows locking), the method fails and no clipboard or database changes occur.
If the page is locked and the Remove parameter is selected, the system deletes the page. It marks the persistent object in the database for deletion, or deletes it immediately, depending on the Immediate parameter.
The system automatically performs index processing for an immediate delete, or later when a Commit method follows the Obj-Delete method.
These situations cause the method status to be Fail or Warn.
You cannot delete an instance without locking it first (usually with the Obj-Open method). You cannot delete an instance while it is locked by another requestor.
As a debugging aid, the standard HTML rule @baseclass.DeferredOps interrogates system internals and presents an ordered list of non-immediate (uncommitted) database operations, including Obj-Delete operations. Your activity can display this HTML rule using the Show-Page method.
This method updates the pxMethodStatus property. See How to test method results using a transition.
When a deferred — that is, non-immediate — 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: