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: Database-LockFailure-NotSupported.

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:
  • pxOwnerID — requestor who holds the lock.
  • pxExpireDateTime — date and time the lock will go soft.
  • pxUpdateOperator — pyUserIdentifier value for the requestor who holds the lock.
  • pxLockHandle — text string that defines the lock.

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 LockInfo in standard rules. When a lock failure occurs during a flow execution, the flow can display the standard harness Work-.LockInfo (or a similar harness incorporating the standard section System-Locks.LockInfo ) to report the situation. If the lock not acquired is held by the same user in a separate requestor session, the user can click the Release Lock button to relinquish it.

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.

CAUTION:
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.

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