Creates an alarm. An alarm is triggered when a data item value reaches a specified threshold value.
hs_create_alarm view_name, data_item_name, data_item_stat, alarm_action, alarm_action_data, alarm_value
name of the view that contains the data item to which the alarm applies.
the data item to which the alarm applies. If the data item contains embedded spaces, surround it with quotation marks.
statistic type for data_item_name. The data_item_name and data_item_stat combination must exist in the view definition. Surround the statistic type with quotation marks.
action to take when an alarm condition occurs. Values are:
log – logs messages when the alarm condition occurs. You specify the log file name in the alarm_action_data parameter.
execute – executes a program or script file when the alarm condition occurs. You specify the file to execute in the alarm_action_data parameter.
specifies information required to carry out the alarm_action:
If alarm_action is |
Then alarm_action_data is |
|---|---|
log |
Name of the file where Historical Server should log the alarm messages. The default is the Historical Server log file. If you specify a file that does not exist, Historical Server creates it. If you specify an existing file, the user who started Historical Server must have write permission for the file. |
execute |
Name of the file to execute, optionally followed by a list of parameters separated by spaces. The file must exist and the user who started Historical Server must have execute permission for it. WARNING! When an alarm condition occurs and alarm_action is execute, the specified file is executed by the account that started Historical Server, not by the account that created the alarm. This means that the access privileges of the person who starts Historical Server are available to the users who define alarms. A user who normally could not execute a file might be able to execute it through an Historical Server alarm. |
triggering value for the alarm.
This example creates an alarm for a view named Page I/O. The view contains the Page I/O data item with a Value for Session statistic type. The data is logged to the page_io_alarm_file file when a trigger value of 50 or greater is achieved.
hs_create_alarm PageIO,"Page I/O", "Value for Session",log,page_io_alarm_file,50
This example creates an alarm for a view named Page I/O. This alarm causes the /user/script1 script to be executed and passed the value 100 as its first parameter when a trigger value of 100 or greater is achieved on the Page I/O data item.
hs_create_alarm PageIO,"Page I/O", "Value for Session",execute, "/user/script1 100",100
If alarm_action is execute, when the alarm condition occurs, the script or program executes in the background. The commands within the script or program are executed in the foreground and displayed if applicable.
For example, if you want the clock to display in an alarm condition, you should put clock.exe into a script file and specify the script file name when creating the alarm, rather than specifying clock.exe when creating the alarm.
When an alarm condition occurs and alarm_action is log, Historical Server writes three lines to the log file. The first line contains:
Timestamp of the sample that triggered the alarm
Name of the data item on which the alarm was set
Statistic type of that data item
Value of the data item that triggered the alarm
Threshold value of the alarm
The second line in the log file contains:
Session ID
View name
Alarm ID
The third line in the log file contains:
Name of the Adaptive Server being monitored
Names and values of all key data items in the view for the row of sample data that triggered the alarm
When an alarm condition occurs and alarm_action is execute, Historical Server runs the script or program specified in the alarm_action_data parameter. Historical Server invokes the program or file using the arguments specified in alarm_action_data, followed by additional positional arguments that can be accessed within the program. The positional arguments appended to the call by Historical Server represent the following information:
Session ID
Alarm ID
Sample timestamp
Data item on which the alarm was set
Statistic type of that data item
Value of the data item that triggered the alarm
Threshold value of the alarm
Name of the Adaptive Server being monitored
Number of key data items in the view
For each key data item:
Name of the data item
Value of that data item for the row of sample data that triggered the alarm
When an alarm condition occurs and alarm_action is execute, the specified file is executed by the account that started Historical Server, not by the account that created the alarm. This means that the access privileges of the person who starts Historical Server are available to users who define alarms.
WARNING! It is possible that a user who normally could not execute a file can execute that file through an Historical Server alarm.
