Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Scripting_function


Panel
titleDescription

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_friendly

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

Panel
titleClient Permission Restrictions

This scripting function has no Client Permission restrictions.

Panel
titleSyntax

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.

Note
titleImportant

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

Panel
titleCode Examples
Code Block
languagepy
titleCode 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 Block
languagepy
titleCode 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 Block
languagepy
titleCode 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)