IBM
Contents Index Previous Next



Graphical User Interface


This section describes the appearance and functionality of the graphical user interface to the simulator monitor (SimUI). Some user interface descriptions general to all tools can be found in User Interface and Basic Operations. These general descriptions are not repeated in this chapter.

Starting the SimUI

A new SimUI is started by selecting SDL > Simulator UI from the Tools menu in the Organizer. When the SimUI is started, a number of definition files are read, controlling the contents of the main window and some status windows. See Definition Files for more information.

No simulator is started automatically by the SimUI in this way. The user must start a simulator by selecting Open from the File menu, as stated in the text area of the main window, or by using the Open quick button.

A simple way to generate a simulator, start the SimUI and open the simulator is to click the Simulate quick button in the Organizer.

When a simulator is started, a file selection dialog may be opened if the SDL system contains external synonyms. For more information, see Supplying Values of External Synonyms.

The Main Window

The main window provides a text area (which displays output from the monitor system), an input line (used for entering and displaying textual command line input to the monitor system and the SimUI) and a button area with button modules (with buttons for execution of monitor and SimUI commands).

Figure 460 : The main window

The Text Area

The text area displays all text output from the monitor system, including user prompts, error messages and command results.

Commands cannot be entered in this area, but a command given on the input line or through the use of the command buttons is echoed after the displayed prompt:

Command : 

The Input Line

The input line is used for entering and editing commands from the keyboard. For information on available monitor commands, see Monitor Commands. There are also special SimUI commands that are not sent on to the simulator monitor, see SimUI Commands.

The 100 latest commands entered on the input line are saved in a history list. The history list can be traversed by using the <Up> and <Down> keys on the input line.

When <Return> is pressed anywhere on the input line, the complete string is saved in the history list and is moved to the text area. The command is then executed.

The input line also has an associated popup menu with the choices Undo, Command, Save, Go to Source and Add to watchwindow:

Parameter Dialogs

If a command entered on the input line requires additional user input (i.e. parameter values), the information will automatically be asked for in a dialog:

Each parameter dialog has an OK button for confirming the value and a Cancel button for cancelling the command altogether. Some parameters have a default value that does not have to be specified. In this case, an empty value or `-' is accepted for the default value.

Enumeration Type Parameter Dialogs

Additional functionality is available in the dialog for enumeration type parameters:

Figure 461 : A typical selection dialog

In this dialog, the value can also be entered or edited on the text input line below the list in the dialog. The Sort button sorts all values in alphabetical order.

Name completion with the space character is provided. When you press <Space> after an initial string, the first value starting with the string will be selected (if any). Another <Space> will select the next value, etc. When there are no more matches, a space character will be added after the string you initially entered.

A slightly different name completion is provided with the `?' character. When you press `?' after an initial string, the first value containing the string will be selected (if any). Another `?' will select the next value. When there are no more matches, a `?' character will be added after the string you initially entered.

For those commands that take an optional variable component, the component must be entered on the text input line after the selected variable name, since it will not be asked for in a dialog. If a `?' is entered instead of a variable component, an additional dialog is opened in which the component can be selected. See the discussion of `?' in Examine-Variable.

Signal Parameter Dialogs

If a command takes an output signal as parameter, and that signal have parameters, the signal parameters are asked for in a separate dialog. In this dialog, all parameters are listed with their default ("null") values, and they can all be edited in the same dialog. For more information, see Selecting Signal Parameters.

Quick Buttons

The simulator has the following quick buttons:

The Button Area

The button area is used for entering monitor or SimUI commands by clicking the left mouse button on a command button. Each button corresponds to a specific command. The buttons are divided into groups, roughly corresponding to the different types of commands listed in Simulating a System. Each group is shown as a module in the button area. Any number of button modules may reside in the button area. If the modules do not fit in the button area, a vertical scroll bar is added.

The definition of the buttons and button groups are stored in a button definition file (see Definition Files). New buttons can be added and existing ones deleted or redefined by using the Group menu in a button module.

To examine a button's definition without executing the command, the left mouse button is pressed on the button and the mouse pointer is moved outside the button. The command definition then appears in the status bar, but the command is not executed.

