Using the Message Purge API

InterSystems IRIS also provides a utility method that enables you to purge messages, with more detailed ability to control how different kinds of messages are purged. This method is in the Ens.Util.MessagePurgeOpens in a new tab class:

classmethod Purge(Output pDeletedCount As %Integer, 
                  pDaysToKeep As %Integer = 7, 
                  pKeepIntegrity As %Boolean = 1, 
                  pBodiesToo As %Boolean = 0, 
                  pBitmapChunkLimit As %Integer = 500, 
                  ByRef pExtendedOptions As %String) as %Status {
}

In order to use this method, you must have the SELECT privilege on the Ens.MessageHeaderOpens in a new tab table.

This method can use the Work Queue Manager to split the purge into multiple parallel batches. This option is enabled only if TypesToPurge is Messages; see the previous section.

This method has the following arguments:

pDeletedCount

This argument, which is returned as output, indicates how many messages were deleted.

pDaysToKeep

See Do not purge most recent (NumberOfDaysToKeep) in the previous section.

pKeepIntegrity

See Purge only completed sessions (KeepIntegrity) in the previous section.

pBodiesToo

See Include message bodies (BodiesToo) in the previous section.

pBitmapChunkLimit

Specifies the maximum number of nodes of the associated bitmap index to examine and then potentially delete. The system will delete only nodes that are unused – that is, nodes that no longer map to any records in the table.

Each node of the bitmap index global corresponds to 64000 records in the associated table, and it is time-consuming to scan the node to make sure it is unused. Consequently, the API does not by default scan all the nodes of the index global.

pExtendedOptions

This argument, which must be passed by reference, is a multidimensional array that specifies some or all of the following additional options:

pExtendedOptions("LimitToConfigItems") is a comma-separated list of configuration names of production hosts. If this option is specified, the purge is limited to messages sent by or received by the business hosts in the list.
pExtendedOptions("WQCategory") causes the purge to use the Work Queue Manager, using the given category; if the given category does not exist, the default category is used.
When using the Work Queue Manager, the message purge is split into batches, using separate SQL queries that select messages by their creation time stamps. For example:
- One batch will purge messages from time stamp A (inclusive) to time stamp B (exclusive).
- Another batch will purge messages from time stamp B (inclusive) to time stamp C (exclusive).
- Yet another batch will purge messages from time stamp C (inclusive) to time stamp D (exclusive).
You can specify the batch size either by specifying the number of messages in a batch or by specifying a span of time (in minutes). The default is a batch of 100000 messages.
pExtendedOptions("WQBatchSize") controls the size of the batch, if WQBatchPeriodMinutes is not defined and you are using WQCategory. This setting specifies the number of messages in a batch (exclusive of completeness or configuration item name requirements). The minimum count is 10000.
pExtendedOptions("WQBatchPeriodMinutes") provides an alternative way to controls the size of the batch. This is used if WQBatchSize is not defined and you are using WQCategory. See comments for pExtendedOptions("WQCategory").
pExtendedOptions("StartDateTime") and pExtendedOptions("DoNotDeleteEndDateTime") are UTC time stamps that specify the start and the end of the time range to delete. Specifically, if a message has a time stamp that is greater than or equal to pExtendedOptions("StartDateTime") and also less than pExtendedOptions("DoNotDeleteEndDateTime"), the message is purged (if the other criteria apply).
pExtendedOptions("StartDateTime") and pExtendedOptions("DoNotDeleteEndDateTime") override pDaysToKeep.

For example, suppose that we want to purge all messages sent or received by the business hosts Service1, Process1, and Operation1. To do this, we could call the purge method as follows:

 set myArray("LimitToConfigItems")="Service1,Process1,Operation1"
 set status=##class(Ens.Util.MessagePurge).Purge(.DeleteCount,,,,,.myArray)

Then the DeleteCount variable would contain the number of messages deleted.

Settings Applicable to Data Purges