doc/src/user/alarm.im

.** vim: sw=4 ts=4 et :
.if false
==================================================================================
    Copyright (c) 2020 Nokia
    Copyright (c) 2020 AT&T Intellectual Property.

   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.
==================================================================================
.fi


.if false
	This imbed file contains the portion of the document that describes the
	alarm collector AIP provided by the framework.
.fi


.if pfm
    .** work round bug in cmd_ps.im
    .dv beg_table .ta $1
    .dv end_table .et
    .dv col .cl ^:
    .dv row .tr ^:
.fi

.** ------ positioning -------------------------------------

&h1(Alarm Manager Interface)
The C++ framework provides an API which allows the xAPP to easily construct and
generate alarm messages.
Alarm messages are a special class of RMR message, allocated in a similar fashion
as an RMR message through the framework's &cw(Alloc_alarm()) function.

&space
The API consists of the following function types:

&half_space
&indent
&beg_dlist( 1i &ditemtext: )
	&di(Raise) Cause the alarm to be assigned a severity and and sent via RMR
			message to the alarm collector process.

	&half_space
	&di(Clear) Cause a clear message to be sent to the alarm collector.

	&half_space
	&di(Raise Again) Cause a clear followed by a raise message to be sent to
			the alarm collector.
&end_dlist
&uindent
&space

&h2(Allocating Alarms)
The &cw(xapp::Alloc_alarm()) function provided by the framework is used to create
an alarm object.
Once the xAPP has an alarm object it can be used to send one, or more, alarm
messages to the collector.

&space
The allocation function has three prototypes which allow the xAPP to create
an alarm with an initial set of information as is appropriate.
The following are the prototypes for the allocate functions:

&half_space
.im alloc_proto.im


Each of the allocation functions returns a unique pointer to the alarm.
In the simplest form (1) the alarm is initialised with an empty meid
(managed element ID) string, and unset problem ID (-1).
The second prototype allows the xAPP to supply the meid, and in the
third form both the problem ID and the meid are used to initialise the
alarm.

&h2(Raising An Alarm)
Once an alarm has been allocated, its &cw(Raise()) function can be used
to cause the alarm to be sent to the collector.
The raise process allows the xAPP to perform the following modifications
to the alarm before sending the message:

&half_space
&indent
&beg_list(&lic1)
	&li Set the alarm severity
	&half_space
	&li Set the problem ID value
	&half_space
	&li Set the alarm information string
	&half_space
	&li Set the additional information string
&end_list
&uindent
&space

The following are the prototypes for the &cw(Raise()) functions of an alarm object:
.....



In its simplest form (1) the &cw(Raise()) function will send the alarm without making any
changes to the data.
The final two forms allow the xAPP to supply additional data which is added to the
alarm before sending the message.

Each of the raise functions returns &cw(true) on success and &cw(false) if the alarm
message could not be sent.

&h3(Severity)
The severity is one of the &cw(SEV_) constants listed below.
These map to alarm collector strings and insulate the xAPP from any future alarm collector
changes.
The specific meaning of these severity types are defined by the alarm collector and thus
no attempt is made to guess what their actual meaning is.
These constants are available by including &cw(alarm.hpp.)

&half_space
&indent
&ex_start
    SEV_MAJOR
    SEV_MINOR
    SEV_WARN
    SEV_DEFAULT
&ex_end
&uindent
&fig_cen(Severity constants available in alarm.hpp.)

&h3(The Problem ID)
The problem ID is an integer which is assigned by the xAPP.
The framework makes no attempt to verify that it has been se, nor does it attempt
to validate the value.
If the xAPP does not set the value, &cw(-1) is used.

&h3(Information Strings)
The two information strings are also xAPP defined and provide the information that
the xAPP deems necessary and related to the alarm.
What the collector expects, and how these strings are used, is beyond the scope of
the framework to describe or validate.
If not supplied, empty strings are sent in the alarm message.

&h2(Clearing An Alarm)
The &cw(Clear()) function of an alarm may be used to send a clear message.
In a manner similar to the &cw(Raise()) functions, the &cw(Clear()) functions allow
the existing alarm data to be sent without change, or for the xAPP to modify the
data before the message is sent to the collector.
The following are the prototype for these functions.


&ex_start
   bool Clear( );
   bool Clear( int severity, int problem, std::string info );
   bool Clear( int severity, int problem, std::string info, std::string addional_info );
   bool Clear_all( );

&ex_end
&fig_cen(Clear function prototypes. )
&space

Each of the clear functions returns &cw(true) on success and &cw(false) if the alarm
message could not be sent.


&space
The &cw(Clear_all()) function sends a special action code to the collector which is assumed
to clear all alarms.
However, it is unknown whether that implies &bold(all) alarms, or all alarms matching the
&cw(problem_id,) or some other interpretation.
Please consult the alarm collector documentation for these specifics.


&h2(Adjusting Alarm Contents)
It might be necessary for the xAPP to adjust the alarm contents outside of the scope of
the &cw(Raise()) function, or to adjust data that cannot be manipulated by &cw(Raise().)
The following are the (self explanatory) prototypes for the &ital(setter) functions
which are available to the xAPP.
&half_space

&ex_start
  void Set_additional( std::string new_info );
  void Set_appid( std::string new_id );
  void Set_info( std::string new_info );
  void Set_meid( std::string new_meid );
  void Set_problem( int new_id );
  void Set_severity( int new_sev );
&ex_end
&fig_cen(Alarm Setters)
&space