The following chapter describes parts of the equipment and alarm models from the ANx project, a telecom application providing households with broadband access. It gives a practical example of what has so far been covered in the abstract description of the functional and informational models of the MRI.

The Equipment Model

The equipment model described is hierarchically organized. On the top level, there is a system node. It logically groups together equipment, either geographically, functionally, or both. The subrack is the hardware in which the boards are inserted. Every subrack is associated to a system node, so both values have to be included in the record to yield a unique key.

-record(mr_sn,{sn = key,                   % int(), Node identifier
                             mgt}).                        % Management Data

 -record(mr_sr,{ sn = key,                   % int(), Logical subrack grouping
                              sr = key,                    % int(), Subrack Id
                              hw_id,                       % str(), Hardware Id
                              type,                           % adsl, maccg, other
                              alarm_status,          % [], Subrack Alarm Status. See MRI
                              mgt}).                        % Management Data

The keys of these record are the sn and sr fields. They are always given the default value key when the record is defined, and always have to be set to an actual value whenever a get_info call is executed. A get_info call to retrieve the MRI record containing the information for the system node 1 and the subrack 10 would be

mr:get_info(#mr_sr{sn = 1, sr = 10}).

The return value of this call would be either {error, Reason} or {ok, Record}. The error reason is defined in the functional model to be the atom type or instance. Record is an instance of the #mr_sr record, where all the fields are set.

Slots are positions in the subrack where the boards can be inserted. Slots are never created or deleted individually, as they are directly associated with the subrack. When a subrack is created, all the entries in the slots table are also created. The same applies to deleting a subrack. All instances of the slots in that subrack will also be deleted.

-record(mr_slot, { sn = key,        %int()
                                 sr = key,         %int()
                                 spos = key,     int(), Denotes the slot position 
                                 type,                 %virtual | real
                                 configured,     % unmanaged | unconfig_empty | config_empty | config_board          
                                 alarm_status,% [removed | unconfig_inserted | mismatch | unrecognized]
                                 mgt}).

The board records denote the managed entities that are inserted in the slots. There is a one to one relation between a board and a slot, so the keys are the same. Many different types of boards can be inserted in the slots, and parameters from these different boards may differ. The board record contains all the values that all boards can have in common. Other values are placed in record extensions, resulting in records that share the same keys as their abstract counterpart.

-record(mr_board, { sn = key,        % int()
                                     sr = key,         % int()
                                     spos = key,    % int()
                                     type,                % et | power | qau | ce | ucm | hfc_nt | adsl_nt
                                     hw_id,             % string()
                                     sw_id,             %{Core, Appl} string()
                                     status,             %{Oper, Admin} up | down
                                     led_status,      % red_on | red_off | none
                                     alarm_status, % see alarm list in MRI document
                                     mgt}).

-record(mr_hfc_slot, { sn = key,    % int()
                                        sr = key,      % int()
                                        spos = key, % int()
                                        coax,             %Logical Unit ID
                                        qam,             %{Spos, Index} Upstream Port
                                        ucm,              % {Spos, Index} Downstream Port
                                        mgt}). 

The mr_hfc_slot record will only exist if a slot is configured to contain a board of type hfc_nt. It will contain a logical identifier for the coaxial cable it is connected to, together with the ports that handle the upstream and downstream traffic when the board is inserted. This information is specific only to slots that will contain an hfc Network terminal.

The hierarchy in the ANx goes further to include interfaces, which denote points used for inter - board communication. These interfaces are in turn divided up into entities such as points and timeslots. Just like the records in this example, interfaces and other hierarchically lower managed entities have the keys of the entity on a higher level, with an additional key.

The call to retrieve all the keys takes only one argument, namely an empty MRI record. Only the record type is checked.

mr:get_keys(#mr_sr{}).

The return value is {error, type} should the record not be supported. The tuple {ok, Keys} is otherwise returned. Keys denotes either an empty list, should no subracks exist, or a list of lists, where every sub list contains the system node and the subrack identifier, in the same order as they were defined in the MRI record. They keys are lexicographically ordered, and could for example be a list resembling [[1,1], [1,2], [1,10], [2,5], [2,6]].

The following action signs on [26] a network terminal, (NT ) [27] located in the virtual slot found in subrack 1 at position 1, belonging to the logical grouping represented by system node 1. Rate is the bandwidth assigned to the NT.

mr:action(sign_on, #mr_adsl_slot{sn = 1, sr = 1, spos = 1, rate = {Up, Down}}).

The return value is either {error, Reason}, where Reason is either instance, should such a slot not exist, {invalid, rate}, should the bandwidth values entered by the operator be wrong, or bandwidth, should the network not be able to reserve enough bandwidth for the NT. If the operation succeeds, {ok, Rec#mr_adsl_slot} is returned. All the fields in the record are set.

The fact that this action returns a record where the values of the field refer to the valid parameters after the success of the action might lead to the thought that all actions are synchronous. This is not necessarily the case, and if the call is synchronous or not is decided in the application to which the action is forwarded to.

An example of an asynchronous call requiring an extra state parameter is the signing on of the adsl slot. Such an operation can take a long time considering that the board has to be located in the network. The signing on of a slot reserves the bandwidth and initiates the search for the board. It could take days before the board is actually connected to the network so the response time would thus not be acceptable for the operator if the calling process is to hang until the board is located. Some sort of feedback is thus given as soon as the action has been initiated. The additional state signing_on is used as a complement to the signed_on and signed_off states in order to return an accurate mr_adsl_slot record through the MRI. As soon as the signing on succeeds, an event is generated.

The event and alarm model.

Here follows the MRI alarm model used for the ANx. The alarm model is the smallest of the models, and easiest to understand as it contains no project specific data other than the network element specific alarms specified in a configuration file. This makes the alarm information model product independent, allowing it (and the code written to implement it) to be reused in different products. All actions in the alarm model are also included.

The alarm model is responsible in reporting events and alarms. Events and alarms are logged in the mr_event_log table, and active alarms are stored in the mr_alarm table. These records are identical, in that they contain an index to uniquely identify the alarm or event, and an mr_notification record, which stores all the necessary data.
Treatments on the various events and alarms are stored in the mr_treatment table. There exists one entry in the table for every type of alarm or event, and determines if the alarm is to be logged or sent.

The mr_notification record has no keys. It is just a record extension collecting data related to a specific alarm or event, and stored in one of the fields of the mr_event_log or mr_alarm records. This is possible because alarms and events consist of the same information.

-record(mr_notification,{ name,        % atom(), alarm or other          event
                                             originator, % MRI record,
                                             severity,    % minor | major | critical | warning | undefined 
                                             time,          % {{Y, M, D},{H, M, S},{‘-‘| ‘+’, H, M}}
                                             info,            % string(), < 255 chars
                                             mgt}).

-record(mr_treatment,{ name = key,      %atom(), alarm or event          see MRI 
                                          type,                     % alarm | state_change | other_event
                                          logging,               % enabled | disabled
                                          sending,              % enabled | disabled
                                          last_time_sent,  % {{Y, M, D},{H, M, S},{‘-‘| ‘+’,          H, M}}
                                          severity,                % minor | major | critical | warning | undefined
                                          category,              % undefined | communication | qos | procesing | equipment | environmental
                                          mgt}).

-record(mr_event_log,{ index = key,  %integer()
                                           record,          % #mr_notification record
                                          mgt}).

-record(mr_alarm,{ index = key, %integer()
                                    record,
                                    mgt}).

The configuration file contains all of the data that is inserted in the event treatment table upon start up. This file will change with the information model, and is proprietary to the CP. The name, type, severity, category and originator are however defined in an alarm appendix of the MRI document. All values are static except for the severity, which can be changed by the operator. The value described in the MRI denotes just the default value. An alarm table describing all possible events and alarms follows.

There are four actions that can be applied on the MRI alarm model records. set_event_treatment sets the treatment for one event. Fields considered are logging, sending and severity. If any of them has the value undefined, it is ignored. All other values are set. An instance error is returned if the event or alarm that we want to change is not represented in the record.

mr:action(set_event_treatment, Rec#mr_event_treatment) -> {ok, NewRec#mr_event_treatment} | {error, instance}

Set and get log properties is applied to the event log table. There is however no record denoting the event log, so the managed entity field is kept empty, and the properties are instead passed in the field used for the extra arguments not included in the managed entity record. It is noted in the next chapter that a log properties record should in fact have been defined. Setting the log properties includes changing the administrative status to enabled or disabled [28]. Size regulates the number of records stored in the table according to the first in, first out principle. This action can be used to clear the log by setting its value to zero, and then back to its original one.

mr:action(set_log_properties, {}, Properties) -> {ok, [{admin_status, up | down}, {size, Size}]}

mr:action(get_log_properties, {}) -> {ok, [{admin_status, up | down}, {size, Size}]}

mr:action(get_no_of_alarms, {}) -> {ok, NoOfCurrentAlarms}

[26] Locating and activating.

[27] The endpoint of a broadband network into which phones, TVs, Ethernet links and other devices can be connected to.

[28] Log or don’t log all mr_event_treatment records whose log treatment is set to enabled | disabled.