Use the Obj-Delete-by-Handle method to delete an instance identified by its handle. This method executes the operations of the Obj-Open-By-Handle method followed (if successful) the Obj-Delete method.
Unlike the Obj-Delete method, the Obj-Delete-By-Handle method does not require that the instance be open on the clipboard. Using Obj-Delete-By-Handle, you can delete it without first opening the object.
This method has five parameters:
Parameter |
Description |
| InstanceHandle |
Enter the handle that identifies the instance to be opened as a literal or a property reference. This corresponds to the value of the pzInsKey property for an internal class, and a simulated handle for an external class. Because the handle is lengthy and not easily displayed, it is often easier to identify it by a property reference, rather than attempt to enter the handle by typing. |
| Lock |
If the class allows locking, a lock will be required to delete the object. Select this option to obtain the lock when executing the Obj-Delete-By-Handle method. If the instance is already locked at the time Obj-Delete-By-Handle is called, you can leave this option cleared. If selected, but the class does not allow locking, the Obj-Delete-By-Handle method deletes the instance but produces a warning: As a best practice, select this box if the object belongs to a class that allows locking. |
| Release on Commit |
Select this box to cause a lock held by your requestor to be released when your changes are completed through the Commit method. In most cases, select this box if you selected the Lock box. In the unusual case that you want to retain the lock after Commit (perhaps because additional changes are expected), your activity can later use the Page-Unlock method to release the lock. |
| LockInfoPage |
Optional. As a debugging aid, identify the name of a page to be created by this method to hold the results of the locking attempt when it fails. The page, of class System-Locks, contains the following properties:
If the Obj-Delete-By-Handle fails to acquire a lock, this page is created and can be viewed with the Clipboard tool or the Tracer. By convention, this page is named |
| Immediate |
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. |
If the Lock check box is selected, the system attempts to acquire a lock on the object. This attempt does not require the object to be opened. If Lock is selected, the class supports locking, but the lock cannot be acquired, the method fails.
Next, if Immediate is selected, the method deletes the instance from the clipboard and from the PegaRULES database. If Immediate is not selected, the deletion operation is queued until the next Commit occurs.
These situations cause the method status to be Fail or Warn:
Fail - Database LockFailure - LockHeldByAnother)Use the Obj-Delete-By-Handle method only if you can determine the unique handle that permanently identifies which instance to delete. The handle of an instance is a unique key, in an internal format, assembled by the system that identifies an instance in the PegaRULES database. It may differ from the visible key generally used to identify instances. (Every instance has a unique handle, but more than one instance may share the same visible key.) For rule instances, the handle includes system-generated identifying values (including the create date and time) that make it unique.
This method does not access or depend on any information in the Step Page field of the step. To avoid a warning message, leave the Step Page field blank.
You can reverse or cancel a previously executed Obj-Delete-By-Handle method by using the Obj-Save-Cancel method, unless the Immediate box is selected or the Commit method has already occurred.
If you use the Obj-Delete-By-Handle method in an activity with Activity Type of Trigger, do not check the Immediate check box.
Do not use Obj-Delete-By-Handle method on instances in a class derived from the Index- base class. Use only Declare Index rules to delete these instances.
This method cannot be used in a step that involves iteration.
This method updates the pxMethodStatus property. See How to test method results using a transition.
When a deferred — that is, non-immediate — Obj-Delete-By-Handle method fails, the next Commit method will also fail unless one of the following is performed successfully before the Commit method is attempted: