This is documentation for Caché & Ensemble.

For information on converting to InterSystems IRIS, see the InterSystems IRIS Adoption Guide and the InterSystems IRIS In-Place Conversion Guide, both available on the WRC Distributions page (login required).

Home > Class Reference > %SYS namespace > SYS.DataCheck.RangeList


persistent class SYS.DataCheck.RangeList extends %Library.Persistent

SQL Table Name: SYS_DataCheck.RangeList

A list of global subscript ranges describing the entire key space of a single global. Objects of this class are the list header with properties for the list metadata. The ListElements query provides the list elements as rows.

The RangeList is used to store results of the check and also the include/exclude subscript ranges to check (see ListSet property for more info)

RangeList objects that store results are maintained by the DataCheck destination system and should not be modified.

To create/edit a global selection RangeList as part of configuring a DataCheck destination system, the sequence is as follows. Note that the system must be configured to use global selection RangeLists in order for this to have an effect:
1. To create a new RangeList object, passing the appropriate arguments to the %New() constructor (see %OnNew()); then call SetCollation(). To edit an existing RangeList object, you can open through the MainIndex with the MainIndexOpen() method.
2. Call Insert() repeatedly, setting the desired ranges to state $$$RangeStateExcluded, with the rest being $$$RangeStateIncluded.
3. Call %Save() to save the object.

Property Inventory

Method Inventory


