Chapter 1: Preface

Purpose of Document

This document presents a description of the
functions provided by the Alarm Handler (ALH) and describes its
graphical user interface. The purpose of this guide is to explain how
to use and configure the Alarm Handler.

Audience

This guide is written for individuals who
wish to use and understand the Alarm Handler, namely accelerator
operators and accelerator physicists.

Background/Environment

The Alarm Handler is part of the
Experimental Physics and Industrial Control System EPICS) co-developed
by Los Alamos National Laboratory and Argonne National Laboratory.
EPICS consists of a set of software components and tools with which
application developers and designers can create an extremely flexible
control system that minimizes the need for custom coding and helps
ensure uniform operator interfaces. The Alarm Handler is one of the
EPICS control system tools.

EPICS Control System Perspective

The Alarm Handler provides an interface
between an operator and the EPICS control system database. The database
is the interface between instrumentation hardware and all the EPICS
control system software tools. This database is distributed throughout
a network on I/O Controllers and contains records that are used to
transfer information to and from the attached instrumentation to the
Alarm Handler and other EPICS software tools.

Database records are made up of fields of
various types. Scan fields specify under what circumstances a record
will be processed. Convert fields determine how to convert a raw signal
to/from engineering units. Device fields are used to specify the
software interface to the device. Operator display fields specify how
to display the record value. Processing fields are used by the run-time
code for processing the record. There are also alarm fields that are
used to specify conditions for alarm and to determine if the record is
in an alarm state. Most fields are accessible throughout the network by
means of the channel access interface software layer by specifying the
record name and the field name. All monitoring and control operations
are performed through the database.

Alarm Fields

Each record in the database includes fields
for specifying the record's current alarm condition. There are two
parts to this alarm condition: the alarm status and the severity of
that alarm status. Alarm status and severity values are set and checked
whenever a record is processed. When a new condition is detected, a
routine is called to send a message to each process monitoring this
record. The Alarm Handler is one of these processes.

Each database record also includes two
fields for specifying the record's current alarm acknowledgment state.
The unacknowledged severity field is the highest severity value of
unacknowledged alarms, and the acknowledge transients field specifies
whether transient alarms need to be acknowledged. A transient alarm is
when the record enters alarm state and then returns to normal before
the alarm is acknowledged. When any change to these fields is detected,
a routine is called to send a message to each process monitoring this
record.

The Alarm Handler filters alarm messages and
displays alarms to the operator hierarchically. The alarm configuration
structure defined in the alarm configuration file is used to determine
this hierarchical display. The Alarm Handler brings alarms to the
operator's attention, logs the alarms, allows the operator to
acknowledge alarms, and gives the operator guidance on handling of
specific alarms.

Document Organization

Chapter 1 is this
Preface describing the users guide. Chapter 2
is an Introduction to the Alarm Handler and describes the scope of the
tool and explains some Alarm Handler terminology.
Chapter 3 explains how to invoke the Alarm Handler and describes
the command line options. The Main Window is explained in
Chapter 4 and Chapter 5 contains a
description all Main Window menu functions. The content of an alarm
configuration file is described in Chapter 6.
An index of terms is available at the end of the document. Using the
alarm configuration mode will be explained in Chapter 7 of a future
version of this document.

Chapter 2: Introduction

What is the Alarm Handler?

The Alarm Handler is an interactive
graphical application used primarily by accelerator operators and
physicists to display and monitor EPICS database alarm states. It
serves as an interface between an operator and the EPICS database and
it communicates with the database using channel access function calls.
The user interface for the Alarm Handler contains a hierarchical
display of an alarm configuration structure allowing both high level
and detailed views of the alarm configuration structure in one window.

The alarm handler is a Motif and X11 Window
based application written in C language, and it runs on Unix, Linux,
and Windows 98/XP/.../8 hosts. The Alarm Handler source code is
available via WWW as an EPICS extension.

Purpose of the Alarm Handler

The Alarm Handler monitors alarm conditions
of EPICS database records. The primary responsibilities of the Alarm
Handler (ALH) are to:

Bring alarms to the operator's attention.

Provide the operator guidance for handling of specific alarms

Allow the operator to globally acknowledge alarms.

Provide a graphical view of current database alarms

