system.alarm.queryStatus
This function is used in Python Scripting.
Description​
Queries the current state of alarms. The result is a list of alarm events, which can be parsed for individual properties. The results provided by this function represent the current state of alarms, in contrast to the historical alarm events retrieved by the system.alarm.queryJournal function.
Depending on the number of alarm events in the system, this function can be fairly intensive and take a while to finish executing. This can be problematic if the application is attempting to show the results on a component (such as using this function to retrieve a count of alarms). In these cases it's preferred to call this function in a gateway script of some sort (such as a timer script), and store the results in a tag.
Client Permission Restrictions​
This scripting function has no Client Permission restrictions.
Syntax​
system.alarm.queryStatus([priority], [state], [path], [source], [displaypath], [all_properties], [any_properties], [defined], [includeShelved], [provider])
Parameters​
| Type | Parameter | Description |
|---|---|---|
| List[Integer / String] | priority | A list of possible priorities to match. Priorities can be specified by name or number, with the values: Diagnostic(0), Low(1), Medium(2), High(3), Critical(4). [optional] |
| List[Integer / String] | state | A list of states to allow. See State Values for a list of options. [optional] |
| List[String] | path | A list of possible source paths to search at. The wildcard "*" may be used. Works the same as the source argument, and either can be used. [optional] |
| List[String] | source | A list of possible source paths to search at. The wildcard "*" may be used. Works the same as the path argument, and either can be used. [optional] |
| List[String] | displaypath | A list of display paths to search at. Display paths are separated by "/", and if a path ends in "/*", everything below that path will be searched as well. [optional] |
| List[Tuple[String, String, Any] | all_properties | A set of property conditions, all of which must be met for the condition to pass. This parameter is a list of tuples, in the form ("propName", "condition", value). Valid propName values can be either associated data or the keys listed on the PyAlarmEvent object. Valid condition values: "=","!=","<","<=",">",">=". String values can only be compared using "=" and "!=" conditions. [optional] |
| List[Tuple[String, String, Any] | any_properties | A set of property conditions, any of which will cause the overall condition to pass. This parameter is a list of tuples, in the form ("propName", "condition", value). Valid propName values can be either associated data or the keys listed on the PyAlarmEvent object. Valid condition values: "=","!=","<","<=",">",">=". String values can only be compared using "=" and "!=" conditions. [optional] |
| List[String] | defined | A list of string property names, all of which must be present on an event for it to pass. [optional] |
| Boolean | includeShelved | A flag indicating whether shelved events should be included in the results. Defaults to false. [optional] |
| List[String] | provider | A list of tag providers to include in the query. Omitting this parameter will query all providers. [optional] |
Returns​
AlarmQueryResult - The AlarmQueryResult object is a list of PyAlarmEvent objects with some additional helper methods, see See Scripting Object Reference.
Additionally, each PyAlarmEvent inside of the AlarmQueryResult object has several built-in methods to extract alarm information. More details on these methods can be found on the Scripting Object Reference page.
Each item in the resulting list is a combination of each alarm event for the same alarm: details for when the alarm became active, acknowledged, and cleared are combined into a single item. This differs from system.alarm.queryJournal() which splits these events into separate items
Scope​
Gateway, Vision Client, Perspective Session
State Parameter Values​
| String Representation | Integer Representation |
|---|---|
| ClearUnacked | 0 |
| ClearAcked | 1 |
| ActiveUnacked | 2 |
| ActiveAcked | 3 |
Code Examples​
# This example queries the state of all tags named "HiAlarm", and puts the results in a Vision table Component named "Table" (this assumes it's being run from a button on the same screen)
# Note that this example is simple for the sake of brevity. Normally you'll want to use system.util.invokeAsynchronous to search for alarms in a separate thread, especially so if calling
# this function from a component based script. See the next example for more information.
table = event.source.parent.getComponent("Table")
results = system.alarm.queryStatus(source=["*HiAlarm*"])
table.data = results.getDataset()
# In this example we'll call system.alarm.queryStatus in a separate thread, and return the results to the data property on a Vision Table component. Similar to the example above.
# What makes this example different is that it offers better performance when calling from a Vision component. Depending on the number of alarm events in the system, queryStatus
# may take a significant amount of time to finish, which would lock up a Vision Client while the script is running in the GUI thread. Thus this example will use
# system.util.invokeAsynchronous to call queryStatus in a separate thread, and then system.util.invokeLater make any changes to our components.
# Define a function that will retrieve alarm data in a separate thread
def getAlarms():
# Call queryStatus to retrieve the alarm data we're looking for, and store the results in a variable.
# In this case, we're looking for alarm events that contain the word "Sensor" in the source path.
results = system.alarm.queryStatus(source=["*Sensor*"])
# From this same script, define a separate function that will later interact with the
# GUI, allowing us to move our alarm data over to a component
# We're also using the getDataset() function on the object returned by queryStatus,
# since that will provide a dataset that our table component will expect.
def setTheTable(alarms = results.getDataset()):
# Replace the property reference below with a path leading to whichever property
# you want to move the alarm data to.
event.source.parent.getComponent("Table").data = alarms
# The last thing we'll do in the separate thread is call invokeLater
# which will let our setTheTable function run in the GUI thread
system.util.invokeLater(setTheTable)
# Call the getAlarms function in a separate thread, which starts the whole process
system.util.invokeAsynchronous(getAlarms)
# The any_properties parameter allows you to filter the results for specific properties. This is useful when searching for alarms that contain associated data.
# Build a List of Tuples that represent the properties to search for. In this case, if our alarms have an Associated Data named 'Group', we can use
# the following to search for potential values
props = [("Group", "=", "value1"), ("Group", "=", "value2")]
state = ["ActiveUnacked", "ActiveAcked"]
alarms = system.alarm.queryStatus(any_properties = props, state = state)
# Here we're printing out the number of alarms that meet our criteria. We could replace this and further examine each individual alarm in a for-loop instead.
print len(alarms)
# Using all_properties (AND operator)
props = [
("EventId","=","9bb7e0ee-011b-4f37-8e07-e54706e11852"),
("Priority","=","Medium"),
("EventTime", "=", "Jan 04 17:07:12 UTC 2022")
]
results = system.alarm.queryStatus(all_properties=props)