NRAO Home  >  Green Bank  |  Wiki Topic:    GB > Main > TWikiUsers > MarkWhitehead > MessageSyntax

Users | Groups | Offices | Changes | Index | Contents | Notify | Search | Jump to Topic:

<summary>
 for generating and passing messages across an ethernet
</summary>

<etymology>
 Message, about as plain as it gets.
</etymology>

<synopsis>
 This library acts as the programmers interface for system messages.
 It allows for two types and six levels of messages.

 <p> Message types may describe a transient event or a state.
 Messages which describe a state are reported twice: when
 the state becomes active and when it becomes inactive, e.g.,
 <pre>
  Instead of:
   if (volt > 5.0)
    printf("Voltage is too high (%f)\n",volt);
  Use:
   mess.check(volt > 5.0,
          "Voltage is too high (%f)\n",volt);
 </pre>
 Messages which describe transient events are reported each time their
 test passes, e.g.,
 <pre>
  Instead of:
   if (spike_detected())
    printf("Spike detected on power line\n");
  Use:
   mess.check(spike_detected(),
          "Spike detected on power line");
 </pre>

 <p> The levels of messages are listed here in order of increasing severity.
 <dl>
 <dt> Info -
 <dd> Merely provides parenthetical text for indicating
 expected events or for debugging purposes.  In many cases these should
 be viewed as temporary mechanisms until appropriate
 means are developed for displaying system status or confidence
 in the system is built up over time.
 A small set of these will be retained for the final system to provide
 context for the message log.
 <p>
 Examples:
 <ul>
 <li>
 The reporting of the generation of a data record for a backend.
 <li>
 A scan is in progress.
 </ul>
 <dt> Notice -
 <dd> This level reports any unexpected events that are not reported
 at the more severe levels.
 This level includes illegal actions by users.
 <p>
 Examples:
 <ul>
 <li>
 The user enters an illegal value for a control parameter.
 <li>
 The one pps in the timing center has drifted past a threshold value.  It
 is expected this event will occur from time to time even when the device
 is in good working order.
 </ul>
 <dt> Warning -
 <dd> This level provides a description of an unexpected or
 possible problem-causing event which requires more careful monitoring
 or investigation by the operator.
 <p>
 Examples:
 <ul>
 <li>
 An attenna surface panel's temperature has an unreasonable reading.
 <li>
 The cryo temperatures have climbed beyond a specified threshold.
 <li>
 The antenna is pointing within a specified distance from the sun.
 </ul>
 <dt> Error -
 <dd> An event has occurred which requires
 a specific action by the operator, such as notifying the contact engineer.
 <p>
 Examples:
 <ul>
 <li>
 An off-line receiver is warming up.
 <li>
 A cryo compressor has failed and a spare should be connected.
 <li>
 The A Rack of the Spectral Processor fails to start a scan on time.
 </ul>
 <dt> Fault -
 <dd>  This level describes events which will cause the system to -- at least
 in part -- generate bad observational data or prevents the completion
 of actions.
 <p>
 Examples:
 <ul>
 <li>
 The cryo temperatures of the active receiver
 have climbed to the point there is little hope of
 detecting a signal.
 <li>
 The tracking LO has gotten out of sync with the sig/ref signal.
 <li>
 The antenna is more than N beamwidths off the commanded track.
 <li>
 A failure of a digital interface.
 <li>
 The A Rack of the Spectral Processor fails to start.
 <li>
 An LO repeatedly fails to stay in lock.
 </ul>
 <dt> Fatal -
 <dd> Description of an unexpected and problem-causing event which
 the system took some action as a result of, or requires some
 action by telescope personnel, i.e., equipment or personnel are
 in danger.
 An event from which the software
 cannot recover and must be restarted.
 <p>
 Examples:
 <ul>
 <li>
 The commanded track has driven the telescope into a limit.
 <li>
 The active surface is shutting down because an emergency stop was initiated.
 <li>
 The temperature in a rack of equipment is high enough that the equipment
 needs to be powered down.
 <li>
 The wind speed is high enough to cause the automatic stowing of the antenna.
 <li>
 Some sub-task of a system has crashed.
 <li>
 An "impossible" software condition occurs, a la assertion.
 </ul>
 </dl>
 <pre>
  Color Coding scheme for Messages

 Fatal:  red
 Fault:  orange-red or pink
 Error:  Orange
 Warning: yellow or yellow-green
 Notice:  blue
 Info:  white or black
 Clear:  white or black
 </pre>


 In addition to the messages listed above an additional type, System Status
 messages, such as SystemUp or SystemDown are defined. These are for
 detection of system crashes or reboots.<p>

 Each node is uniquely identified by a MessageId tag.
 MessageId's consist of a unique id and an IP address.
 </synopsis>

 <example>
 Message declaration:
 <srcblock>
 Message startTimeErr(
                 MSG_ID(SpectralProcessorMsg::startTimer),
                 Msg::Error,
                 "Spectral Processor Rack start sequence ",
                 1);
 </srcblock>
 Message use:
 <srcblock>
  startTimeErr.check(
   !pulsarMode && (start + 999) < now,
   "%s missed start time",
   rack->getDescrip());
 </srcblock>
 </example>

 <motivation>
 This class was created to allow a single mechanism to pass messages to
 telescope personnel.
 </motivation>

 <todo>
 <li> Allow <b>Samplers</b> to be attached to message nodes.
 </todo>