Provide for logging alarms and display of the logged alarm history

System Requirements

The Alarm Handler currently requires either
an IBM personal computer with Windows 98/XP/.../8 and Hummingbird's
Exceed software or a workstation running a Unix type operating system
with X Windows and Motif Version 1.2 or above. The Alarm Handler also
requires the global alarm acknowledgment in EPICS base Version 3.11 or
above.

Alarm Handler Terminology

An unexpected change of state for an EPICS
database record. Examples of alarm conditions are:

Deviations from tolerance band

Software or Hardware errors

Loss of communication to hardware or linked records

There are two parts to an alarm: the alarm
status and the severity of that alarm status. Alarm status and severity
are set and checked whenever a record is processed. When a change is
detected, a routine is called which sends a message to each process
monitoring this record. The Alarm Handler may be one of these
processes.

An Alarm Channel will be considered in an
error state if there is a loss of communication between the Alarm
Handler and the channel or if a channel access exception or other error
occurs on the channel.

The alarm handler can execute in either a
local or global mode. Global mode means that unacknowledged severity
and acknowledge transients states will be determined by the current
value of the fields in an EPICS database record. Local mode means that
the unacknowledged severity and acknowledge transients states are local
alh settings. Command line options determine the execution mode with
local mode being the default setting. There is no way to change between
local and global mode during execution.

The alarm handler can execute in either a
passive (monitor) or active (modify) state. Passive state means that
the alarm handler does not allow alarm acknowledgment and does not
allow changes to acknowledge transients settings. There will be no
channel access puts when executing in a passive state. The
passive/active execution state is determined by a command line option
with active state being the default and there is no way to change the
current state during execution.

In Global Mode the Alarm Handler reads all
ACKT and ACKS fields of the configured Alarm Channels: the Alarm
Handler starts with the complete memory of still unacknowledged alarms.
These alarms will have to be acknowledged, even if some may not be
active anymore. (If a channel's ACKT field is set, any transient alarm
will be latched and has to be acknowledged later on.) Global Mode also
makes the Alarm Handler write alarm acknowledgements into the channels
using Channel Access, i.e. all other Alarm Handlers in Global Mode will
receive an alarm acknowledgment. Usually, all Alarm Handlers in the
Control Room will run in Global Mode, so that any alarm has to be
acknowledged only on one of the Alarm Handlers.

In Local Mode, the Alarm Handler starts
without reading open acknowledgements from the channels, all alarm
acknowledgements made will be valid only for this instance of the Alarm
Handler. Usually, Alarm Handlers outside of the Control Room will run
in Local Mode.

Alarm Handler Windows

The Alarm Handler display consists of two
types of windows, a runtime window and a Main Window. While the Alarm
Handler is executing, the runtime window is always displayed.

The runtime window is a small icon like
window that contains a single button containing the name of the alarm
configuration main Alarm Group. The color of this button is used to
show the highest alarm severity of any outstanding alarms. Beeping and
blinking of the button is used to show the presence of unacknowledged
alarms. Pressing the runtime window button will open the Alarm Handler
Main Window or, if already open, bring the Main Window to the top of
the window stack. The Close or Quit item on the window manager menu
allows the user to exit the Alarm Handler.

The Alarm Handler Main Window is divided
into three parts: a menu bar, an alarm configuration display area, and
a message area.

On the menu bar, there are selections for
pull-down menu items that perform all the functions of the Alarm
Handler.

The alarm configuration display area is
divided into two major parts: an alarm configuration tree structure
display and an Alarm Group contents display. The current alarm
configuration tree structure appears in the first area, and a list of
the contents of the currently selected Alarm Group from the alarm
configuration tree structure appears in the second area. Color is used
to show alarm severity. A single character severity code is also
provided for an operator with a monochrome display.

The message area displays the name of the
current configuration file and has indicators to show definitions of
the summary alarms fields for the currently open alarm configuration
file.

Alarm Handler Files

There are three files used by the alarm
handler while it is executing. They are the alarm configuration file,
the alarm log file, and the operation modification log file.

The alarm configuration file is the only
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 specifies the Alarm Groups, Alarm Channels, channel
masks, hierarchy of Alarm Groups, and other configuration information.
The format and contents of the alarm configuration file are described
in Chapter 6.

