This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see the InterSystems IRIS Migration Guide and Migrating to InterSystems IRIS, both available on the WRC Distributions page (login required).

%SYS.Maint.Bitmap

persistent class %SYS.Maint.Bitmap extends %Library.Persistent

SQL Table Name: %SYS_Maint.Bitmap

This utility is used to compress bitmap indices. Over time in a volatile table (think lots of INSERTs and DELETEs) the storage for a bitmap index will become less and less efficient. To a lesser extent index value changes, for example OrderStatus changing from Open to Closed, can also degrade bitmap performance.

This utility can by run on a live system. It will loop over all bitmap indices in a class or namespace and compress them by either removing a chunk that is all zeros or by using $BITLOGIC() to compress the bits.

The Utility has 2 entry points:

  d ##class(%SYS.Maint.Bitmap).Namespace("Samples",1,1,"2014-01-17 09:00:00")
  
  d ##class(%SYS.Maint.Bitmap).OneClass("BitMap.Test",1,1)
  

Property Inventory (Including Private)

Method Inventory (Including Private)

Properties

property ClassName as %String (MAXLEN = 500);
Namspace that was compacted Last Class Compacted, if NULL then it finished all the classes.
Property methods: ClassNameDisplayToLogical(), ClassNameGet(), ClassNameGetStored(), ClassNameIsValid(), ClassNameLogicalToDisplay(), ClassNameLogicalToOdbc(), ClassNameNormalize(), ClassNameSet()
property CompressionAmount as %String [ Transient ];
Property methods: CompressionAmountCompute(), CompressionAmountDisplayToLogical(), CompressionAmountGet(), CompressionAmountIsValid(), CompressionAmountLogicalToDisplay(), CompressionAmountLogicalToOdbc(), CompressionAmountNormalize(), CompressionAmountSQLCompute(), CompressionAmountSet(), CompressionAmountSetT()
property ElapseTime as %Integer [ Transient ];
Property methods: ElapseTimeCompute(), ElapseTimeDisplayToLogical(), ElapseTimeGet(), ElapseTimeIsValid(), ElapseTimeLogicalToDisplay(), ElapseTimeNormalize(), ElapseTimeSQLCompute(), ElapseTimeSet(), ElapseTimeSetT()
property IndexName as %String (MAXLEN = 500);
Last Index Compacted, if NULL then it finished all the indices.
Property methods: IndexNameDisplayToLogical(), IndexNameGet(), IndexNameGetStored(), IndexNameIsValid(), IndexNameLogicalToDisplay(), IndexNameLogicalToOdbc(), IndexNameNormalize(), IndexNameSet()
property Message as array of %String (MAXLEN = 30000);
Message contains error info and lists of global that were skipped because they where not in the local DB
Property methods: MessageBuildValueArray(), MessageCollectionToDisplay(), MessageCollectionToOdbc(), MessageDisplayToCollection(), MessageDisplayToLogical(), MessageGet(), MessageGetObject(), MessageGetObjectId(), MessageGetStored(), MessageGetSwizzled(), MessageIsValid(), MessageLogicalToDisplay(), MessageLogicalToOdbc(), MessageNormalize(), MessageOdbcToCollection(), MessageSet(), MessageSetObject(), MessageSetObjectId()
property Namespace as %String (MAXLEN = 500);
Property methods: Namespace(), NamespaceDisplayToLogical(), NamespaceGet(), NamespaceGetStored(), NamespaceIsValid(), NamespaceLogicalToDisplay(), NamespaceLogicalToOdbc(), NamespaceNormalize(), NamespaceSet()
property NewSize as %Integer [ InitialExpression = 0 ];
Property methods: NewSizeDisplayToLogical(), NewSizeGet(), NewSizeGetStored(), NewSizeIsValid(), NewSizeLogicalToDisplay(), NewSizeNormalize(), NewSizeSet()
property NumberCompressed as %Integer [ InitialExpression = 0 ];
count of how many indices were compacted
Property methods: NumberCompressedDisplayToLogical(), NumberCompressedGet(), NumberCompressedGetStored(), NumberCompressedIsValid(), NumberCompressedLogicalToDisplay(), NumberCompressedNormalize(), NumberCompressedSet()
property OldSize as %Integer [ InitialExpression = 0 ];
Property methods: OldSizeDisplayToLogical(), OldSizeGet(), OldSizeGetStored(), OldSizeIsValid(), OldSizeLogicalToDisplay(), OldSizeNormalize(), OldSizeSet()
property StartTime as %TimeStamp;
when the last Compact was started
Property methods: StartTimeDisplayToLogical(), StartTimeGet(), StartTimeGetStored(), StartTimeIsValid(), StartTimeLogicalToDisplay(), StartTimeNormalize(), StartTimeOdbcToLogical(), StartTimeSet()
property Status as %String;
current status of the compaction Running - Compaction is underway Stopped - Compaction reached the Duration limit before finishing all Classes or encountered an error Finished - Compaction completed.
Property methods: StatusDisplayToLogical(), StatusGet(), StatusGetStored(), StatusIsValid(), StatusLogicalToDisplay(), StatusLogicalToOdbc(), StatusNormalize(), StatusSet()
property StopTime as %TimeStamp;
Passed in Timestamp for when the compact should stop, NULL for no stop time Set to the time the compaction finshed when done.
Property methods: StopTimeDisplayToLogical(), StopTimeGet(), StopTimeGetStored(), StopTimeIsValid(), StopTimeLogicalToDisplay(), StopTimeNormalize(), StopTimeOdbcToLogical(), StopTimeSet()

