<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>1996</year>
<year>2016</year>
<holder>Ericsson AB, All Rights Reserved</holder>
</copyright>
<legalnotice>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
The Initial Developer of the Original Code is Ericsson AB.
</legalnotice>
<title>alarm_handler</title>
<prepared>Martin Björklund</prepared>
<responsible>Bjarne Dacker</responsible>
<docno></docno>
<approved>Bjarne Däcker</approved>
<checked>Martin Björklund</checked>
<date>1996-09-10</date>
<rev>A</rev>
<file>alarm_handler.sgml.t1</file>
</header>
<module>alarm_handler</module>
<modulesummary>An Alarm Handling Process</modulesummary>
<description>
<p>The alarm handler process is a
<seealso marker="stdlib:gen_event"><c>gen_event</c></seealso>
event manager process that receives alarms in the system.
This process is not intended to be a complete alarm handler.
It defines a place to which alarms can be sent. One simple event
handler is installed in the alarm handler at startup, but users
are encouraged to write and install their own handlers.</p>
<p>The simple event handler sends all alarms as info reports to
the error logger, and saves all in a list. This list can be
passed to a user-defined event handler, which can be installed
later. The list can grow large if many alarms are generated.
This is a good reason to install a better user-defined
handler.</p>
<p>Functions are provided to set and clear alarms. The alarm
format is defined by the user. For example, an event handler
for SNMP can be defined, together with an alarm Management
Information Base (MIB).</p>
<p>The alarm handler is part of the SASL application.</p>
<p>When writing new event handlers for the alarm handler, the
following events must be handled:</p>
<taglist>
<tag><c>{set_alarm, {AlarmId, AlarmDescr}}</c></tag>
<item>
<p>This event is generated by
<c>alarm_handler:set_alarm({AlarmId, AlarmDecsr})</c>.</p>
</item>
<tag><c>{clear_alarm, AlarmId}</c></tag>
<item>
<p>This event is
generated by <c>alarm_handler:clear_alarm(AlarmId)</c>.</p>
</item>
</taglist>
<p>The default simple handler is called <c>alarm_handler</c> and
it can be exchanged by calling
<seealso marker="stdlib:gen_event#swap_handler/3"><c>gen_event:swap_handler/3</c></seealso>
as <c>gen_event:swap_handler(alarm_handler, {alarm_handler, swap},
{NewHandler, Args})</c>. <c>NewHandler:init({Args, {alarm_handler,
Alarms}})</c> is called. For more details, see
<seealso marker="stdlib:gen_event"><c>gen_event(3)</c></seealso>
in STDLIB.</p>
</description>
<funcs>
<func>
<name>clear_alarm(AlarmId) -> void()</name>
<fsummary>Clears the specified alarms.</fsummary>
<type>
<v>AlarmId = term()</v>
</type>
<desc>
<p>Sends event <c>clear_alarm</c> to all event handlers.</p>
<p>When receiving this event, the default simple handler
clears the latest received alarm with id <c>AlarmId</c>.</p>
</desc>
</func>
<func>
<name>get_alarms() -> [alarm()]</name>
<fsummary>Gets all active alarms.</fsummary>
<desc>
<p>Returns a list of all active alarms. This function can only
be used when the simple handler is installed.</p>
</desc>
</func>
<func>
<name>set_alarm(alarm())</name>
<fsummary>Sets an alarm with an id.</fsummary>
<type>
<v>alarm() = {AlarmId, AlarmDescription}</v>
<v>AlarmId = term()</v>
<v>AlarmDescription = term()</v>
</type>
<desc>
<p>Sends event <c>set_alarm</c> to all event handlers.</p>
<p>When receiving this event, the default simple handler
stores the alarm. <c>AlarmId</c> identifies the alarm
and is used when the alarm is cleared.</p>
</desc>
</func>
</funcs>
<section>
<title>See Also</title>
<p><seealso marker="kernel:error_logger"><c>error_logger(3)</c></seealso>,
<seealso marker="stdlib:gen_event"><c>gen_event(3)</c></seealso></p>
</section>
</erlref>