The user can specify the desired alarm
configuration file using a file selection window at Alarm Handler
start-up, or on the command line.

The user can change to a new alarm
configuration file while the Alarm Handler is running by using the
File/Open item on the main window menu bar.

The Alarm Log output file contains a log of
alarm state changes. For each change of alarm state, channel access
connection state, and read/write access state, the date, time, channel
name and current state values are recorded. The alarm log file is an
ASCII file that can be displayed on any terminal or sent to a printer.

The Operation Modification Log output file
contains a log of alarm acknowledgments and changes the user has made
to the current alarm handler configuration. For each operator
modification the date, time and description of the operator's
modification are recorded.

Chapter 3: Starting ALH

Before invoking the Alarm Handler for the
first time, the path to the executable and configuration files must be
established. Contact your EPICS administrator to find the locations of
the Alarm Handler executable, alh, and your site's Alarm Handler
configuration input files.

Environment Variables

The optional environment variable
ALARMHANDLER can be used to point the Alarm Handler to a desired
working directory. If ALARMHANDLER is not set, the current
working directory is assumed. If the alarm configuration file resides
in a different directory (e.g. /home/cs/appl/ah
/dev) from the current working directory, under UNIX
ALARMHANDLER can be set to point to the desired path by issuing the
UNIX c shell command:

The environment variable ALHMAINFONT may be
used to set the Runtime Window button font e.g.

export
ALHMAINFONT='-*-utopia-bold-r-normal--0-720-75-75-p-0-*-*'

Command Line Syntax

Once the path is properly set, invoke the
Alarm Handler by executing the command:

alh

This command displays a file selection box
in which to specify an alarm configuration file name. The default path
for files is the directory defined by the ALARMHANDLER environment
variable or the current directory and the default alarm handler output
file names are ALH-default.alhAlarm and
ALH-default.alhOpmod . If there is an alarm configuration file in
the current directory with the name ALH-default.alhConfig, it will be
used as the input configuration file.

The Alarm Handler command has several
options and a usage message similar to the table below will be
displayed if you enter: "alh -help".

The '-B' option enables an operator
to send messages using message broadcasting. The default is no message
broadcasting. When this option is specified a send message menu item
appears on the Main Window menu, and a message input dialog popup
appears when the menu item is selected. The operator can then type in a
message that will be sent to other alh processes when OK is pressed. A
popup dialog box containing a sent message will appear when an Alarm
Handler process receives a message.

The ' -caputackt ' option specifies
that the Alarm Handler should write the alarm configuration file ACKT
values using channel access puts to the EPICS database records when the
Alarm Handler reads the configuration file. The default is not to write
the alarm configuration file ACKT values.

The ' -D ' option allows running the
Alarm Handler without creating and/or modifying the alarm log and alarm
opmod files. This is useful if one alh process runs without this
option, creating and modifying some fixed named alarm log files and all
other alh process specifying the same file names run with the -D option
which does not allow them to overwrite the alarm log files.

The '-filter f-opt' option sets the
initial alarm display filter for the Alarm Handler (see
->>Menu Functions->Setup Menu->Display Filter). `f-opt' may be one
of `n[o]' (for no filter), `a[ct]' (show active alarms) or `u[nack]'
(show only unacknowledged alarms). Default is `no', i.e. all Alarm
Groups and channels in the current configuration will be displayed.
This option is particularly useful in combination with `-mainwindow' to
start Alarm Handlers from operator panels.

The '-global' options specifies that
the alarm handler should run in a global mode. In global mode an Alarm
Channel's unacknowledged severity and it's acknowledge transients state
will be determined by the current value of the EPICS database record's
ACKS and ACKT field settings. In local mode, the default mode, the
unacknowledged severity and acknowledge transients settings are local
to the alarm handler.

The '-L' option activates a file
locking system (based on lockf(), i.e. NFS-safe) making sure that only
one of multiple Alarm Handlers with enabled log writing has access to
the log. If the `master' (i.e. actively logging) process dies, another
Alarm Handler will seamlessly take over logging. Default is not to use
this locking mechanism.

