You're currently browsing the Ignition 7.9 docs. Click here to view the latest docs.

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

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

All

Code Examples
Code Snippet - Querying Alarm Status
# 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()
Code Snippet - Call queryStatus in a Separate Thread
# 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)
Code Snippet - Querying Alarm Status Using any_properties
# 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)
  • No labels