Deleting Saved Objects

The %DeleteId() Method

The %DeleteId() method deletes an object that is stored within a database, including any stream data associated with the object. The signature of this method is as follows:

classmethod %DeleteId(id As %String, concurrency As %Integer = -1) as %Status

Where:

• id is the ID of the object to open.

  In these examples, the ID is an integer. You can instead define a class so that the ID is instead based on a unique property of the object.

• concurrency is the concurrency level (locking) used when deleting the object.

For example:

Set sc = ##class(MyApp.MyClass).%DeleteId(id)

%DeleteId() returns a %StatusOpens in a new tab value indicating whether the object was deleted or not.

%DeleteId() calls the %OnDelete() callback method (if present) before deleting the object. %OnDelete() returns a %StatusOpens in a new tab value; if %OnDelete() returns an error value, then the object will not be deleted, the current transaction is rolled back, and %DeleteId() returns an error value.

%DeleteId() calls the %OnAfterDelete() callback method (if present) after deleting the object. This call occurs immediately after %DeleteData() is called, provided that %DeleteData() does not return an error. If %OnAfterDelete() returns an error, then the current transaction is rolled back, and %DeleteId() returns an error value.

Lastly, %DeleteId() calls the %OnDeleteFinally() callback method, if present. This callback method is called after the transaction has completed and the status of the deletion has been finalized.

Note that the %DeleteId() method has no effect on any object instances in memory.

You can also use the %Delete() method, which requires an OID rather than an ID. An OID is a permanent identifier unique to the database that includes both the ID and the class name of the object. For more details, see Identifiers for Saved Objects: ID and OID.

The %DeleteExtent() Method

The %DeleteExtent() method deletes every object (and subclass of object) within its extent. Specifically it iterates through the entire extent and invokes the %Delete() method on each instance of the object. By default, it calls the %KillExtent() method when all instances are successfully deleted.

The signature of this method is as follows:

classmethod %DeleteExtent(concurrency As %Integer = -1, ByRef deletecount, ByRef instancecount, pInitializeExtent As %Integer = 1, Output errorLog As %Status) as %Status

Where:

• concurrency is the concurrency level (locking) used when deleting the object.

• deletecount is the number of instances deleted.

• instancecount is the original number of instances.

• pInitializeExtent determines whether to call %KillExtent() when the extent is empty.

  • A value of 0 indicates that %KillExtent() will not be called. Some empty globals may remain, as well as the ID counter, if it exists.

  • A value of 1 indicates that %KillExtent() will be called, but the default stream global will not be deleted. This is the default.

  • A value of 2 indicates that %KillExtent() will be called, and the default stream global will be deleted.

  Note:

  If the globals used by the extent are not exclusively used by the extent, some globals may remain even if %KillExtent() is called.

• errorLog is used to return any applicable errors.

For example:

Set sc = ##class(MyApp.MyClass).%DeleteExtent(-1, .deletecount, .instancecount, 2, .errorLog)

The %KillExtent() Method

The %KillExtent() method directly deletes the globals that store an extent of a class, its subextents (subclasses), and its child extents (extents of classes that have a child relationship of the class). The default stream storage global is optionally deleted. %KillExtent() does not invoke the %Delete() method and performs no referential integrity actions.

The signature of this method is as follows:

classmethod %KillExtent(pDirect As %Integer = 1, killstreams As %Boolean = 0) as %Status

Where:

• pDirect determines whether the filing timestamps are also deleted from the ^OBJ.DSTIME global. This is used in InterSystems IRIS Business Intelligence. See Keeping the Cubes Current. The default is 1.

• killstreams determines whether the default stream global is deleted. The default is 0.

For example:

Set sc = ##class(MyApp.MyClass).%KillExtent(1, 0)