GetAlarmList

(Alarm Manager module)

Description: Returns filtered and sorted lists of records from alarm databases.
Returns: See descriptions in the parameter list.
Usage: Script Only.
Function Groups: Alarm
Related to:  
Format:

\AlarmManager\GetAlarmList(ListPtr, LengthPtr, ListNames[, Snapshot, IncludeShelved, IncludeConfig, FilterExpr, CalculatedFields, CalculatedFieldsScope, SortOrder, BeginTime, EndTime, MaxHistory, PtrDone, PtrHistoryProgress, PtrChangeStats, DBTags, RefreshInterval, Realm, Area, IncludeSubordinates, InitDeferTimeout])
Parameters:  
ListPtr
Required. This pointer will be assigned the array of records being returned. The array may be longer than the number of records, see LengthPtr for the valid length.
LengthPtr
Required. Pointer to a variable which will be assigned the number of elements in the ListPtr array that are to be used.
ListNames

Required. Provide a text string or an array of strings identifying the lists to which the alarm will subscribe. Valid list names include:

  • History
  • Active
  • Unacked
  • Shelved
  • Disabled
  • Configured

To obtain the Current list, include Active and Unacked in your array.
Snapshot
Optional Boolean. If TRUE, then this function will take a snapshot of the list(s) and terminate. If FALSE, then the function will build the list while also keeping it updated.
A snapshot of live list(s) acts as a subroutine, all other uses must launch a worker process.
Defaults to FALSE.
IncludeShelved
Optional Boolean. Set TRUE to include shelved alarms. Defaults to FALSE.
IncludeConfig
Optional Boolean. Set TRUE to include alarm configuration events in History. Defaults to FALSE.
FilterExpr

Optional text string that is the expression to evaluate if a record is to be included.
Standard realm-area filtering is handled automatically so should not be included in this expression.

Note that text must be surrounded in quotation marks if being used in the filter. For example:

Concat("Record\Area == """, pArea, """")
CalculatedFields

Optional array. May be used to create additional record fields or modify existing records. A callback subroutine allows record field values to be replaced, for example swapping AccountID for an operator name.
If specified, this parameter must be an array that defines the extra record fields.
For example:

CalculatedFields = New(4);
CalculatedFields[0] = "FriendlyName";
CalculatedFields[1] = "IsActive";
CalculatedFields[2] = "IsUnacked";
CalculatedFields[3] = "IsDisabled";
CalculatedFieldsScope
Optional. Scope in which to find calculated field values. Often, Self()
SortOrder

Optional. For live lists this is sorting information for SortArray.
For example:

{ Sort by friendly name }
SortInfo = SortKeys("FriendlyName", 1 { text }, #SortAscending);

For history set TRUE for forward chronological, and FALSE for reverse (default).
BeginTime
Optional UTC timestamp. Oldest time. May be used when filtering history.
EndTime
Optional UTC timestamp. Newest time. May be used when filtering history.
MaxHistory
Optional numeric, except required when querying the History list. Limits the number of history records retrieved. No default.
PtrDone
Optional pointer. Will be set TRUE when history search completes.
PtrHistoryProgress
Optional pointer. Will be set to a structure instance containing progress stats (HistoryProgressDef)
PtrChangeStats

Optional pointer. Allows the caller to detect changes. Set to a structure as follows:

  • Additions { Set to cumulative number of records added };
  • Modifications { Set to cumulative number of records modified};
  • Deletions { Set to cumulative number of records deleted };
DBTags
Optional array of AlarmDatabase tag names (UniqueIDs or Friendly Names). If a simple text value, then it is the single tag to access. If Invalid then all AlarmDatabase tags are included. Realm filtering is automatically detected and used.
RefreshInterval
Optional numeric. Minimum time in seconds between sorted array updates. Defaults to a half-second.
May also be set by adding an application property, AlarmListRefreshDelayTime.
Realm
Optional text. Realm to use for realm filtering. This will be detected automatically for the logged-on account if not otherwise specified.
Area
Optional text. Area to use for filtering. May use wildcard characters.
IncludeSubordinates
Optional Boolean. When TRUE, alarm databases from subordinate applications are included. Defaults to TRUE.
InitDeferTimeout
Optional numeric. Sets a time to wait before initializing. Setting this value to .1 will allow other objects on a page to load before the alarm list is populated, resulting in a smoother user experience. Defaults to 0.
Comments:

An alarm database contains a history of alarm transactions / event records. Event records are included only in a queries for a history list.

Filtering - Only records that pass filtering will be displayed. Filtering may be:

  • Area filtering (Realms, etc..) [automatic]
  • Shelved alarm suppression
  • Custom filter expression

For efficiency reasons the filtering is done on the base record rather than the calculated version.

History - Unlike the live lists, the history is unbounded and must be accessed from storage. The process can take time so search progress is reported via PtrHistoryProgress.

When working with a live list, the system will automatically rerun filtering and recalculate fields if an alarm is changes on any list, allowing filtering and calculated fields based on other list state.

Example:

LoadList [
  If 1 WaitResults;
  [
    \AlarmManager\GetAlarmList(&Records, &NRecords, "History", TRUE, ShowShelved, FALSE,
                               Concat("Record\Name == """, Record\Name, """ && 
                               (Record\Action == ""Active"" || Record\Action == ""Trip"")"),
                               Invalid, Invalid, FALSE, StartTime, EndTime, NRecordsLimit,
                               &Done, &Progress);
  ]
]