~rdoering/ubuntu/karmic/erlang/fix-535090

<?xml version="1.0" encoding="latin1" ?>

<!DOCTYPE erlref SYSTEM "erlref.dtd">

 

<erlref>

  <header>

    <copyright>

      <year>1996</year>

      <year>2007</year>

      <holder>Ericsson AB, All Rights Reserved</holder>

    </copyright>

    <legalnotice>

  The contents of this file are subject to the Erlang Public License,

  Version 1.1, (the "License"); you may not use this file except in

  compliance with the License. You should have received a copy of the

  Erlang Public License along with this software. If not, it can be

  retrieved online at http://www.erlang.org/.

 

  Software distributed under the License is distributed on an "AS IS"

  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See

  the License for the specific language governing rights and limitations

  under the License.

 

  The Initial Developer of the Original Code is Ericsson AB.

    </legalnotice>

 

    <title>alarm_handler</title>

    <prepared>Martin Bj&ouml;rklund</prepared>

    <responsible>Bjarne Dacker</responsible>

    <docno></docno>

    <approved>Bjarne D&auml;cker</approved>

    <checked>Martin Bj&ouml;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 <c>gen_event</c> event manager

      process which 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 start-up, 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 of them in a list which can be

      passed to a user defined event handler, which may be installed at

      a later stage. The list can grow large if many alarms are

      generated. So it is a good reason to install a better user defined

      handler.

      </p>

    <p>There are functions to set and clear alarms. The format of

      alarms are defined by the user. For example, an event handler

      for SNMP could be defined, together with an alarm 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 may be exchanged by calling <c>gen_event:swap_handler/3</c>

      as <c>gen_event:swap_handler(alarm_handler, {alarm_handler, swap}, {NewHandler, Args})</c>. <c>NewHandler:init({Args, {alarm_handler, Alarms}})</c> is called. Refer to gen_event(3)

      for further details.

      </p>

  </description>

  <funcs>

    <func>

      <name>clear_alarm(AlarmId) -> void()</name>

      <fsummary>Clear the specified alarms</fsummary>

      <type>

        <v>AlarmId = term()</v>

      </type>

      <desc>

        <p>Clears all alarms with id <c>AlarmId</c>.

          </p>

      </desc>

    </func>

    <func>

      <name>get_alarms() -> [alarm()]</name>

      <fsummary>Get 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>Set an alarm with an id</fsummary>

      <type>

        <v>alarm() = {AlarmId, AlarmDescription}</v>

        <v>AlarmId = term()</v>

        <v>AlarmDescription = term()</v>

      </type>

      <desc>

        <p>Sets an alarm with id <c>AlarmId</c>. This id is used at a

          later stage when the alarm is cleared.

          </p>

      </desc>

    </func>

  </funcs>

 

  <section>

    <title>See Also</title>

    <p>error_logger(3), gen_event(3) 

      </p>

  </section>

</erlref>