Obj-Delete-By-Handle method
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.
Parameters
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. |
Results
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.
Fail and Warn conditions
These situations cause the method status to be
Fail
or Warn:
- Lock
is selected, the class rule enables locking, but a lock
cannot be acquired because another requestor session holds the lock (
Fail - Database LockFailure - LockHeldByAnother
.) - The InstanceHandle parameter identifies an instance that does not exist (Fail).
- Lock is selected, but the class rule does not allow locking (Warn). The object is deleted.
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.
This method cannot be used in a step that involves iteration.
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-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:
- Another deferred Obj-Delete-By-Handle (or Obj-Save) method is performed on the instance
- An Obj-Save-Cancel is performed
- A Rollback method is performed
Previous topic Obj-Delete method Next topic Obj-Filter method