property AggregateState as RangeState [ Calculated ];
One of the following constants, defined for convenience in
  • 1 - $$$RangeStateMatched - the entire global, less any excluded ranges, was found to be matched
  • 0 - $$$RangeStateUnknown - the entire global has not been checked yet, but no discrepancies found
  • -1 - $$$RangeStateUnmatched - some ranges have discrepancies
  • Property methods: AggregateStateCompute(), AggregateStateDisplayToLogical(), AggregateStateGet(), AggregateStateIsValid(), AggregateStateLogicalToDisplay(), AggregateStateNormalize(), AggregateStateSQLCompute()
    property Collation as %Integer [ InitialExpression = -1 , ReadOnly ];
    Collation of global or -1 if unknown
    Property methods: CollationDisplayToLogical(), CollationGet(), CollationGetStored(), CollationIsValid(), CollationLogicalToDisplay(), CollationNormalize()
    property Database as LocalDatabase [ Required , ReadOnly ];
    Database referenced by this RangeList
    Property methods: DatabaseDisplayToLogical(), DatabaseGet(), DatabaseGetPath(), DatabaseGetStored(), DatabaseIsMirrorDBName(), DatabaseIsPath(), DatabaseIsValid(), DatabaseLogicalToDisplay(), DatabaseLogicalToOdbc(), DatabaseNormalize()
    property GlobalName as GlobalReference [ Required , ReadOnly ];
    Global name referenced by this RangeList
    Property methods: GlobalNameCollatesAfter(), GlobalNameDisplayToLogical(), GlobalNameEncode(), GlobalNameGet(), GlobalNameGetStored(), GlobalNameGlobalName(), GlobalNameIsValid(), GlobalNameLogicalToDisplay(), GlobalNameNormalize()
    property ListSet as %String (COLLATION = "EXACT") [ Required ];
    The set of RangeLists that this object is a member of. Integer values 1 and higher are the set of results generated by the DataCheck system and incremented each time the system starts a new set of results. The currently active set of results is returned by GetActiveResultsListSet(). A value of "%GS" ($$$RangeListSetGlobalSelection) indicates that this object is a member of the set of configured subscript ranges to include / exclude from the check.
    Property methods: ListSetDisplayToLogical(), ListSetGet(), ListSetGetStored(), ListSetIsValid(), ListSetLogicalToDisplay(), ListSetLogicalToOdbc(), ListSetNormalize(), ListSetSet()
    property SystemName as SystemName [ Required , ReadOnly ];
    DataCheck system name that this RangeList belongs to
    Property methods: SystemNameDisplayToLogical(), SystemNameGet(), SystemNameGetStored(), SystemNameIsValid(), SystemNameLogicalToDisplay(), SystemNameLogicalToOdbc(), SystemNameNormalize()


    method %OnNew(systemname As %String, set As %String, database As LocalDatabase, globalname As %String) as %Status
    Constructor for RangeList

    Input Parameters:

  • systemname: name of the DataCheck destination system
  • set: set that this rangelist is a member of; see ListSet
  • database: The local database path for non-mirror DataCheck configurations; the mirror database name, in :mirror:mirrorname:mirrorDBname format, for mirrored DataCheck configurations.
  • globalname: name of the global that this rangelist represents (leading ^ is optional)

    IMPORTANT: The creator of a global selection RangeList is responsible for ensuring that the database is specified correctly, and for non-mirror DataCheck configurations, that it has a mapping specified in the DataCheck configuration.

  • method DumpArrays()
    classmethod GetActiveResultsListSet(systemname As %String) as %String
    Given a DataCheck system name, returns the ListSet of the currently active set of results
    classmethod GetListSetEndTime(systemname As %String, listset As %String) as %String
    Given a DataCheck system name and a list set, returns the date and time in $horolog format when all pending DataCheck queries finished, with the specified list set was the active one. Returns null if there are queries pending and the specified list set is the active one, or if the specified list set does not exist. If the specified list set is the active one, the value may change from non-null back to null if new queries are run.
    classmethod GetListSetStartTime(systemname As %String, listset As %String) as %String
    Given a DataCheck system name and a list set, returns the date and time in $horolog format when the check whose results are stored in that list set began. Returns null if the set does not exist.
    method Insert(gloref1 As GlobalReference, gloref2 As GlobalReference = "", state As RangeState, cachetoken As %List = "", Output sc As %Status) as %List
    Inserts a new range into the range list, merging and splitting with existing ranges as appropriate. Caller must call %Save() to save.

    Input Parameters:

  • gloref1: beginning of the range to insert (inclusive)
  • gloref2: end of range to insert (exclusive)
  • state: state of the range to insert
  • cachetoken: (optional) A token returned from a previous call to Insert(). See below for more detail.
  • Output Parameters:
  • sc: %Status returned from this call. If an error occurs that is not simply the result of invalid input, the RangeList needs to be reloaded to return to a valid state; in this case subsequent calls to Insert or attempts to save the RangeList will result in $$$DCRangeListErrorStatus errors.

    Returns: Returns a "cachetoken" that reserves some of the list elements in a cache to optimize the next insert. Caller must maintain this cachetoken as described below. If the status in 'sc' is not $$$OK, the cachetoken shall be null.

    The cachetoken returned from a call to Insert() should be passed in to the next call to Insert() that is to act on a nearby part of the list. Each call to Insert() that is passed a token will: start a linear scan of the list from elements referenced in the passed cachetoken (assuming those elements are still cached and haven't be removed by intervening modifications to the list); release the cache reservation on the elements that the token references; and return a new cachetoken with an updated cache reservation. If an Insert() call is not known to be acting on a region of the list near to a cachetoken that the caller has from a previous Insert() call, the caller should instead pass a null cachetoken. When no cachetoken is passed, Insert() will evaluate all cached elements to determine an optimal starting location.

    The caller is responsible for releasing the cache reservation for any cachetoken returned from Insert() that is not used in a later Insert() call. The cache reservation should be released by passing the unused cachetoken to ReleaseCacheToken() or by closing the RangeList object.

  • method ReleaseCacheToken(cachetoken As %List)
    Takes as argument a cachetoken returned from Insert() and releases the cache reservation of the cached elements.
    method SetCollation(col As %Integer)
    Sets the Collation to the value of the 'col' parameter if specified. If no value is specified, obtains it from the local system by looking at the global referenced by this RangeList object, if it exists, or from the default for the database referenced by this RangeList object. Throws an exception if it was already set to a valid collation. Caller must call %Save() to save.


    query ListElements(systemname As %String, set As %String, database As LocalDatabase, global As GlobalReference, ByRef rl As RangeList)
    Selects From As SYS.DataCheck.GlobalReference, To As SYS.DataCheck.GlobalReference, State As SYS.DataCheck.RangeState
    The ListElements query fetches as rows each subscript range in the rangelist in collation order. Each subscript range is the global reference inclusive of the 'From' column up to but excluding the global reference in the 'To' column. If 'To' is null or "[end]" in display mode, the range extends to the end of the global.

    Input Parameters:

  • systemname: name of the DataCheck system
  • set: ListSet to query (see ListSet property)
  • database: path of the database local to this system
  • global: name of the global
  • rl: (optional) If an object is passed in this parameter, it will be assumed to be the RangeList object for which elements should be returned and the other input parameters will be ignored. This parameter also serves as an output parameter to return the RangeList object opened if no object was passed in.

    Output Parameters:

  • rl: (optional) If no object was passed in as an input parameter (see above), then the output of this parameter is the RangeList object that was opened, or null if no RangeList object exists (in this case no rows will be found). If an object was passed as an input parameter, it is not modified.
  • Indexes

    index (IdIndex on SystemName,Counter) [IdKey, Type = key];
    Index methods: IdIndexCheck(), IdIndexDelete(), IdIndexExists(), IdIndexOpen(), IdIndexSQLCheckUnique(), IdIndexSQLExists(), IdIndexSQLFindPKeyByConstraint(), IdIndexSQLFindRowIDByConstraint()
    index (MainIndex on SystemName,ListSet,Database,GlobalName) [Unique];
    Index methods: MainIndexCheck(), MainIndexCheckUnique(), MainIndexDelete(), MainIndexExists(), MainIndexOpen(), MainIndexSQLCheckUnique(), MainIndexSQLExists(), MainIndexSQLFindPKeyByConstraint(), MainIndexSQLFindRowIDByConstraint()
    index (StateIndex on SystemName,ListSet,AggregateState);
    Index methods: StateIndexExists()

    Inherited Members

    Inherited Methods


    Storage Model: CacheStorage (SYS.DataCheck.RangeList)

    FeedbackOpens in a new window