Metalogic FireFox HotLine

This is the Metalogic FireFox HotLine Extension which monitors and presents events generated by the Metalogic Supervisor running on an MCP System.

This document contains information about installation, configuration and operation of FireFox HotLine. It is presented by default when there are no MCP Hosts configured, but it may be viewed at any time by clicking on the Help button.

In addition to this Help, most elements in FireFox HotLine, such as buttons and labels, display a brief explanation of their function when the mouse hovers over them.

Installation

The MCP System must have the CopyWrite TCP/IP Transport service installed. This service is released with Supervisor as an MCP Self Extracting Archive, which installs itself when it is executed.

The workstation must have FireFox 1.5 or later and the FireFox HotLine Extension installed. The FireFox HotLine Extension may be installed directly from the Metalogic Web site (www.metalogic.eu.com).

FireFox HotLine has been tested on Microsoft Windows 2000, SUSE Linux 10.0 and Apple Macintosh OSX 10.

This version of HotLine supports English. Please contact Metalogic at www.metalogic.eu.com should you be interested in providing translation assistance for other languages.

Configuration

A new MCP System is configured in FireFox HotLine using the Configurator. The Configurator is displayed by default if there are no hosts configured, however, it may be opened at any time using the Configurator button.

The Configure Host button can be used to create a new host or modify an existing host.

The Hosts panel shows the configured hosts and their attributes.

To create a new host configuration, enter a name in the Name field. The Name may be any character in the set {_-A-Za-z0-9} and it is case sensitive. After a name has been entered, the Configurator shows a form with fields for modifying the host's attributes.

These attributes may be configured using the Configurator.

Attribute	Description
Name	This Name is used to identify the host in the configuration file. When the cursor is moved from the Name field, by clicking on another attribute or using the Tab key, the Name is stored in the configuration file, and appears in the Hosts panel. Once it has been stored in the configuration file, use the Delete button to delete it.
Comment	This attribute may be used to store a comment along with the host configuration.
UserName	Enter the UserName which will be used to connect to the MCP System. The MCP System will have to be configured with a UserDataFile RU Entry which matches the UserName and IPAddress combination, otherwise access will be denied.
IPAddress	Enter the IPAddress of the MCP System, for example 192.168.1.1.
Connect	If the Connect button is pressed, a connection to the MCP System is immediately attempted using the values in the UserName and IPAddress fields. If the connection is successful, then the TT REC NAMES information will be loaded into the Configurator.
Recorder Names (Hide)	The Hide button toggles with the View button to collapse the Recorder Names, since sometimes there are a large number of Recorder Names, which can be distracting when configuring other attributes.
REC NAMES	The REC NAMES panel contains the Recorder Names which have been received from the MCP System, and also those which have been manually entered. A Recorder Name can be dragged into either the Record Filter, the Alert Filter or the NAME Bin. Further information is provided in the Operation description.
Up Down	The Up and Down buttons can be used to scroll the REC NAMES in either direction, one at a time. To move the REC NAMES more quickly, use the arrow at either end of the REC NAMES list.
Refresh	The Refresh button sends a request to the Recorder at the MCP host to send the current list of REC NAMES.
Manual Entry	The Manual Entry panel provides for the definition of REC NAMES other than those configured on the MCP System. For example, if a Supervisor RECORD command used a number instead of a mnemonic and there was no mnemonic defined for it, a manual entry might be created.
Record Filter	The Record Filter contains the REC NAMES which will be accepted from the MCP System and presented in HotLine. Whenever the Recorder Filter is changed, the MCP System is notified about the set of events which are to be sent to this HotLine. The set of events is known as the TypeMask and it is displayed in the Hosts panel entry for the MCP System. A REC NAME can be added to the Record Filter by dragging it from the REC NAMES panel.
Record Filter (All)	If the All checkbox is checked, then a TypeMask which selects all events is sent to the MCP System, and all events are recorded. This includes events which are destined for the Alert and Status panels.
hAlert Filter	The Alert Filter contains the REC NAMES which will be accepted from the MCP System and handled as an Alert. An Alert is displayed in the Alert panel. An alert can be modified (+<tag>:) and it can be cancelled (-<tag>:) by Supervisor. An Alert can either be plain text or an XML User Interface (XUL) document (<?xul><document>).A REC NAME can be added to the Alert Filter by dragging it from the REC NAMES panel. An Alert can be acknowledged by clicking on the entry.
Status Filter	The Status Filter contains the REC NAMES which will be accepted from the MCP System and handled as a Status message. A Status message can be modified (+<tag>:) and it can be cancelled (-<tag>:) by Supervisor. A Status message can either be plain text or an XML User Interface (XUL) document (<?xul><document>). A REC NAME can be added to the Status Filter by dragging it from the REC NAMES panel. The details of a Status message are shown when the entry is clicked.
NAME Bin	The NAME Bin is used to remove REC NAMES from the Recorder Names, Record Filter or Alert Filter. A REC NAME can be dragged from any of those panels and dropped onto the NAME Bin.
Colour, FontFamily and TextSize	These attributes are used to style messages and elements associated with this MCP System.
AutoConnect	If the AutoConnect checkbox is checked, an automatic connection to the MCP System is made when HotLine is started and periodically after that, if the initial connection attempt failed.
Keep Messages	This attribute specifies the number of hours to keep Recorder Messages. Every hour, any Recorder messages which are older than this value are deleted. The host context menu 'Discard Expired Records' can be used to perform an immediate check, for example, after changing the configuration value.

