[ Home | What's New | Contents | Overview | Contributors | Distribution | Examples | Documentation | Manual | Publications | Mailing List Archive | Problems ] This page was last updated by Axel Belinfante on 2004-10-25
TorX Test Tool Information
Prev   Next

mscviewer(1) - view a Message Sequence Chart

Table of Contents


mscviewer - view a Message Sequence Chart


mscviewer [ -r ] [ -m mcastid ] [ files ... ]
Bmsc [ -r ] [ -m mcastid ] [ files ... ]
Bmsc -exit


The mscviewer program reads MSC's from files, or from standard input if no files are given, and displays it to the user, step by step. Each MSC is displayed in a separate window. Instead of waiting for the whole MSC to be available, it will immediately start displaying what it has read, and update the display as soon as it has been able to read more of the MSC.

Bmsc is a shell-level command that causes a running mscviewer to load the named MSC files, or to display its standard input. The connection between Bmsc and a running mscviewer will not be closed until all files (or the complete standard input) of the Bmsc command have been processed by mscviewer, in order to allow the running mscviewer to report possible error messages (e.g. about syntax errors) about the files that it processes via the standard error of the Bmsc command that sent the files to it. If Bmsc cannot find a running mscviewer, it will start a new one. To display the new MSC file(s), mscviewer will reuse windows that contain a complete MSC and have the Reuse toggle activated. If more windows are needed, they are created.

In general, it is probably best to only use the Bmsc command, and let it start mscviewer when necessary. However, one should be aware of the fact that when a Bmsc command is given when no mscviewer is currently running, the Bmsc will ``become'' a mscviewer command, which is ``long-running'' and will only exit when all its windows are closed or the Quit button is pressed (or a Bmsc -exit command is given). In contrast, a Bmsc command given when a mscviewer is already running will exit as soon as its files or standard input are processed by the running mscviewer.

The -r command line option of both mscviewer and Bmsc will activate the Reuse toggle button for the windows that will contain the MSC's given on the same command line or via standard input.

When Bmsc is started with only command line option -m mcastid, or when environment variable TORXMCASTID was set, the MSC viewer tries to connect to the address given in the mcastid and to use the resulting connection as a remote control connection to synchronise displaying a particular step in the MSC viewer. Whenever the user does something in the user interface that selects a different step in the MSC, its step number is written to the remote control connection. Whenever a step number can be read from the remote control connection, the corresponding step is displayed in the MSC viewer.

When Bmsc is started with only one command line parameter: -exit, the running mscviewer will clean up and exit.

The MSC file should be in event oriented textual representation. mscviewer indicates both ``normal'' end-of-msc and ``abnormal'' end-of-input without having seen end-of-msc. The ``normal'' end-of-msc is visualized by drawing horizontal bars at the end of every instance in the MSC. The ``abnormal'' end-of-input is visualized by drawing at the end of each instance of the MSC a stippled/dotted contininuation of the instance, and ending that with stippled/dotted horizontal bars.


At the bottom of the MSC viewer there are several buttons. The Save as button opens a dialog box that allows saving of the MSC in postscript form (by choosing or entering a file name ending in a .ps suffix) and in textual form (by choosing or entering any other file name).
The Font down and up arrow buttons decrement resp. increment the font size. When a font size change makes this necessary, labels are moved to the right to keep them visible.
The Highlight toggle button enables and disables highlighting (default: enabled). Independent of this button, the step number of the MSC item under the mouse is shown in the Step field. Step numbers start at 1, and are assigened when the second part (target) of a message is seen. Step number 0 is special: it used to refer to the instance headers. When highlighting is enabled, the item under the mouse is highlighted by drawing a box arround it and making the arrow slightly bigger. Also, when a new item is added to the MSC, it is highlighed. To highlight the item for a known step, enter the step number in the Step entry field, and hit the return key. The MSC window automatically scrolls to make the highlighted item visible. If a step number is present in the Step field, the down and up arrow buttons can be used to decrement resp. increment the step number, to move the highlight up resp. down in the MSC.
The Reuse toggle button indicates that its window may be reused for a new MSC, when end-of-input has been seen for the MSC currently displayed in it. (default value: unset, except when overridden by a -r command line option of mscviewer or Bmsc).
The Close button closes the MSC window, and, if this was the last remaining window, exits the progam.
The Quit button closes all MSC windows and exits the progam.

See Also

torx-intro(1), xtorx-showmsc(1), log2msc(1), torx-logclient(1), jararacy(1), tmcs(1),
Ekkart Rudolph, Peter Graubmann and Jens Grabowski: Tutorial on Message Sequence Charts, Computer Networks and ISDN Systems, Volume 28, Issue 12, June 1996, Pages 1629-1641


file to communicate tcp port number on which mscviewer listens for Bmsc to connect
the file containing a list of process identifiers (one per line) of mscviewer and its subprocesses


The Bmsc command was named (and designed) after the B shell-level command of the sam(1) editor.


The current implementation expects each ``statement'' of the MSC in event oriented textual representation to be on a separate line. The output of log2msc(1) complies to this limitation.

The ``endinstance'' statements in the MSC are ignored; the ``endsmsc'' statement is used to close all instances.

Only a limited subset of the MSC language is implemented. Valid input is assumed; only very limited checking is done.

The syntax recognized for the MSC language is inferred from the tutorial mentioned above, but not checked with a more formal syntax description. In particular, mscviewer expects double quotes (") to be present for MSC items containing whitespace -- whether this is consistent with the MSC standard has not been checked.

When mscviewer is started, it checks if other instances of it are running. If so, they are killed. This was added to clean up run-away processes.

When mscviewer is given multiple files that are to be processed simultaneously, it has a tendency to process the files one after the other, in reverse order, instead of procesing them in parallel, step by step.

It is counter-intuitive that the Step up arrow button moves the highlight down (because the up button increments the step number, and the steps are numbered increasing from top to bottom).

Table of Contents

Prev Table of Contents Next
Appendix D: TorX Manual Pages: mkprimer(1) - generate a primer for torx Valid HTML 4.01! Appendix D: TorX Manual Pages: partitioner(1) - weight-based test primitive selection for primer