![]() |
![]() |
![]() |
![]() |
![]() |
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).
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:
- Both Undo and Command open a dialog with all commands entered so far. In the Undo case, all the commands to redo can be selected, and the default is to redo all but the last one, which is equivalent to an Undo of the last command. In the Command case, only one of the commands to re-execute can be selected. For more information, see Undo/Redo Commands.
- Save will save all monitor commands issued by the user so far to a command file. It opens a file selection dialog, in which the name of a command file is selected (on UNIX preferably with the suffix .com).
- Go to Source will go to the SDT reference selected in the text area.
- Add to watchwindow will add the variable selected in the text area to the watch window.
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:
- Parameter values that are file names are selected in File Selection Dialogs.
- Parameter values of enumeration type are presented in lists, from which the value can be selected (see Figure 461).
- Other parameter values are prompted for in simple text input dialogs. In these dialogs, the button Default value will enter a "null" value for the parameter in the input field.
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:
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:
- Open simulator: Open an existing simulator executable file.
- Restart simulator: Restart the current simulator from the initial system state.
- Rerun script: Rerun last executed script.
- Undo command(s): Undo one or more commands.
- Show Organizer: Show the Organizer main window.
- Show Help: Show help on Simulator user interface.
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:
Each module consists of a title bar and a number of command buttons arranged in rows and columns. The title bar displays:
- A collapse/expand toggle button. Clicking on this button collapses the module so that only the title bar is visible, and expands the module back to its current size so that the buttons become visible.
- The group name of the button module.
- A Group button, providing a menu with commands affecting the buttons in the module.
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.
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.
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.
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.
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
The Send Signal Module
The Examine Module
The Trace Module
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
- View Menu
- Buttons Menu
- Log Menu
- General Menu
- Execute Menu
- Examine Menu
- Change Menu
- Show Menu
- Trace Menu
- Breakpoint Menu
- Help Menu
(See Help Menu.)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 input history contains all textual commands sent to the SimUI.
- The command history contains all textual commands sent to the simulator.
- The complete log contains all textual output presented during a simulator session, this includes both user commands and simulator output.
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:
- Macros: The input history contains
Output-to MySignal ($maxvalue) MainOutput-to MySignal (37329) Main- Check: This SimUI command, together with its expected output section, is saved in the input history but not in the command history.
- Execute input script: This SimUI command is saved in the input history, while the command history contains the executed commands.
The Log menu contains the following menu choices:
- Save Input History
- Save Command History
- Clear Input History
- Clear Command History
- Start/Stop Complete Log
- Log Status
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.
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
Execute Menu
Examine Menu
Change Menu
Show Menu
Trace Menu
Breakpoint Menu
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.
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:
Each module consists of a title bar and a scrollable text area for the command output. The title bar displays:
- A collapse/expand toggle button. Clicking this button collapses the module so that only the title bar is visible, and expands the module back to its current size so that the text area becomes visible. When a module is expanded, the text area is automatically updated.
- The command that is executed.
- A Command button, providing a menu with commands affecting the module.
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.
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.
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:
- 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.
- If the file names does not contain a directory path, the files are searched for in the following directories and the following order:
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.
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.
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) guessMacros
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:
- Type in the SimUI macro command. Note though, that SimUI commands cannot be abbreviated in the same way as simulator commands.
- Define a button or a menu for the SimUI macro command.
These commands are available for macros:
- Use add-macro to define a new macro:
add-macro <macro name> <macro value>add-macro maxvalue 37329- Use list-macros to see all defined macros and their values:
list-macrosCommand: list-macrosNumber of macros defined: 1Macro name: maxvalueMacro value: 37329- Use $ to get the value of a defined macro:
$<macro name>Output-to MySignal ($maxvalue) MainOutput-to MySignal (37329) Main- Use remove-macro to remove an already defined macro:
remove-macro <macro name>remove-macro maxvalueSimUI 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:
- add-macro
- Adds a new SimUI macro. For details, see Macros.
- check
- When commands are entered manually and a check command is issued, the SimUI saves the simulator output for the next command in an expected output section in the input history.
- When commands are read from file by executing an input script, and a check command is encountered, the SimUI compares the simulator output for the next command with the expected output from the input script. The SimUI reports if the check passed or failed.
- clear-command-history
- clear-input-history
- execute-input-script
- If a relative file name is used, then it is interpreted as relative to the Organizer source directory.
- If parameters are given as a space separated list after the file name, then these parameters can be accessed with $1, $2, ... in the called script. It is also possible to access the number of parameters with $# and the name of the calling script with $0.
- list-macros
- Produces a list of all defined macros and their values. For more details, see Macros.
- remove-macro
- Removes an already existing SimUI macro. For more details, see Macros.
- save-command-history <file name>
- save-input-history
- set-source
- set-synonym-file <file name>
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:
- Send in signals and check that the correct signals are sent back out again.
- Check that a variable has the correct value at a specific moment.
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:
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:
- Create a simulator for System DemonGame.
- 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. */
- The go command that we are checking produces the following textual simulator output:
Breakpoint matched by output of Score- 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:
checkgoexpected-output startBreakpoint matched by output of Scoreexpected-output end- Add a symbol for the input script in the Organizer, with Edit > Add New, plain text, do not show in editor.
- Connect the symbol to the input script file with Edit > Connect.
- 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.
- To force a test case failure:
- To examine the details of a test case failure:
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:2MyProcess env:3The 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:2If 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:1In 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 |
![]() |
![]() |
![]() |
![]() |