Home
This section is mostly a copy of the alh Alarm Handler User's Guide.
It was modified to reflect differences and different terminology between alh and TAlh.

  • Configuration File Description
  • File Name
  • Input Format
  • Sample Configuration File
  • Alarm Channel Mask

  • Configuration File Description

    The alarm configuration file is the file used as input to the Alarm Handler. This file defines the Alarm Group structure and takes data in a flexible input format. The alarm configuration file, which can be prepared via any text editor, defines a complete Alarm Group structure composed of subgroups and channels. The arrangement of channels and subgroups follow the standard tree structure. The subgroups always terminate at channels. The only input format constraint is that the definitions must be in hierarchical order. That is, after a group is defined in the configuration file as belonging to a parent group, all its subgroups and channels must be defined in the configuration file before a new group belonging to the same parent group can be defined. There can be only one top-level group (main group) and this group must have NULL as the parent group name. For each group or channel, a set of input specifications is used to define special events to be taken care of at start-up time.

    File Name

    When opening a new configuration file, ".alhConfig" will be used as the default suffix. The default file name for the alarm configuration file is test.alhConfig.

    Input Format

    The configuration file statements for a given group or channel takes flexible input format which can consist of the following items:

    GROUP parentName GroupName
    $HEARTBEATPV heartbeatPvName <value> <seconds>
    $BEEPPV beepPvName
    CHANNEL parentName ChannelName <mask>
    INCLUDE parentName fileName
    $ACKPV ackPVName ackValue
    $FORCEPV forcePVName forceMask <forceValue> <resetValue>
    $FORCEPV CALC forceMask <forceValue> <resetValue>
    $FORCEPV_CALC <expression>
    $FORCEPV_CALC_A <PVNameA>
    ...
    $FORCEPV_CALC_F <PVNameF>
    $SEVRPV sevrPVName
    $GUIDANCE
    $END
    $GUIDANCE urlAddress
    $ALIAS anyValidTextString
    $COMMAND anyValidCommand
    $SEVRCOMMAND severityChangeValue anyValidCommand
    $STATCOMMAND alarmStatusStringValue anyValidCommand
    $ALARMCOUNTFILTER inputCount inputSeconds
    $BEEPSEVERITY ALHbeepSeverity
    $BEEPSEVR GroupOrChannelBeepSeverity

    new in TAlh:

    $INSTANCE <instance string>
    $NOACKGROUPS

    Input syntax notes:

    Heartbeat Process Variable

    The line starting with $HEARTBEATPV is optional. It is required only when a user wants a monitored pv to show whether or not ALH is running. If the $HEARTBEATPV line is present, TAlh will do CA puts of the specified value to the specified pv at the specified rate (in seconds). The heartbeat PV Name must be an existing PV in the EPICS database and can be specified as <channel_name>.<field_name>.


    Beep Process Variable

    The line starting with $BEEPPV is optional. It is required only when a user wants a monitored pv to show the severity of the highest unacknowledged alarm. If the $BEEPPV line is present, TAlh will do a CA put of this severity every time a beep is triggered . The beep PV Name must be an existing PV in the EPICS database and can be specified as <channel_name>.<field_name>. 
    This PV can be used to trigger external hardware. NOTE that TAlh does not reset this PV, i.e. the PV changes only if the highest unacknowledged alarm severity changes.

    Alarm Handler Instance

    The line starting with $INSTANCE is optional. It is required only when a user wants the alarm handler name to be different from the configuration file prefix. For logging to files, the alarm handler name determines the log file name.

    Group Acknowledge Policy

    The line starting with $NOACKGROUPS is optional. It is required only when a user wants to establish a site policy about acknowledging alarm groups.

    If present, the acknowledging of alarm groups is disabled, i.e. all alarms must be individually acknowledged.
    If not present, the acknowledging of alarm groups is enabled. This setting can be modified during a TAlh session on the in the File >> Preferences dialog.

    Group or Channel

    A set of group or channel lines must appear in the alarm configuration file. These lines define the Alarm Group structure. The first line is the top level Alarm Group definition. There can be only one top-level Alarm Group and this Alarm Group must have NULL as the parent group name. Group or Channel lines must start with the keyword GROUP or CHANNEL. The GroupName is the name of a user specified Alarm Group. The ChannelName must be the name of a specific record defined in an EPICS database. The parentName is the name of the parent Alarm Group. There is no restriction on the number of group definitions.

    GROUP parentName GroupName

    CHANNEL parentName ChannelName <mask>

    The channel <mask> is optional and defaults to no mask. It is required only for a channel with a non default mask setting. The detailed description of mask settings is given in Alarm Channel Mask in this Chapter.

    Include File

    The line starting with INCLUDE allows a user to designate, within his alarm configuration file, the name of another alarm configuration file to be read by the Alarm Handler at runtime. The main Alarm Group of the designated file will become a child group of the parentName group specified on the INCLUDE line.

    INCLUDE parentName fileName

    Acknowledge Process Variable

    The line starting with $ACKPV is optional. It is required only when a user wants to write a user specified value (ackValue) to an acknowledge process variable (ackPVName) when a channel's alarm is acknowledged. The acknowledge Process variable must be defined in the IOC database and is specified as <record_name>.<field_name>. Whenever the channel's alarm is acknowledged, the acknowledge value (ackValue) is written to the acknowledge process variable via a channel access put (ca_put) request. Writes to an acknowledge process variable are done only when the alarm handler is in global active mode.

    $ACKPV ackPVName ackValue

    Force Process Variable

    The lines starting with $FORCEPV are optional. They are required only when a user wants to let TAlh automate changing an alarm group or channel's mask values by monitoring an EPICS database process variable or by monitoring the value of a calulated expression based on PV values.

    The first method is to monitor a single EPICS database process variable. Only only one input line is required. This line defines the forcePVName (process variable to be monitored), forceMask, forceValue, and resetValue. The forcePVName must be an existing PV in the EPICS database and can be specified as <channel_name>.<field_name>. Whenever the value of the force process variable changes to be the same as the forceValue, the Alarm Group or Channel mask will be set to the forceMask. For an Alarm Group, this means that masks of all the channels in the group and its subgroups are set to the forceMask. Whenever the value of the force process variable changes to be the same as the resetValue, these channel masks are set to their default values. The forceValue must be different from the resetValue. The default setting is forceValue = 1, and resetValue = 0. A "NE" can be used in the resetValue field to reset the masks when the value of the force process variable no longer equals the force value. Alarm Handler menu items exist which allow the user to enable/disable the Force PV, change the name of the Force PV, and change the Force Process Variable values. The force PV test uses type double for forceValue, resetValue and pv value.

    $FORCEPV forcePVName forceMask <forceValue> <resetValue>

    The second method is to monitor the value of a calculated expression. This requires multiple Force PV CALC input lines to define the expression. This CALC facility allows algebraic, relational, and logical operations on up to 6 pv values. The result of the expression is compared to the forcePV forceValue and resetValue to determine whether or not to set group/channel masks.

    To specify a forcpePV calculation expression in the alhConfig file you create the $FORCEPV record as before but you specify "CALC" instead of a PV name. Then you add a new $FORCEPV_CALC line in which you specify the calculation expression in a manner similar to the calc record expression. In fact alh uses the same code as the calc record to evaluate the expression. You specify the expression using A, B, ... instead of the pvnames. Then you add $FORCEPV_CALC_A through $FORCEPV_CALC_F lines to specify the pv names. (You can also specify constant values on these lines.) The Alarm Handler ForcePV dialog window allows users to specify or change the ForcePV CALC data.

    An example of the alhConfig file lines for a calculation forcePV is

    $FORCEPV CALC ---TL 18.321 NE
    $FORCEPV_CALC A+B+C
    $FORCEPV_CALC_A jba:alh5
    $FORCEPV_CALC_B jba:alh6
    $FORCEPV_CALC_C 5.321

    The expression is evaluated using type "double" for all pv values and constants.

    Severity Process Variable

    The line starting with $SEVRPV is optional. It is required only when a user wants to write the severity value of a group or channel to a process variable. The sevrPVName must be defined in the IOC database and is specified as <channel_name>.<field_name>. Whenever the group or channel severity changes, the new severity value is written to the severity process variable via a channel access put (ca_put) request. Writes to a severity process variable are done only when the alarm handler is in global active mode. The value -1 is written to the servrity PV when the group or channel is disabled.

    $SEVRPV sevrPVName

    Guidance

    The lines starting with $GUIDANCE are optional. They are required only when a user wants to display alarm guidance information for a group or channel. The $GUIDANCE line may be followed by a set of ascii guidance text lines with an $END line to terminate the guidance text, or alternatively, the $GUIDANCE line may contain a url address.

    $GUIDANCE

    <text lines>

    $END

    or

    $GUIDANCE urlAddress

    Alias

    The line starting with $ALIAS is optional. It is required when it is desired that the alarm handler display the specified alias text string in places where it would normally display the Alarm Group or Alarm Channel name.

    $ALIAS   anyValidTextString

    The line starting with $COMMAND is optional. It is required only when a user wants to provide the feature of starting a related process for this group or channel. When the alh operator clicks on a Process Button for an alarm group or channel in the alarm handler Main Window display one of two things occurs. If there was a single related process specified on the $COMMAND line for the group or channel, that process is invoked. If multiple processes were specified on the $COMMAND line, a popup menu of the related process names appears and the related process selected by the user is invoked.

    A single command is specified as follows:

    $COMMAND   anyValidCommandSyntax

    Multiple commands are specified with command names and command strings separated by exclamation points, "!", using the following syntax

    $COMMAND   cmd_1_name!cmd_1_string!cmd_2_name!cmd_2_string!...cmd_n_name!cmd_n_string

    Severity Command

    The line starting with $SEVRCOMMAND is optional. It is required if a process should be invoked when the alarm severity value for a group or channel changes. A single group or channel may have multiple $SEVRCOMMAND lines. This line defines the change in the severity necessary to start the process and defines the process to be started.

    Valid severity change values are -

    UP_INVALID, UP_MAJOR, UP_MINOR, UP_ANY, DOWN_MAJOR, DOWN_MINOR, DOWN_NO_ALARM, DOWN_ANY, UP_ALARM

    Status Command

    The line starting with $STATCOMMAND is optional and valid only for an Alarm Channel. It is required only when the alarm handler should start a process when the channel alarm status becomes a specified value. A single channel may have multiple $STATCOMMAND lines. This line defines the status value necessary to start the process and defines the process to be started. Valid alarm status string values can be found in the EPICS base alarmString.h header file.

    Example alarm status string values are -

    NO_ALARM, READ, WRITE, HIHI, HIGH, READ_ACCESS, LOLO, LOW, STATE, COS, COMM, WRITE_ACCESS, TIMEOUT, HWLIMIT, CALC, SCAN, LINK, SOFT, BAD_SUB, UDF, DISABLE, SIMM

    Alarm Count Filter

    The line starting with $ALARMCOUNTFILTER is optional. It is required only when the alarm handler should filter the registration of alarms for a channel. This line defines the alarm count and seconds required for alarm registration. To register as an alarm, a channel must remain in an alarm state for more than inputSeconds seconds or the channel must enter into an alarm state from a no-alarm state more than inputCount times within inputSeconds seconds.

    If inputCounts is zero, inputCounts is not used in determining alarm/no-alarm states, only inputSeconds is used to filter a channel going in and out of alarm state. If inputCounts is -1, inputSeconds only is used for filtering a channel going from no-alarm to alarm state, and a change in channel from alarm state to no-alarm state is not filtered.

    $ALARMCOUNTFILTER inputCount inputSeconds

    Beep Severity

    The line starting with $BEEPSEVERITY is optional. It is required only when the alarm handler should filter the beeping if alarms are present. This line defines the minimum severity level required for beeping. Beeping will not occur when the highest outstanding severity is less than the specified severity. Valid severity values are MINOR, MAJOR, INVALID, and ERROR.

    $BEEPSEVERITY severity

    Sample Configuration File

    The following listing shows a simple example of an alarm configuration file.

    GROUP NULL MAIN
    $COMMAND medm /home/phoebos/USER/appl/example.adl
    $GUIDANCE
    Line 1 of guidance information about main group
    Line 2 guidance.
    Line 3 guidance.
    $END

    GROUP MAIN AAA
    $COMMAND medm /home/phoebos/USER/appl/example2.adl
    $SERVPV SEVR:AI
    $FORCEPV FORCE:AI -D---
    CHANNEL AAA rai_2000
    CHANNEL AAA rai_2001

    GROUP MAIN BBB
    CHANNEL BBB rbi_000
    CHANNEL BBB rbi_2000

    GROUP MAIN CCC
    CHANNEL CCC rbo_000
    CHANNEL MAIN rbo_001

    In this example, the first group is named MAIN. The MAIN group contains three subgroups ( AAA, BBB, and CCC) and one channel (rbo-001). The AAA subgroup contains two channels: rai_2000 and rai_2001. The BBB subgroup contains the two channels: rbi_000 and rbi_2000. The CCC subgroup contains only one channel: rbo_000.

    In this example the default mask "-----" is used for every channel. That is, no masks are specified on the group and channel lines.

    In above example, $COMMAND and $GUIDANCE options are specified for the MAIN group. The $GUIDANCE option allows the user to display guidance text in a popup window when the MAIN group guidance button is pressed. The $COMMAND line option allows a user to start the display manager, medm, by pressing the MAIN group's related proccess button.

    In above example, the $COMMAND, $FORCEPV, and $SEVRPV options are specified for the AAA group. This $COMMAND option allows a user to open an xterm window from the start related process button on the AAA group line. The $FORCEPV option tells alh to add an automatic force mask event for group AAA. If the value of process variable FORCE:AI becomes 1, then the mask of all the channels in this group will be set to the forceMask, "-D---". If the value of process variable FORCE:AI becomes 0, then the mask of all the channels in this group will be reset to their default mask values. The $SEVRPV option tells alh to record the alarm severity of group AAA to the process variable SEVR:AI.

     

    Alarm Channel Mask

    Associated with each Alarm Channel are two masks (default and current). The current mask can be changed by modifying the run-time configuration of an alarm or by force process variables. The default mask is defined in the alarm configuration file.

    In the configuration file, the mask is defined by a string consisting of one or more uppercase characters.

    Add/Cancel Alarm

    The character C determines if a channel PV has a channel access subscription. Add/Cancel means that a ca_add_event is/isn't active. If ca_add_event is not active for a channel, the IOC will not send alarm events to the alarm handler for that channel.

    The presence of C means "no subscription", the absence of C means "subscribe to the alarm".

    Currently in TAlh an alarm configured with "no subscription" cannot be subscribed at run-time, therefore it is recommended not to use C in the mask.

    Enable/Disable Alarm

    The character D determines if Alarms are disabled, i.e. ignored by the alarm handler. Disabling an alarm has the effect of no display and NoAck. If an alarm is disabled the alarm status and severity are not displayed. Thus, even though the alarm is subscribed, the channel always appears to the operator to be in the NO_ALARM state. Alarm change of states will, however, still be logged if quick logging is selected.

    When a pv is enabled after it has been disabled for a while and the pv is not in alarm state but there are unacknowledged transient alarms and the alarm handler is running in global mode, an automatic acknowledgement is sent when the pv is enabled and the auto acknowledgement is logged in the opMod file if the alarm handler is running in global mode.

    " D" means alarm disabled

    Ack/NoAck

    The operator is/isn't required to acknowledge alarms.

    " A" means alarm acknowledgment is not required.

    Ack/NoAck Transient Alarms

    The operator is/isn't required to acknowledge transient alarms. A transient alarm is one that enters alarm state and then returns to normal before the operator can acknowledge the alarm.

    " T" means acknowledgment of transient alarms is not required.

    Log/No Log Alarms

    Alarms will/won't be logged.

    " L" means no alarm logging .