The '-L lockfile' option specifies a
lock file directory with file name prefix. A ".LOCK" suffix will be
appended. The default is the configure filename with directory from the
-f option or the current working directory.

The '-m maxrecords' option allows the
user to specify the maximum number of records that the alarm handler
will allow in the alarm log file. If this number of records is reached,
new records will overwrite old alarm records. The default number of
records is 2000. Specifying zero means the file can have an unlimited
number of records.

The `-mainwindow' option makes the
Alarm Handler start with the Main Window instead of the Runtime Window.
This is useful in conjunction with the `-filter f-opt' option to start
Alarm Handlers from operator panels. The default is to start with the
Runtime Window.

The `-noerrorpopup' option tells the
Alarm Handler not to use popup boxes for displaying errors. This is
useful for Alarm Handlers running as overhead displays (and no mouse
attached to handle popups). The default is to use popups.

The '-P' option allows simultaneously
printing of new alarms to the log file and to a TCP printer (socket
connection). The user must specify all three printer values:
'Name:port:colorModel ' (where colorModel is mono,hp_color,...).
Currently the printing is done asynchronously by adding an additional
task "alh_printer". (This option is still under construction and will
use pipes in the future)

Specifying this '-S' option means
that the alh will execute in a passive (monitor) mode. This means that
alh can not send channel access acknowledgment of alarms and can not do
channel access puts to the acknowledge transients fields and cannot
write to the severity process variable. It is useful for a non-operator
alh user.

With the '-T' option, alarmLog file
names will have "date" extensions like YYYY-MM-DD, and log files are
automatically switched at midnight. For this option, there is a Main
Window menu browser that is displayed after pressing View-"Alarm Log
File Window". This browser allows searches in the AlarmLogFile and find
all alarms inside of [t1,t2]-diapason containing some <String>.

When executing on Unix, the 'alh'
command line accepts all X options such as '-bg color_name' and
'-fg color_name' and '-geometry geom_spec'

Configuration File Selection Window

If the Alarm Configuration file is not
specified on the command line, a file selection window is presented so
the user can select the desired Alarm Configuration file

There are several ways to select the
directory using this window:

Double-click on the appropriate Directories entry.

Type the directory name in the Filter window and click
on Filter .

Type the directory name in the Selection window and
click on OK .

Once in the appropriate directory, there are
several ways to select the desired file:

Double-click on the appropriate Files entry.

Click on the appropriate Files entry and click on OK .

Type the file name in the Selection window and click on OK
.

Cancel ends the Alarm Handler
session.

Help has not been implemented in this
release.

Runtime Window

Once an Alarm Configuration file has been
selected, the Runtime Window is displayed on the user's screen as a
small icon like window. This window contains one button labeled with
the name of the Alarm Configuration file's Main Alarm Group (or the
Main Alarm Group's alias if it was defined) followed by the group's
Current Mask Summary characters if the mask contains characters other
than "-".

The color of the button indicates the
highest outstanding alarm severity level in the active alarm
configuration.:

White: Invalid Alarm

Red: Major Alarm

Yellow: Minor Alarm

Background color: NO Alarm

There will be beeping and the button will
blink to indicate the presence of unacknowledged alarms.

Click the Runtime window button to open the
Alarm Handler Main window or, if the Main window is already open,
clicking the button will bring the Main window to the top of the window
stack. This window contains the hierarchy of Alarm Groups and Alarm
Channels (Process Variables) being monitored. The left half of the
window contains the tree-structure of the Alarm Group, and the right
side contains the contents of the selected Alarm Group. This window
will be discussed in detail in the next chapter.

Chapter 4: Main Window

Main Window Description

When the Runtime Window button is clicked,
the Main Alarm Handler window. is displayed. The Alarm Handler Main
Window is divided into two major parts: an alarm configuration tree
structure display and an Alarm Group Contents display. This window also
contains a menu bar and a message area.

This window shows the hierarchy of Alarm
Groups and Alarm Channels (EPICS database records) being monitored. The
left half of the window contains the tree-structure display of Alarm
Groups, and the right side displays the contents of the tree-structure
display's currently selected Alarm Group.

The current alarm configuration tree
structure of Alarm Groups is graphically displayed as Group Summary
Lines which are described in Group Summary Line
. Buttons on the tree structure display allow the user to expand or
deflate the alarm configuration tree structure.

Each group name in the configuration tree
structure is displayed on a separate line. The following items appear
in each group line of the tree structure display.

Single character color coded acknowledgment button

Single character color coded severity code

Group name selection button

Optional subgroups arrow button

Optional guidance button

Optional related process button

Current mask summary

Optional Group Beep Severity character

Alarm severity summary

The configuration tree structure display has
a scrolling/paging facility and a display resize facility. This allows
users to view an alarm configuration tree structure too large to
display on one screen.

The user will be able to choose any Alarm
Group for display by pressing the Alarm Group name button from the
configuration tree structure display. Selecting an Alarm Group will
cause the Alarm Group contents display to show one level of the alarm
subgroups and the Alarm Channels associated with the selected group.

The Alarm Group contents display for the
currently selected Alarm Group contains group summary lines for each
alarm subgroup followed by channel status lines for each Alarm Channel
in the selected Alarm Group.

Each subgroup or channel name in the summary
line is displayed with a color identifier indicating whether the name
is an Alarm Group name or a channel name.

The Alarm Group display has a
scrolling/paging facility to allow users to view an Alarm Group too
large to display in one screen.

The message area shows the current execution
mode (local or global), the current execution state (passive or
active), the name of the current configuration file. It also contains
buttons to silence alarms, and explanatory descriptions of the mask
abbreviation codes and status data which appear in the group summary
and channel status lines.

There are two Silence buttons which toggle
beeping on or off. The Silence Current button turns off current alarm
beeping until a new alarm occurs. The Silence Interval button toggles
beeping of current and future alarms off for a specified interval. When
pushed in, beeping is turned off, when out, beeping is toggled on.
Beeping occurs only when there are unacknowledged alarms. The main
window background color is changed when beeping is turned off. Setup
menu items can be used to change the specified time interval.

Group Summary Line

This display line summarizes the status of
all alarms for the group named in this line and all lower level groups.
The group summary display consists of the following items:

A one-character acknowledgment button is
activated only if an unacknowledged alarm is present for the group and
the alarm handler is executing in active (modify) state. This button is
color-coded representing the highest severity unacknowledged alarm as
follows:

White: V - Invalid Alarm

Red: R - Major Alarm

Yellow: Y - Minor Alarm

Background color - No Alarm

This button describes the highest severity
of unacknowledged alarms for this group and all associated subgroups.

Clicking on this button while alh is
executing in active state will send channel access alarm
acknowledgments to all Alarm Channels associated with the group. It has
the same effect as individually acknowledging each channel in an
unacknowledged alarm state.

A one-character severity display code. It is
present only if at least one channel associated with the group is in
alarm or in an error state. It is color-coded and represents the
highest severity outstanding alarm as follows:

White: E - Error state

White: V - Invalid Alarm

Red: R - Major Alarm

Yellow: Y - Minor Alarm

The code shows the highest severity
unacknowledged alarm for this group and all it's subgroups.

ALH allows the operator to choose any Alarm
Group by selecting the Group Name button on the group summary line. The
result is to display one level of the contents associated with the
selected group. This group also becomes the currently selected group.

ALH allows drag and drop of the alarm group
name text associated with the Group Name Selection Button. This may be
used to view the alarm group name when an alias is displayed. The user
should hold down the middle (second) mouse button when the mouse cursor
is positioned over a Group Name Button. A text box containing the alarm
group name will appear. When the user moves the mouse with the mouse
button still depressed, the box will follow the mouse around until the
user finally releases the button. The alarm group name text will then
be dropped into the release location which must be a valid drop
location.

The Current Mask Summary Display is a five
character mask display. Each character is a"-" or one of the following:

C: Cancel Alarm

D: Disable Alarm

A: NoAck Alarm or H: NoAck 1hr Timer Active

T: NoAck Transient Alarm

L: NoLog Alarm

Mask values are described in
Alarm Channel Mask. If the current mask for any channel connected
with this group or any subgroup has the above mask condition set, the
corresponding character is displayed, otherwise the character "-" is
displayed. For example the string "--A--" means that at least one
channel has the NoAck mask set and that no channels have any other
masks set.

Alarm Channel Status Line

A one character acknowledgment button. It is
activated only if an unacknowledged alarm is present for the channel
and the alarm handler is executing in active (modify) state. It is
color coded, and represents the highest severity unacknowledged alarm
as follows:

White E - Error state

White: V - Invalid Alarm

Red: R - Major Alarm

Yellow: Y - Minor Alarm

Background color - No Alarm

Clicking on this button while alh is
executing in active state will send a channel access alarm
acknowledgments to the Alarm Channel. A warning popup dialog with the
message that alarm acknowledgment is not allowed in passive state will
appear if the alarm handler is executing in passive (monitor) state.

This button contains the database record
name associated with the channel or the alias text if an alias is
defined for this channel. The button is color coded in gray so that an
operator can easily distinguish channels from groups. Selecting this
button makes the channel the currently selected item.

ALH allows drag and drop of the record name
text associated with the Channel Name Selection Button. This may be
used to view the database record name when an alias is displayed. The
user should hold down the middle (second) mouse button when the mouse
cursor is positioned over a Channel Name Button. A text box containing
the record name will appear. When the user moves the mouse with the
mouse button still depressed, the box will follow the mouse around
until the user finally releases the button. The alarm channel name text
will then be dropped into the release location which must be a valid
drop location.

Following the current mask characters are
the channel's current alarm status and severity and the highest
unacknowledged alarm severity. Current status and severity is present
only if the channel is in an alarm state. Highest unacknowledged alarm
severity is present only if an unacknowledged alarm is present.

The " Save As" menu item, allows the user to
save the current alarm configuration structure and current alarm
configuration settings to a new or existing file. A dialog appears
which prompts the user to supply the name of a file to write to. If the
user gives the name of an existing file, another popup dialog will give
a warning and ask the user if the existing file can be overwritten.

Selecting the Close item on the File menu
can close the alh Main Window. This Main Window can be redisplayed
again with a mouse click on the runtime window button.

Action Menu Commands

The Action Menu provides selections which
affect the currently selected Alarm Group or Channel. The action
selections "Acknowledge Alarm", "Display Guidance", and "Start Related
Process" can also be accomplished by clicking buttons on the tree
structure or group contents display. The "Send Message" item is present
only when the Message Broadcasting option, "-B", is present on the
command line.

Alarm acknowledgment is only allowed while
the alarm handler is executing in active (modify) state. The Alarm
Handler user can acknowledge an alarm for the currently selected Alarm
Group or Channel by selecting the "Acknowledge Alarm" item on the
Action menu. Selecting this item for an Alarm Group acknowledges all
Alarm Channels associated with the group. It has the same effect as
acknowledging each channel individually.

When executing in global mode the Alarm
Handler performs an alarm acknowledgment by sending a channel access
alarm acknowledgment command to the channel and logging the alarm
acknowledgement to the operator modification log file. The alarm
acknowledgment indicators (color, blinking, and beeping) will change
only after a channel access alarm event with the modified
unacknowledged severity is received. Other executing alarm handler
processes and other EPICS tools monitoring alarm events will also
receive this alarm event.

When executing in local mode the alarm
acknowledgment indicators (color, blinking and beeping) and the local
unacknowledged severity level setting will change to reflect a local
alarm acknowledgment and the alarm acknowledgement will be logged to
the operator modification log file.

When "Display Guidance" is selected,
associated guidance text lines for a selected Alarm Channel or Alarm
Group will be displayed. Guidance text is intended to suggest possible
reasons why this group or channel might alarm and actions that might
remove the alarm condition. This menu item is inactive if guidance
information is not available for the currently selected Alarm Group or
Alarm Channel.

The guidance text display is a popup window
displaying lines of ascii text if text was specified in the alarm
configuration file. If a URL address was specified in the configuration
file, the default browser will be invoked and display the text at the
specified URL address.

Selecting "Start Related Process" will
initiate execution of an Alarm Group or Alarm Channel's related process
which was specified in the alarm configuration file. This item will be
inactive if a related process was not specified for the currently
selected Alarm Group or Alarm Channel.

This item displays a dialog box that allows
the operator to change values of the Force Process Variable. The Force
Process Variable is described in a later chapter. The user can change
the name of the Force PV, the values of the Force Process Variable
which will cause the Alarm Channel masks to be set and reset, and the
actual mask the Force Process Variable will force on the group. The
user can also disable and enable the Force PV. The force value must be
set to a value different than the reset value.

There are four action buttons on this dialog
box: Apply, Cancel, Dismiss, and Help. The Apply button will accept and
apply the user entered changes. The Cancel button will discard the user
entered changes in this dialog box and reset them to the original
values. The Dismiss button will close this popup dialog, and the Help
button will display a Force PV help information dialog.

Selecting "Force Mask" will popup a dialog
box which allows the operator to change the mask for the currently
selected group or channel. Changing a group mask will actually change
the mask of all Alarm Channels within that group. Three masks are
displayed: 1) the current mask, 2) the reset mask, valid for Alarm
Channels only, which is the mask specified in the alarm configuration
file, and 3) the mask to force, which the user defines by pressing one
or more of the 5 state buttons below the mask.

.

The mask to be used for forcing (5
characters) may be any combination of -,C,D,A,T,L

There are four action buttons on this dialog
box: Apply, Reset, Dismiss and Help. The Apply button will set the mask
of all the Alarm Channels within this group to the mask as shown in the
Mask line. The Reset button will reset the mask of each channel within
this group to its own default mask defined in the alarm configuration
file. The Dismiss button will cancel the force mask option and close
the dialog window. The Help button will give force mask help
information.

This menu item allows the operator to force
or reset a specific bit of the current mask. For example, if the
operator chooses "Add" in the "Add/Cancel Alarms" line then the
Add/Cancel field of the current mask for all channels in the group are
forced into the "Add" event state. Similarly choosing "Cancel" cancels
the channel access add event state for all the channels. If "Reset" is
chosen, the Add/Cancel field of the current mask for each channel in
the group reverts to the default state defined in the active
configuration file. Mask values are described in a later chapter.

This menu item gives the operator the
ability to change the beep severity on individual channels or groups. A
beep severity indicator will appear after the mask on the group
(highest existing) and channel lines. The beep severity indicators are
E=error, V=invalid, R=major, Y=minor. Beep Severity can be changed to
MINOR, MAJOR, INVALID, or ERROR. If beep severity is set to MINOR,then
MINOR, MAJOR, INVALID, and ERROR unacknowledged alarms will cause
beeping. The -s command line option, silent execution, will override
all menu and config file beep severity settings.

This menu item gives the operator the
ability to set the noAck mask field of a group or channel to No
Acknowlegment Necessary for one hour and have it automatically set to
the reset value (config file value) after the hour expires. An "H" will
be put into the noAck position of the mask on the group or channel line
during the noAck hour. When a no-Ack timer is created, it will cancel
any existing timers in any subgroups and channels. When a timer expires
it will not reset any subgroups or channels that have an existing (i.e.
more recent) timer.

The "Send Message" menu item allows alarm
handler operators to send and receive messages to other alarm handler
operators. A message input dialog popup appears when the "Send Message"
menu item is selected. The operator can then type in a message that
will be sent to other alh processes when OK is pressed. A popup message
dialog containing the sent message will appear on other Alarm Handler
processes when they receive the message. The "Send Message" menu item
appears on the Action menu only if the Message Broadcasting option,
"-B", is present on the alh command line.

View Menu Commands

The View menu allows the user to change the
view of Alarm Groups in the current alarm configuration tree structure
display. This menu also provides options for viewing the current
working configuration file, alarm log file, and operation modification
file in scrolled windows.

The View menu allows viewing of logged
events while they take place. A user can simultaneously view both the
alarm log file and the operator modification log files. When View is
chosen, the sub-menu is presented.

The user selects this menu item to expand
the currently selected collapsed Alarm Group in the tree structure
display to graphically display one level of its alarm subgroups in the
tree structure display.

The user uses this menu item to expand or
collapse all groups in the alarm configuration tree structure display
to graphically show all the groups and subgroups on the current alarm
configuration tree structure display.

Selecting "Configuration File" brings up a
scrolled window that displays the contents of the current configuration
file. If INCLUDE lines are present the contents of the included files
are recursively displayed.

Selecting "Alarm Log File" brings up a
scrolled window displaying time stamped alarm events in the alarm log
file. Any new alarms logged into the alarm log file appear
simultaneously in this window.

The date and time, Alarm Channel name, alarm
status, alarm severity, and channel value are displayed when the Alarm
Handler is executing in local mode. The highest unacknowledged severity
and the acknowledge transients field values are also logged if the
Alarm Handler is executing in global mode.

Selecting "Operation Log File" brings up a
scrolled window showing the current content of the Operation
Modification Log file. This file contains a log of time stamped
operator configuration modification events. Any newly logged operation
events appear simultaneously in this window. The top level Alarm Group
name appears on each log line.

ALH does not allow an operator to view a log
file that exceeds 1 Megabyte. When the log file exceeds 1 Megabyte, a
new log file must be used in order for an operator to be able to view
the log process within the ALH.

The Alarm Handler allows the operator to
display all the current configuration settings for any selected Alarm
Group or Alarm Channel.

Setup Menu

The Setup menu provides the option of
overriding initial settings for the alarm configuration, the alarm log,
and the operation modification files.When this menu is selected, the
Setup sub-menu, is presented

If one of the file options is chosen, a file
selection dialog popup window appears and the operator is allowed to
choose a new file. The operation of the file selection box is described
in Configuration File Selection Window. The
file selection changes are always logged in the operation modification
file.

Display Filter

The user is allowed to set an alarm filter
to display active alarms only. When the filter is set to Active Alarms
Only, only those groups or channels with an outstanding alarm will be
displayed. When the filter is set to Unacknowledged Alarms Only, only
those groups or channels with an outstanding unacknowledged alarm will
be displayed. When the selection is set to No Filter, all Alarm Groups
and Alarm Channels in the current configuration will be available for
display.

The operator can specify the beep condition.
The beep condition is the minimum alarm unacknowledged severity
necessary for beeping. The default startup value is MINOR, or a startup
severity can be specified in the alarm configuration file. The ALH Beep
Severity can be changed to MINOR, MAJOR, or INVALID. If the beep
condition is set to MINOR,then MINOR, MAJOR, INVALID, and ERROR
unacknowledged alarms will cause beeping. The -s command line option,
silent execution, will override all menu and config file beep severity
settings.

The Silence Time Interval menu item allows
the user to select a silence interval of 5, 10, 15, 30, or 60 minutes.
The selected interval determines the silence interval for the Silence
Time Interval button on the Main Window message area and text for the
selected interval appears next to the Silence Time Interval button.

The alarm log file contains the log of alarm
changes of states. The Alarm Handler allows the operator to specify an
alarm log file name that differs from the current setting. If it does
not exist, it will be automatically created. All new alarm state
changes will be logged to this file. A file selection dialog window is
used to set a new Alarm Log File name.

The Alarm Handler allows the operator to
specify an operation modification log file that differs from the
current setting. If it does not exist, it will be automatically created
by ALH. All subsequent operation changes will be logged to this new
operation modification file. A file selection dialog window is used to
set a new Operation Modification Log File name.

Help Menu

The Help menu item will display this "Alarm
Handler User Guide" when selected.

When the About menu item is chosen,
information about the current version of the alarm handler is
displayed.

Chapter 6: Alarm Configuration File

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 ALH-default.alhConfig.

Input Format

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

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, ALH
will do CA puts of the specified value to the specified pv at the
specified rate (in seconds). The heartbeatPVName must be an existing PV
in the EPICS database and can be specified as
<channel_name>.<field_name>.

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

The channel <mask> is optional and defaults
to no mask (i.e. -----). 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.

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.

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.

The lines starting with $FORCEPV are
optional. They are required only when a user wants to let ALH 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.

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.

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.

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.

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

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.

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.

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.

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.

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.

Associated with each Alarm Channel are two
five bit masks (default and current). The current mask can be changed
by force commands or by force process variables. The default mask is
defined in the alarm configuration file. A reset command forces all
associated masks to return to the default values.

This mask bit determines if a channel
access add event is active. 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.

Alarms aren't/are 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 a ca_add_event is in effect, the channel always
appears to the operator to be in the NO_ALARM state. Alarm change of
states will, however, still be logged unless NoLog is in effect.

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.