doc/src/user/alarm.im

   1 .** vim: sw=4 ts=4 et :
   2 .if false
   3 ==================================================================================
   4     Copyright (c) 2020 Nokia
   5     Copyright (c) 2020 AT&T Intellectual Property.
   6
   7    Licensed under the Apache License, Version 2.0 (the "License");
   8    you may not use this file except in compliance with the License.
   9    You may obtain a copy of the License at
  10
  11        http://www.apache.org/licenses/LICENSE-2.0
  12
  13    Unless required by applicable law or agreed to in writing, software
  14    distributed under the License is distributed on an "AS IS" BASIS,
  15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16    See the License for the specific language governing permissions and
  17    limitations under the License.
  18 ==================================================================================
  19 .fi
  20
  21
  22 .if false
  23         This imbed file contains the portion of the document that describes the
  24         alarm collector AIP provided by the framework.
  25 .fi
  26
  27
  28 .if pfm
  29     .** work round bug in cmd_ps.im
  30     .dv beg_table .ta $1
  31     .dv end_table .et
  32     .dv col .cl ^:
  33     .dv row .tr ^:
  34 .fi
  35
  36 .** ------ positioning -------------------------------------
  37
  38 &h1(Alarm Manager Interface)
  39 The C++ framework provides an API which allows the xAPP to easily construct and
  40 generate alarm messages.
  41 Alarm messages are a special class of RMR message, allocated in a similar fashion
  42 as an RMR message through the framework's &cw(Alloc_alarm()) function.
  43
  44 &space
  45 The API consists of the following function types:
  46
  47 &half_space
  48 &indent
  49 &beg_dlist( 1i &ditemtext: )
  50         &di(Raise) Cause the alarm to be assigned a severity and and sent via RMR
  51                         message to the alarm collector process.
  52
  53         &half_space
  54         &di(Clear) Cause a clear message to be sent to the alarm collector.
  55
  56         &half_space
  57         &di(Raise Again) Cause a clear followed by a raise message to be sent to
  58                         the alarm collector.
  59 &end_dlist
  60 &uindent
  61 &space
  62
  63 &h2(Allocating Alarms)
  64 The &cw(xapp::Alloc_alarm()) function provided by the framework is used to create
  65 an alarm object.
  66 Once the xAPP has an alarm object it can be used to send one, or more, alarm
  67 messages to the collector.
  68
  69 &space
  70 The allocation function has three prototypes which allow the xAPP to create
  71 an alarm with an initial set of information as is appropriate.
  72 The following are the prototypes for the allocate functions:
  73
  74 &half_space
  75 .im alloc_proto.im
  76
  77
  78 Each of the allocation functions returns a unique pointer to the alarm.
  79 In the simplest form (1) the alarm is initialised with an empty meid
  80 (managed element ID) string, and unset problem ID (-1).
  81 The second prototype allows the xAPP to supply the meid, and in the
  82 third form both the problem ID and the meid are used to initialise the
  83 alarm.
  84
  85 &h2(Raising An Alarm)
  86 Once an alarm has been allocated, its &cw(Raise()) function can be used
  87 to cause the alarm to be sent to the collector.
  88 The raise process allows the xAPP to perform the following modifications
  89 to the alarm before sending the message:
  90
  91 &half_space
  92 &indent
  93 &beg_list(&lic1)
  94         &li Set the alarm severity
  95         &half_space
  96         &li Set the problem ID value
  97         &half_space
  98         &li Set the alarm information string
  99         &half_space
 100         &li Set the additional information string
 101 &end_list
 102 &uindent
 103 &space
 104
 105 The following are the prototypes for the &cw(Raise()) functions of an alarm object:
 106 .....
 107
 108
 109
 110 In its simplest form (1) the &cw(Raise()) function will send the alarm without making any
 111 changes to the data.
 112 The final two forms allow the xAPP to supply additional data which is added to the
 113 alarm before sending the message.
 114
 115 Each of the raise functions returns &cw(true) on success and &cw(false) if the alarm
 116 message could not be sent.
 117
 118 &h3(Severity)
 119 The severity is one of the &cw(SEV_) constants listed below.
 120 These map to alarm collector strings and insulate the xAPP from any future alarm collector
 121 changes.
 122 The specific meaning of these severity types are defined by the alarm collector and thus
 123 no attempt is made to guess what their actual meaning is.
 124 These constants are available by including &cw(alarm.hpp.)
 125
 126 &half_space
 127 &indent
 128 &ex_start
 129     SEV_MAJOR
 130     SEV_MINOR
 131     SEV_WARN
 132     SEV_DEFAULT
 133 &ex_end
 134 &uindent
 135 &fig_cen(Severity constants available in alarm.hpp.)
 136
 137 &h3(The Problem ID)
 138 The problem ID is an integer which is assigned by the xAPP.
 139 The framework makes no attempt to verify that it has been se, nor does it attempt
 140 to validate the value.
 141 If the xAPP does not set the value, &cw(-1) is used.
 142
 143 &h3(Information Strings)
 144 The two information strings are also xAPP defined and provide the information that
 145 the xAPP deems necessary and related to the alarm.
 146 What the collector expects, and how these strings are used, is beyond the scope of
 147 the framework to describe or validate.
 148 If not supplied, empty strings are sent in the alarm message.
 149
 150 &h2(Clearing An Alarm)
 151 The &cw(Clear()) function of an alarm may be used to send a clear message.
 152 In a manner similar to the &cw(Raise()) functions, the &cw(Clear()) functions allow
 153 the existing alarm data to be sent without change, or for the xAPP to modify the
 154 data before the message is sent to the collector.
 155 The following are the prototype for these functions.
 156
 157
 158 &ex_start
 159    bool Clear( );
 160    bool Clear( int severity, int problem, std::string info );
 161    bool Clear( int severity, int problem, std::string info, std::string addional_info );
 162    bool Clear_all( );
 163
 164 &ex_end
 165 &fig_cen(Clear function prototypes. )
 166 &space
 167
 168 Each of the clear functions returns &cw(true) on success and &cw(false) if the alarm
 169 message could not be sent.
 170
 171
 172 &space
 173 The &cw(Clear_all()) function sends a special action code to the collector which is assumed
 174 to clear all alarms.
 175 However, it is unknown whether that implies &bold(all) alarms, or all alarms matching the
 176 &cw(problem_id,) or some other interpretation.
 177 Please consult the alarm collector documentation for these specifics.
 178
 179
 180 &h2(Adjusting Alarm Contents)
 181 It might be necessary for the xAPP to adjust the alarm contents outside of the scope of
 182 the &cw(Raise()) function, or to adjust data that cannot be manipulated by &cw(Raise().)
 183 The following are the (self explanatory) prototypes for the &ital(setter) functions
 184 which are available to the xAPP.
 185 &half_space
 186
 187 &ex_start
 188   void Set_additional( std::string new_info );
 189   void Set_appid( std::string new_id );
 190   void Set_info( std::string new_info );
 191   void Set_meid( std::string new_meid );
 192   void Set_problem( int new_id );
 193   void Set_severity( int new_sev );
 194 &ex_end
 195 &fig_cen(Alarm Setters)
 196 &space