If a button's definition contains parameters, the parameter values are prompted for in dialog boxes before the command is executed, in the same way as described for commands entered from the input line. See Parameter Dialogs.

When no more parameter values are requested, the string shown on the input line saved in the history list and is moved to the text area. The command is then executed.

A Button Module

A button module looks like this:

Figure 462 : A button module

Each module consists of a title bar and a number of command buttons arranged in rows and columns. The title bar displays:

The Group button contains the following menu items:

Add

This menu choice adds a new button to the button module. A dialog prompts for the button label and the command to be executed when the button is pressed. The new button is added to the end of the module. Several buttons may be added with the dialog by using the Apply button instead of the OK button.

For the syntax of a button definition, see the subsection Button and Menu Definitions.

Note:

On UNIX, if several buttons have the same button label, it is always the first button found that will be deleted or modified, independently of the selection.

Edit

This menu choice edits the label and definition of a button. The button to edit is selected in a dialog. When a button has been selected, the label and definition can be edited using a dialog.

Note:

On UNIX, if several buttons have the same button label, it is always the first button found that will be edited, independently of the selection.

Delete

This menu choice deletes one or more buttons from the button module. The buttons to be deleted are selected in a dialog.

Note:

On UNIX, if several buttons have the same button label, it is always the first button found that will be deleted, independently of the selection.

Rename Group

This menu choice edits the name of the current button module in a dialog.

Delete Group

This menu choice deletes the current module from the button area. A dialog asks for confirmation.

The Default Button Modules

The following tables list the default buttons in the button modules and the corresponding monitor command. See Monitor Commands for more information.

Note:

The buttons in the button modules are specified in the button definition file. If the default button file is not used, the button modules may be different than described here. See Button and Menu Definitions for more information.

The Execute Module

Button Monitor command

Symbol

Step-Symbol

Transition

Next-Transition

Go

Go

Until Timer

Proceed-To-Timer

Break

Pressing <Return>

The Send Signal Module

Button Monitor command

Send To

Output-To

Send Via

Output-Via

Send None

Output-None

The Examine Module

Button Monitor command

Process List

List-Process -

Variable