The Delete button can be used to Delete the configuration for an MCP System.

The Exit button is used to Exit from the Configurator. Whenever changes are made to an attribute, they are immediately stored in the configuration file.

Operation

An event on an MCP System is recorded by an OPAL ODTSequence using the RECORD Verb. The verb has the syntax RECORD[<name>](<text>). The <name> may be either an integer or a mnemonic for an integer defined using the TT REC NAMES command in Supervisor.

When FireFox HotLine connects to an MCP System it requests a list of all the NAMES that have been defined. The NAMES are stored in the configuration for the MCP System and they are presented in the Hosts panel.

Using the Configurator, specific NAMES can be dragged into the Record Filter , the Alert Filter and the Status Filter. The NAMES from these filters are combined into a set of events represented by a TypeMask. This TypeMask is sent to the MCP System so that Supervisor will only send the selected events, rather than any event which occurs on the MCP System.

The TypeMask for a Host can be queried on the MCP System using the TT REC WHO command.

When an event message is received from the MCP System, its ClassId (the integer value associated with the NAME) is extracted.

If the ClassId is listed in the Record Filter, the event is stored in the log file for the MCP System and it is displayed in the Recorder panel.

The log file for an MCP System is called <hostname>.log and it exists in the ../content directory for the FireFox HotLine Extension. It is stored in RDF/XML format. It is maintained by FireFox HotLine and should not be edited.

The Recorder panel can be rearranged as required, to hide columns, change their order and to specify the sort key.

To hide a column, click on the menu item at the far right of the headings row. This menu gives the list of columns which can be hidden or made visible by clicking on the checkbox.

The order of the columns can be changed by dragging a Column Heading into a new position.

The sort key can be changed by double clicking on a Column Heading, to have the table sorted by that column's content.

If the ClassId for a message received from the MCP System is listed in the Alert Filter, the event is stored in the Alert panel.

If the ClassId for a message received from the MCP System is listed in the Status Filter, the event is stored in the Status panel.

A message destined for the Alert or Status panel may be Tagged or Untagged. An Untagged message is added to the panel, but unlike a Tagged message, it cannot be modified or deleted by Supervisor at the MCP host.

A Tagged message is created using the RECORD[<name>](“<action><tag>:<text>”) command.

The <action> is + or – ;

A + indicates that this event is a message which is either new or should replace an existing message with the same <tag> in the panel.

