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 queried for individual properties. The result object also has a getDataset() function that can be used to convert the query results into a normal dataset, with the columns: EventId, Source, DisplayPath, EventTime, State, Priority.

note

Depending on the number of alarm events in the system, this function can be fairly intensive and take a while to finish executing. Which 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, which can easily be accessed by a component binding.

The Tag Properties page contains more information on Alarm Properties.

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
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).
String[]	state	A list of states to allow. Valid values: "ClearUnacked", "ClearAcked", "ActiveUnacked", "ActiveAcked".
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.
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.
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.
Object[][]	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 condition values: "=","!=","<","<=",">",">=". Only the first two conditions may be used for string values.
Object[][]	any_properties	A set of property conditions, any of which will cause the overall the condition to pass. This parameter is a list of tuples, in the form ("propName", "condition", value). Valid condition values: "=","!=","<","<=",">",">=". Only the first two conditions may be used for string values.
String[]	defined	A list of string property names, all of which must be present on an event for it to pass.
Boolean	includeShelved	A flag indicating whether shelved events should be included in the results. Defaults to "false".
String[]	provider	A list of tag providers to include in the query.

Returns

AlarmQueryResults - The AlarmQueryResults object is functionally a list of AlarmEvent objects. The AlarmQueryResults object has a built-in getDataset() function that will return a Standard Dataset containing the Event Id (UUID of the alarm), Source Path, Display Path, Event Time, State (as an integer), and Priority (as an integer).

Additionally, each AlarmEvent inside of the AlarmQueryResults object has several built-in methods to extract alarm information. More details on these methods can be found on the Alarm Event Properties Reference page.

Important

Each item in the resulting list is a separate alarm event: an alarm becoming active is one item, while the same alarm becoming acknowledged is a separate item. This differs from system.alarm.queryJournal() which groups each event into a single item.

Scope

All

Code Examples

Example #1

# 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()

Example #2

# 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)

Example #3

# 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)