Examine-Variable (

Var In Scope

Examine-Variable

The Trace Module

Button Monitor command

MSC

Start-Interactive-MSC-Log 1

SDL

Set-GR-Trace 1

TEXT

Set-Trace 6

The Menu Bar

This section describes the menu bar of the SimUI's main window and all the available menu choices. However, the Help menu is described in Help Menu. Simulator commands are described in Monitor Commands.

The menu bar contains the following menus:

File Menu

The File menu contains the following menu choices:

Restart

Restart the currently opened simulator. After user confirmation, the currently running simulator is stopped, the Watch window is updated, and the text area is cleared from previously executed commands.

The command is dimmed if no simulator has been opened.

View Menu

The View menu contains the following menu choices:

Watch Window

Opens the Watch window displaying variable values in the simulation. If this window is already opened, the menu item is dimmed. See Watch Window for more information about this window.

Command Window

Opens the Command window in which arbitrary monitor commands will be executed. If this window is already opened, the menu item is dimmed. See Command Window for more information about this window.

Open All

Opens the Watch and Command windows.

Close All

Closes the Watch and Command windows.

Clear Text Area

Clears the text area in the main window without affecting the simulation.

Buttons Menu

The Buttons menu contains the following menu choices:

For more information on the SimUI's button definition file mentioned in the menu commands below, see Definition Files.

Load

Reads in a new button definition file that overrides the current button definitions. All buttons and modules currently in the button area are deleted and replaced by the buttons and modules defined in the new file. A File Selection Dialog is opened for specifying the file to load.

Append

Appends the contents of a new button definition file into the current button definitions. Buttons with new labels are added to the button area, while buttons with already existing labels in the same module will be duplicated (possibly with different definitions). A File Selection Dialog is opened for specifying the file to append.

Save

Saves the current button and module definitions in the button definition file under its current file name.

Save As

Saves the current button and module definitions in a new button definition file. A File Selection Dialog is opened for specifying the new file name.

Expand Groups

Expands all modules in the button area.

Collapse Groups

Collapses all modules in the button area.

Add Group

Adds one or more new button module after the last module in the button area. A dialog box is opened for specifying the name of the new module. Several modules may be added with the dialog by using the Apply button instead of the OK button.

Log Menu

The Log menu manages three different log variants:

The difference between the input history and the command history is that the SimUI processes commands before forwarding them to the simulator. The input history contains the raw user input, while the command history contains pure simulator commands. For instance:

The Log menu contains the following menu choices:

Clear Input History

SimUI command: clear-input-history

Normally, the input history is cleared when the simulator is restarted. You use this menu choice to clear the input history without restarting the simulator.

Save Input History

SimUI command: save-input-history

A file selection dialog appears, where you specify the file to save the input history in. The default file extension for input history files, i.e. input scripts, is *.cui.

Clear Command History

SimUI command: clear-command-history

Normally, the command history is cleared when the simulator is restarted. You use this menu choice to clear the command history without restarting the simulator.

Save Command History

SimUI command: save-command-history

A File Selection Dialog appears, where you specify the file to save the command history in. The default file extension for command history files, i.e. command scripts, is *.com.

Start/Stop Complete Log

Start Complete Log starts the logging of complete monitor interaction, i.e. the complete contents of the text area will be logged to a file. A file selection dialog is opened for specifying the log file. If an already existing log file is selected, the user is asked whether to overwrite this file or to append the log to it.

Stop Complete Log stops the complete logging to the file. The appropriate menu choice is displayed depending upon the current state of the log.

Log Status

Displays the status of the command and complete logs in a dialog box. If a log is active, the name of the log file is shown.

Additional Simulator Menus

In addition to the standard SimUI menus, a few special simulator menus are included in the menu bar. The menu choices in these menus simply execute a monitor command, i.e. they are functionally equivalent to buttons in the button modules. If the monitor command requires parameters, they are prompted for using dialogs in the same way as the command buttons.

The following tables list the default menu choices and the corresponding monitor command. See Monitor Commands for more information.

Note:

The additional menus in the SimUI are specified in the button definition file. If the default button file is not used, the button modules may be different than described here. See Button and Menu Definitions for more information.

General Menu

Menu choice Monitor command

Command

? (Interactive Context Sensitive Help)

Start SDL Env

Start-SDL-Env

Version

Show-Versions

News

News

Execute Menu

Menu choice Monitor command

Go

Go

Over Symbol

Next-Symbol

Into Stmt

Step-Statement

Over Stmt

Next-Statement

Finish

Finish

Until Time

Proceed-Until

Until Trace

Next-Visible-Transition

Until Timer

Proceed-To-Timer

Input Script

execute-input-script

Command Script

Include-File

Stop Sim

Exit

Examine Menu

Menu choice Monitor command

Ready Q

List-Ready-Queue

Now

Now

Process List

List-Process

Input Port

List-Input-Port

Signal

Examine-Signal-Instance

Timer List

List-Timer

Variable

Examine-Variable (

Call Stack

Stack

Set Scope

Set-Scope

Change Menu

Menu choice Monitor command

Ready Q

Rearrange-Ready-Queue

State

Nextstate

Create Process

Create

Stop Process

Stop

Input Port

Rearrange-Input-Port

Del Signal

Remove-Signal-Instance

Set Timer

Set-Timer

Reset Timer

Reset-Timer

Variable

Assign-Value

Synonym File

set-synonym-file <file name>

Show Menu

Menu choice Monitor command

Next Symbol

Show-Next-Symbol

Prev Symbol

Show-Previous-Symbol

C Line

Show-C-Line-Number

Coverage

Show-Coverage-Viewer

Trace Menu

Menu choice Monitor command

Text Level : Set

Set-Trace

- : Show

List-Trace-Values

SDL Level : Set

Set-GR-Trace

- : Show

List-GR-Trace-Values

MSC Level : Set

Set-MSC-Trace

- : Show

List-MSC-Trace-Values

MSC Trace : Start

Start-Interactive-MSC-Log

- : Start Batch

Start-Batch-MSC-Log

- : Stop

Stop-MSC-Log

Breakpoint Menu

Menu choice Monitor command

Transition

Breakpoint-Transition

Output

Breakpoint-Output

Variable

Breakpoint-Variable

Symbol

Breakpoint-At

Connect sdle

Connect-To-Editor

Remove

Remove-All-Breakpoints

Show

List-Breakpoints

Command Window

The Command window is an optionally visible window used for displaying the results of executed commands. The Command window is opened from the SimUI's View menu.

Figure 463 : The Command window

The Command window is updated automatically whenever the monitor becomes active and after each monitor command. See Activating the Monitor for information on when the monitor becomes active. The window can also be updated manually with a menu command.

Any number of commands can be defined to be executed in the Command window. Each command is executed in a scrollable module in the window.

New commands can be added to the window and existing commands can be changed. The commands to execute are by default List-Process and List-Ready-Queue. The set of commands to execute are stored in a command definition file (see Definition Files). The default command definition file can be changed with the Preference Manager.

Command Modules

A command module looks like this:

Figure 464 : A command module

Each module consists of a title bar and a scrollable text area for the command output. The title bar displays:

The Command button contains the following menu items:

Edit

Opens a dialog for editing the command executed.

Delete

Deletes the command and command module from the Command window.

Size

Sets the size of the text area. A dialog is opened where the number of text rows can be set using a slider.

File Menu

The File menu contains the following menu choices:

Load

Reads in a new command definition file that overrides the current command definitions. All commands currently in the Command window are deleted and replaced by the commands defined in the new file. A File Selection Dialog is opened for specifying the file to load.

Append

Appends the contents of a new command definition file into the current command definitions. New commands are added to the command window, but already existing commands are not affected. A File Selection Dialog is opened for specifying the file to append.

Note:

Command names in a command definition file are case sensitive. If a command in an appended file already exists in the Command window, but with different case, the command will be duplicated.

Command Menu

The Command menu contains the following menu choices:

Command

Adds a new command to the Command window. A dialog box prompts for the new command. The new command module is added to the bottom of the window. For the syntax of a command definition, see Command Definitions.

Update All

Updates all command modules by executing the defined commands.

Watch Window

The Watch window is an optionally visible window used for displaying values of variables defined in the currently running simulation. The Watch window is opened from the SimUI's View menu.

Figure 465 : The Watch window

The Watch window is updated automatically after each monitor command. The window can also be updated manually with a menu command.

The variables to display are selected with a menu command. The set of selected variables are stored in a variable definition file (see Definition Files).

File Menu

The File menu contains the following menu choices:

Load

Reads in a new variable definition file that overrides the current variable definitions. All variables currently in the Watch window are deleted and replaced by the variables defined in the new file. A File Selection Dialog is opened for specifying the file to load.

Append

Appends new variable definitions to the current variable definitions file. The variables in the file are added to the Watch window. A File Selection Dialog is opened for specifying the file to merge. Duplicate variable definitions are permissible.

Watch Menu

The Watch menu contains the following menu choices:

Update All

Updates the Watch window by showing the current value of all displayed variables.

Add

Adds one or more variables to the Watch window. A dialog is opened for specifying the variable to be added. For the syntax of a variable definition, see Variable Definitions. Several modules may be added with the dialog by using the Apply button instead of the OK button.

Edit

Edits a variable specification in the Watch window. The variable whose specification is to be changed is selected in a dialog. When a variable has been selected, the specification can be edited using a dialog.

Delete

Deletes one or more variables from the Watch window. The variables to delete are selected in a dialog.

Delete All

Deletes all variables from the Watch window.

Definition Files

In the SimUI, the following types of information are stored on files:

At start-up of the SimUI, the files to read are determined in the following way:

  1. The file names are defined with the Preference Manager. If a file name is not defined there, the default file name def.btns, def.cmds and def.vars is used, respectively.
  2. If the file names does not contain a directory path, the files are searched for in the following directories and the following order:
    • the current directory
    • the user's home directory
    • the installation directory

Once a file has been found, it is read and the contents of the corresponding window are set up. If a file cannot be found, the corresponding window area becomes empty.

Common File Syntax

Each of three text files can contain comment lines starting with the `#' character. Empty lines are not discarded.

Note:

When a file is read, no checks are made upon the relevance or correctness of the definitions contained in the file.

Button and Menu Definitions

The button and menu definitions are stored in a button definition file with the default extension .btns. The button definitions are divided into groups where each group defines a button module in the main window's button area, or a menu in the main window's menu bar.

Syntax

In the file, a button group has the following syntax:

:[COLLAPSED] <group name>
<button label>
<definition>
<button label>
<definition>
  . . .

The <group name> is the string shown in the title bar of the button module. If the group name is prefixed with the string COLLAPSED, the button module is initially collapsed. The <button label> is the label of the button in the button module. The <definition> is the monitor command that will be executed when the button is pressed. The syntax of a button definition is the same as when entering a command textually to the monitor.

A menu has the following syntax:

:MENU <menu name>
<menu choice>
<definition>
<menu choice>
<definition>
 . . .

The <menu name> is the name of the menu shown in the menu bar. The <menu choice> is the name of the menu choice in the menu. The <definition> is the monitor command that will be executed when the menu choice is selected.

In the monitor command definition, a `?' as parameter will not work, but a hyphen `-' can be used to signify the default value. Missing parameters at the end of the command will open dialogs for those parameters.

Defining Multiple Commands

In addition, a button definition may consist of several monitor commands, if they are separated by a space and a semicolon, i.e. ";". The commands are then executed immediately after each other.

Example 336 : Multiple Commands in Simulator

next-transition ; out-via probe -

This button definition executes the next transition and then sends the signal Probe from the environment.

Command Definitions

The command definitions are stored in a command definition file with the default extension .cmds. Each command definition defines a command module in the Command window. The file has the following syntax:

<command>
<command>
  . . .

The <command> is the monitor command that will be executed in the command module. The syntax of a command definition is the same as when entering a command textually to the monitor. All parameter values must be specified explicitly or with the default value `-', i.e. `?' is not allowed, and no parameters may be missing. Command names are case sensitive.

Note:

Care should be taken when deciding what command to execute; commands belonging to the Execute group should be avoided.

Variable Definitions

The variable definitions are stored in a variable definition file with the default extension .vars. Each variable definition defines a variable to display in the Watch window. The file has the following syntax:

(<process>) <variable>
(<process>) <variable>
   . . .

The <process> is the name of the process, possibly augmented with an instance number separated with a space or colon. The <variable> is the name of the variable in that process. Names are not case sensitive.

Example 337 : Variable Definitions in Simulator

(Main) Count
(game:1) guess

Macros

The SimUI has a built-in macro facility. A macro can represent a simulator command or a part of a simulator command. Even though SimUI macro commands are processed by the SimUI, it is possible to enter SimUI macro commands almost as if they were normal simulator commands:

These commands are available for macros:

SimUI Commands

The SimUI examines entered textual commands before sending them to the simulator. If they are SimUI commands they are not sent to the simulator.

Here is a list of all SimUI commands and what they do:

Regression Testing

By using the simulator for regression testing, it is possible to check that an enhanced version of an SDL system does not break the old functionality, that is still expected to work for the same SDL system.

With regression testing in the simulator, you can for instance:

The basic idea is to save and replay the input history, and check the textual simulator output for selected commands. An input history saved to a file is called an input script. A group of input scripts can be collected in the Organizer together with the SDL system. The Organizer provides the possibility to run a group of input scripts (or test cases). This results in a textual summary where it is easy to see any test case failures. To examine a test case failure in detail, it is possible to run a single test case with the SimUI command execute-input-script (see SimUI Commands).

Note that it is also possible to express test cases with the MSC notation. MSC test cases are converted to input scripts before being run in the simulator.

Here is a small example, to see how it works:

Example 338

In System DemonGame (that is provided as an example in the SDL Suite installation), you can (after some initialization) send in a Result signal and expect to get a Score signal back.

To make a test case testing that we get a Score signal back:

  1. Create a simulator for System DemonGame.
  2. Execute the following simulator commands (you do not have to type in the comments):
    • Output-To NewGame Main /* Send in signal NewGame to start a new game. */
    • Next-Transition /* Execute the start transition for process Main. */
    • Next-Transition /* Execute the start transition for process Demon. */
    • Next-Transition /* Execute the transition receiving signal NewGame and creating process Game */
    • Output-To Result Game /* Send in a signal to get the current score. */
    • break-output - env - - - - - - /* Set a breakpoint on signals sent to the environment. */
    • Set-Trace System DemonGame 0 /* Minimize textual trace. */
    • check /* Check the output from the next command. */
    • go /* Execute as far as possible. The simulator will stop and report that the Score signal has been sent to the environment. */
  3. The go command that we are checking produces the following textual simulator output:
    Breakpoint matched by output of Score
  4. Save the input history in an input script, with the SimUI command save-input-history. The last part of the input script will look like this:
    check
    
    go
    
    expected-output start
    
    Breakpoint matched by output of Score
    
    expected-output end
    
    
    
  5. Add a symbol for the input script in the Organizer, with Edit > Add New, plain text, do not show in editor.
  6. Connect the symbol to the input script file with Edit > Connect.
  7. Now, make a test: Deselect everything in the Organizer (to make sure that both the SDL system and the input script will be considered) and choose Tools > Simulator Test. After a dialog, a fresh simulator will be created and the test case run. The result is presented in the Organizer Log.
  8. To force a test case failure:
    • Edit the test case (by double-clicking on the Organizer symbol to get a text editor) by changing the expected output to be something different.
    • Save the test case.
    • Repeat the above test.
    • If everything works as expected, the test case fails.
  9. To examine the details of a test case failure:
    • Restart the simulator.
    • Execute the test case (input script) in the SimUI with the execute-input-script command.
    • If everything works as expected, the expected output from the go command did not match the actual output.

Mapping Instances to Different Environments

When generating test scripts (.CUI scripts) from MSCs, it is possible to select for which specific processes/blocks for which a cui script shall be generated if an MSC testcase describes several blocks.

Through an instance translation table, which is a plain text file in the Organizer with the extension *.itt, it is decided which instances in the MSC that should be regarded as environment. In this file it is for example stated that an instance A really is instance env:2.

Example *.itt file:
MyBlock env:2
MyProcess env:3

The name used for an instance in the MSC is placed first, followed by a space, and then comes the name of the environment instance to map the MSC instance to. Note that the only names that can be used for mapping are env:2, env:3, env:4 etc. and that no numbers can be left out when mapping, i.e. it is not allowed to only use env:2 and env:4 without using env:3.

Whenever an MSC is converted to a CUI test script, the first found (or closest found) translation table from the Organizer is used and all instances in the file are translated according to the table in the file. All instances starting with env (after translation, if there is a translation file) are outside the system, and all other instances are assumed to be inside the system.

Order of execution

In the case where the MSCs used as test scripts only have one environment instance, the order of execution is the same order as messages are connected to the environment instance in.

To determine the order things are done in when several instances are converted to environment instances, the y-coordinate of the connection of messages to environment instances is used. If the y-coordinate of sending in message A is above the y-coordinate of sending in message B, then message A is sent before message B. If two connections have the same y-coordinate, then the x-coordinate is used to determine the order. The left most connection is done first.

Only messages connected to an environment instance in one end and a system instance in the other end are used to drive the simulation. Messages between environment instances and messages within the system are ignored.

For action symbols (that can contain ordinary simulator commands or shortcuts for ordinary simulator commands), the upper connection point to the environment instance is used for determining the order of doing things in.

It is also possible to test in an MSC test script if a service response message is returned to the same environment instance (representing a specific external process) that sent in the service request message, in the case where there are many environment instances. This is done with the output-internal simulator command that is generated by the MSC to CUI converter. An example:

output-internal SignalIn ProcessOne env:2

If the system responds to this message by sending back another message to sender, then the textual trace will contain information about what environment instance the signal was sent to:

* OUTPUT of SignalOut to env:2 from ProcessOne:1

In addition to the output-internal command, the create null env command is generated in the CUI script by the converter. This command will create the environments in the simulator that will be used for the instances that are mapped to an environment instance in the .itt file.

Note that when instances are mapped with an .itt file, process id mapping should not be used.


http://www.ibm.com/rational
Contents Index Previous Next