A – indicates that any message with a matching <tag> should be cancelled and removed from the panel.

The <tag> is any text not including :. It is used to uniquely identify a message set.

The <text> is presented in either the Alert or Status panel as plain text.

Instead of plain text, the <text> may contain an XML User Language (XUL) document. If the <text> contains the sequence <abstract><?xul><document>, then <document> must contain syntactically correct XUL constructs. The text in <abstract> is displayed with a 'Details' button at the end of the line. When the Details button is pressed the XUL <document> is displayed.

For example, RECORD[META_STATUS](“0 Waiting Entries<?xul><label value='No Waiting Entries'/>”);

This provides the capability to program a user interface around detailed information gathered from the MCP System. See Generating Details below for more information.

An Alert message can be acknowledged by clicking on an entry in the Alert panel. If it is acknowledged, it is deleted from the Alert panel. If no acknowledgement has been made after 2 minutes, the style of the entry is changed into reverse highlight to attract attention.

The details of a Status message can be shown by clicking on an entry in the Status panel. If a Tagged Status message is not updated within 3 minutes, the style of the entry is changed into reverse highlight to attract attention.

Every hour, any Recorder messages which are older than the HoursToKeep attribute value are deleted.

Generating Details

The <document> which follows the <?xul> tag may contain any valid XUL. The <document> is wrapped inside a XUL <dialog> with the XUL namespace, and the stylesheet for the host, and some Javascript modules which support the display of the details.

The XHTML namespace “xmlns:html=http://www.w3.org/1999/xhtml” is also added to the <document>, so that HTML elements can be used to generate the details. The HTML tags must be preceded by the html:<tag> namespace.

For example, <html:p>This is some text</html:p>.

In addition, a simplified XUL box feature is provided to handle many of the common cases used by an OPAL to present the details associated with an event on the MCP.

The general XUL model for presentation consists of boxes of elements, arranged either horizontally (<hbox>) or vertically (vbox>). There are other types of boxes, such as <groupbox> and <box>. See the tutorial at www.xulplanet.com for a comprehensive tutorial and the XUL element reference.

HotLine introduces a 'script' attribute and a 'data' attribute which can be associated with a <box> element. The 'script' attribute specifies the standard HotLine script which will be used to build the details display in the <box> from the 'data'. The 'data' attribute specifies the name of the Javascript variable which contains a constant object or array of objects which specify the details.

For example,