Methods

private classmethod CompactGlobal(global As %String, vars As %Integer, current As %Integer, ByRef v As %String, Display As %Boolean = 0, StatusObj As %CacheObject) as %Status

This method compacts any global bitmap
Called from CompactMap it takes 3 parameters

  • global - is the root for this index, for example ^Sample.PersonI("NameIndex")
  • vars - is the number of subscripts we need to $ORDER() over
  • current - is the subscript level we are presently on

Once we get tot he final subscript level we execute the compat code.

private classmethod CompactMap(ClassName As %String, MapName As %String, Display As %Boolean, StatusObj As %CacheObject) as %Status
classmethod Namespace(ns As %String, NoJournal As %Boolean = 0, Display As %Boolean = 0, StopTime As %TimeStamp = "") as %Status [ SQLProc = Bitmap_Namespace ]

Entry point to compact all bitmaps in a namespace.
Each run records its' status in this class
If the last run did not finish then it will pick up where it stopped
This utility will only Compact globals in the default database

Parameters:

  • ns - Namespace you want to compact
  • NoJournal - Stop journaling for this Process
    • 1 to Stop Journaling
    • 0 to continue Journaling default = 0
  • Display - write info to the current device
    • 1 to write to the device
    • 0 to not write to the device default = 0
  • StopTime - Timestamp for when the utility should stop.
    • The stop time is tested after each index is finished so it could go over.
    • A value of NULL means not limit
classmethod OneClass(ClassName As %String, NoJournal As %Boolean = 0, Display As %Boolean = 0, StopTime As %TimeStamp = "", StatusObj As %CacheObject = "") as %Status [ SQLProc = Bitmap_OneClass ]

Entry point to compact all bitmaps in one class.
Each run records its' status in this class
This utility will only Compact globals in the default database

Parameters:

  • ClassName - Class you want to compact
  • NoJournal - Stop journaling for this Process
    • 1 to Stop Journaling
    • 0 to continue Journaling default = 0
  • Display - write info to the current device
    • 1 to write to the device
    • 0 to not write to the device default = 0
  • StopTime - Timestamp for when the utility should stop. The stop time is tested after each index is finished so it could go over.
    • a value of NULL means not limit
  • StatusObj - This is either passed in from the Namespace Method or is defined in this method.
    • This value should not be passed in if you are calling this method directly

Indices

index (IDKEY on ) [IdKey, Type = key];
Index methods: IDKEYCheck(), IDKEYDelete(), IDKEYExists(), IDKEYOpen(), IDKEYSQLCheckUnique(), IDKEYSQLExists(), IDKEYSQLFindPKeyByConstraint(), IDKEYSQLFindRowIDByConstraint()

Inherited Members

Inherited Methods (Including Private)

Storage

Storage Model: CacheStorage (%SYS.Maint.Bitmap)

^%SYS.Maint.BitmapD(ID)
=
StartTime
StopTime
Namespace
ClassName
IndexName
NumberCompressed
Status
OldSize
NewSize

Storage Model: CacheStorage (%SYS.Maint.Bitmap)

^%SYS.Maint.BitmapD(ID,"Message",n)
=
Message(n)
Feedback