RECORD[META_STATUS](“System Name<?xul><vbox id='1' script='System' data='Sys'/><script>var Sys={HostName:'” &
HOSTNAME & “'};</script>”);

System Name is the <abstract> displayed on the line in the HotLine Status panel, giving a brief summary of the event.

<?xul> tells HotLine that the rest of the information is a XUL <document>.

The <vbox> will vertically stack any elements that are added.

The standard HotLine script called 'System' will be used to add the data to the <vbox>.

The System script requires that the data be a constant object. A constant Object contains a sequence of <attribute name> : <attribute value> items separated by commas and enclosed in braces. In the example, var Sys={HostName:'LX100'};. An Object with two properties could be var Sys2={HostName:'LX100',NumberOfProcessors:2}; The syntax for the Object is defined by the JavaScript language.

The System script displays each property name and property value of the Object.

The standard HotLine script called Mix requires that the data be an array of constant Objects. For example, an array of two objects could be var Mix=[{MixNumber:1234,Name='A/B ON C'},{MixNumber:4567,Name='SYSTEM/ALGOL',Compiler:true,Suspended:null}];

The data definitions and any other JavaScript are enclosed in <script> </script> tags.

The standard HotLine scripts provide some simple rules which can be used to format the property values.

If the <attribute name> begins with an underscore, the <attribute Name> and the following colon are suppressed. The attribute value is styled with the host class.

if the <attribute value> is null, the colon and the <attribute value> are suppressed. The <attribute name> has the same font as the Host, but not the Host colour.

An underscore or hyphen in an <attribute name> is always replaced with a space.

If an XML parsing error occurs, the Details button displays a dialog box with the parser error message and the source text, highlighted to show the XUL sent from the host in contrast to the XUL in which it was wrapped. If the XUL contains any <![CDATA[...]]> tags, they are replaced by a [CDATA]...[/CDATA] sequence, to avoid any problem presenting the invalid XUL.

If a Details dialog box is displayed but there is only an OK button, then it is most likely because the JavaScript embedded in the XUL sent from the Host has syntax errors. This can be checked using either the the JavaScript Console or the better FireFox Extension Console2 available from https://addons.mozilla.org/firefox.

The RECORD statement in SUPERVISOR will only transfer a maximum of 16416 Bytes to HotLine. This is a limit imposed by the MCP MAX_DCMESSAGE_SIZE (2736 Words on MCP 5.1) on the size of a DCALGOL message which is used by SUPERVISOR to communicate with RECORDER.

Generating Charts

Simple Pie Charts, Bar Charts and Line Charts are available using the scripts called Pie, Bar and Line respectively. The general format for the data for these charts is a 2 dimensional array where each row consists of a label followed by a set of values. The x coordinate is the ordinal value of the row (1..n), and is associated with the label, and the remainder of the values give the y coordinates for each data set.

A Pie Chart uses the label for each segment, the size of which is calculated using the first value specified, any ther values being ignored.

A Bar or Line Chart uses the label for the x coordinate, and each subsequent value as a y coordinate in the corresponding dataset.

In the following example, the Bar chart has 3 elements, each with 3 datasets.

<box id='3' script='Bar' data='Points' flex='1'><script>var Points=[['*',4,6,8],['OPS',6,6,6],['DEV',8,7,6] ];var Options={drawYAxis:true,backgroundColor:Color.redColor(),shouldFill:false,SVG:true,Debug:false,axisLabelFontSize:20,axisLabelWidth:100 }; Points['Options']=Options;</script></box>

The example above also shows how formatting options can be associated with the data.

The charting is provided by PlotKit, http://www.liquidx.net/plotkit which is licensed under the BSD license, and which is dependent on MochiKit at http://www.mochikit.com/.

If the simple charts are not suitable, then direct access to PlotKit is provided using the Plot script. The data for the Plot script is an object which contains at least a DataSets, Options and Style property.

DataSets is an array of DataSet objects.

A DataSet object has a Name property, which is a string, and a Points property which is an array of (x,y) points.

Options is an object defined by PlotKit, and includes xTicks and yTicks for specifying label names at specific points.

Style is a string from the set {'pie','bar','line'}.

This is an example of using the Plot Script,

<box id='3' script='Plot' data='PlotData' flex='1'>
<script>var PlotData={DataSets:[{Name:'sqrt',Points:[[1,1],[2,1],[3,2]]},
{Name:'sqr',Points:[[1,1],[2,1],[3,16]]}],
Options:{},
Debug:true,
SVG:false,
Style:'bar'};</script></box>

The Debug and SVG properties are optional.

The Debug property when set causes an alert which contains diagnostic information.

If the SVG property is set, then an <svg> element is used for rendering the chart, otherwise a <canvas> element is used. Since HotLine is dependent on FireFox which supports both elements, <svg> should not be needed, however there may be some differences between the MAC, Linux and Windows.

References

Information about FireFox Extensions and XUL is available from many sources of which these are but a few.

www.xulplanet.com

This site contains a XUL Reference which describes in detail the XUL Elements and their attributes. It also has an excellent tutorial which describes how each of the XUL Elements can be used in a XUL application.

developer.mozilla.org/en/docs/Main_Page

This site contains references to documents about how to create FireFox Extensions and a vast array of other documentation.

www.mozilla.com

The home page for FireFox and Thunderbird and other Mozilla based software.

www.mozillazine.org

Mozilla News and links to other Mozilla sites.