IBM
Contents Index Previous Next



Monitor Commands


This section provides an alphabetical listing of all available commands in the simulator monitor. Simulator UI commands are described in SimUI Commands.

Alphabetical List of Commands

@ (Keyboard Polling)

Parameters:

(None)

The monitor will repeatedly look at the keyboard for a carriage return, indicating an immediate break in the execution of the current transition. Using the command @, this facility can be turned off. Each time the command @ is entered the monitor toggles between having the keyboard polling for carriage return on and off. At start up keyboard polling is on.

Note:

No other characters may be typed together with the carriage return. If some other characters are typed by mistake, please delete them before typing the carriage return.

To turn keyboard polling off is useful in some situations, for example if a user wants to paste a sequence of commands into the monitor. If the sequence contains an empty line this might cause an unwanted interrupt.

? (Interactive Context Sensitive Help)

Parameters:

(None)

The monitor will respond to a `?' (question mark) by giving a list of all allowed values at the current position, or by a type name, when it is not suitable to enumerate the values. After the presentation of the list, the input can be continued.

Typing `?' at the prompt level gives a list of all available commands, after which a command can be entered. For further help, see the command Help.

ASN1-Value-Notation

Parameters:

(None)

The value notation used in all outputs of values is set to ASN.1 value notation. See also the command SDL-Value-Notation.

Assign-Value

Parameters:

[ `(' <PId value> `)' ]
<Variable name> <Optional component selection>
<New value>

The new value is assigned to the specified variable in the process instance, service instance, or procedure given by the current scope. Sender, Offspring, and Parent may also be changed in this way, but their names may not be abbreviated.

It is, in a similar way as for the command Examine-Variable, possible to handle components in structured variables (struct, strings, array, and Ref) by appending the struct component name or a valid array index before the value to be assigned. Nested structs and arrays can be handled by entering a list of index values and struct component names.

If a PId is given within parenthesis the scope is temporarily changed to this process instance instead.

Breakpoint-At

Parameters:

<SDT reference> <Optional breakpoint commands>

A breakpoint is defined at the symbol specified by the SDT reference. If the execution reaches the symbol, the monitor becomes active immediately before that symbol. SDT references may be obtained by using the Show GR Reference command in an SDL Editor, see Show GR Reference.

The <Optional breakpoint commands> parameter can be used to give monitor commands that should be executed when the breakpoint is triggered. Monitor commands should be separated by " ; ", i.e. space semicolon space.

Breakpoint-Output

Parameters:

<Signal name>
<Receiver process name> <Receiver instance number>
<Sender process name> <Sender instance number>
<Counter>
<Optional breakpoint commands>

A breakpoint is activated and a breakpoint condition is defined. If a breakpoint condition is matched by an output, the monitor becomes active immediately after the symbol containing the output. The breakpoint condition defines one or several outputs and is specified by the parameters. Any of the parameters may be omitted, which implies that any value will match the missing fields in the breakpoint condition. Initially no breakpoints are active.

The <Counter> parameter is used to indicate how many times the breakpoint condition should be true before the monitor should become active. Default value for this parameter is 1, which means that the monitor should be activated each time the breakpoint condition is true.

The <Optional breakpoint commands> parameter can be used to give monitor commands that should be executed when the breakpoint is triggered. Monitor commands should be separated by " ; ", i.e. space semicolon space.

Breakpoint-Transition

Parameters:

<Process name> <Instance number> <Service name>
<State name> <Signal name> <Sender process name>
<Sender instance number> <Counter>
<Optional breakpoint commands>

A breakpoint is activated and a breakpoint condition is defined. If a breakpoint condition is matched by a transition, the monitor becomes active immediately before that transition is started. The breakpoint condition matches one or several transitions and is specified by the parameters. Any of the parameters may be omitted, which implies that any value will match the missing fields in the breakpoint condition. Initially no breakpoints are active.

The <Counter> parameter is used to indicate how many times the breakpoint condition should be true before the monitor should become active. Default value for this parameter is 1, which means that the monitor should be activated each time the breakpoint condition is true.

The <Optional breakpoint commands> parameter can be used to give monitor commands that should be executed when the breakpoint is triggered. Monitor commands should be separated by " ; ", i.e. space semicolon space.

Breakpoint-Variable

Parameters:

<Variable name> <Optional breakpoint commands>

A breakpoint is defined on the specified variable in the process instance given by the current scope. If the variable's value is changed, the monitor becomes active immediately after the symbol or assignment statement where the value is changed. The value is only checked between symbols and between assignment statements in tasks.

The breakpoint is also triggered when the variable no longer exists, i.e. the PId containing the variable is stopped or the procedure containing the variable has reached its end. In this case, the breakpoint is automatically removed.

The <Optional breakpoint commands> parameter can be used to give monitor commands that should be executed when the breakpoint is triggered. Monitor commands should be separated by " ; ", i.e. space semicolon space.

Call-Env

Parameters:

(None)

The Call-Env command performs one call of the function InEnv. See the command Start-Env for more details.

Note:

This command and the commands Start-Env and Stop-Env are only available when the SDL to C Compiler is used to generate applications.

Call-SDL-Env

Parameters:

(None)

The command makes one call to the function that looks for incoming signals from the SDL Suite communication mechanism. This means that all signals that have come to the simulator will be sent to their appropriate receiving process instances. See the command Start-SDL-Env for more details.

Cd

Parameters:

<Directory>

Change the current working directory to the specified directory.

Clear-Coverage-Table

Parameters:

(None)

This command is used to reset the coverage table to 0 in all positions, which means restart counting coverage from now.

Close-Signal-Log

Parameters:

<Entry number>

Stops the signal log with the specified entry number and closes the corresponding log file; see the command Signal-Log for more details. Entry numbers assigned by the command List-Signal-Log should be used.

Command-Log-Off

Parameters:

(None)

The command log facility is turned off; see the command Command-Log-On for details.

Command-Log-On

Parameters:

<Optional file name>

The command enables logging of all the commands given in the monitor. The first time the command is entered a file name for the log file has to be given as parameter. After that any further Command-Log-On commands, without a file name, will append more information to the previous log file, while a Command-Log-On command with a file name will close the old log file and start using a new file with the specified name.

Initially the command log facility is turned off. It can be turned off explicitly by using the command Command-Log-Off.

The generated log file is directly possible to use as a file in the command Include-File. It will, however, contain exactly the commands given in the session, even those that were not executed due to command errors. The concluding Command-Log-Off command will also be part of the log file.

Connect-To-Editor

Parameters:

(None)

This command will create a new Breakpoints menu in the SDL Editor and tell the SDL Editor to show all graphical breakpoints. If no SDL Editor is opened, the menu will appear when an SDL Editor is opened the next time. The commands given in the new menu will only be handled in those simulations that are connected. See also the Disconnect-Editor command.

Create

Parameters:

<Process name> <Parent's PId value> 
<Process parameters>

A process instance of the specified process type is created. If the parent PId is not equal to null, Offspring is set in the specified parent instance. If the number of instances of the specified process type is greater than or equal to the maximum number of concurrent instances, the user has to verify the create action.

Define-Continue-Mode

Parameters:

"On" | "Off"

Defines whether the execution of the simulation shall continue after a command is given. The default is "Off".

Define-Integer-Output-Mode

Parameters:

"dec" | "hex" | "oct"

Defines whether integer values are printed in decimal, hexadecimal or octal format. In hexadecimal format the output is preceded with "0x", in octal format the output is preceded with `0' (a zero).

On input: if the format is set to hexadecimal or octal, the string determines the base as follows: After an optional leading sign a leading zero indicates octal conversion, and a leading "0x" hexadecimal conversion. Otherwise, decimal conversion is used.

The default is "dec", and no input conversion is performed.

Define-MSC-Trace-Channels

Parameters:

"On" | "Off"

Defines whether the env instance should be split into one instance for each channel connected to env in the MSC trace. The default is "Off".

Detailed-Exa-Var

Parameters:

(None)

When printing structs containing components with default value, these values are explicitly printed after this command is given.

Disconnect-Editor

Parameters:

(None)

This command will remove the connection to the SDL Editor. If this simulation is the only connected to the SDL Editor, it will also remove the Breakpoints menu in the SDL Editor. See also the Connect-To-Editor command.

Display-Array-With-Index

Parameters:

"On" | "Off"

When Display-Array-With-Index is On and you examine an array, the value of the array element is printed with its index. Index is added before the value of the array element. The default is "Off".

Down

Parameters:

<Optional service name>

Moves the scope one step down in the procedure call stack. If the current scope is a process containing services, one of the services should be specified. See also the commands Stack, Set-Scope and Up.

Examine-PId

Parameters:

[ `(' <PId value> `)' ]

Information about the process instance given by the current scope is printed (see the Set-Scope command for an explanation of scope). This information contains the current values of Parent, Offspring, Sender and a list of all currently active procedure calls made by the process instance (the stack). The list starts with the latest procedure call and ends with the process instance itself. If the process contains services, these services will be listed, each with its own procedure call stack.

If a PId is given within parenthesis information about this process instance is printed instead.

Examine-Signal-Instance

Parameters:

<Entry number>

The parameters of the signal instance at the position equal to entry number in the input port of the process instance given by the current scope are printed (see the Set-Scope command for an explanation of scope). The entry number is the number associated with the signal instance when the command List-Input-Port is used.

Examine-Timer-Instance

Parameters:

<Entry number>

The parameters of the specified timer instance are printed. The entry number is the number associated with the timer when the List-Timer command is used.

Examine-Variable

Parameters:

[ `(' <PId value> `)' ]
<Optional variable name>
<Optional component selection>

The value of the specified variable or formal parameter in the current scope is printed (see the Set-Scope command for an explanation of scope). Variable names may be abbreviated. If no variable name is given, all variable and formal parameter values of the process instance given by the current scope are printed. Sender, Offspring, Self, and Parent may also be examined in this way. Their names, however, may not be abbreviated and they are not included in the list of all variables.

Note:

If a variable is exported, both its current value and its exported value are printed.

It is possible to examine only a component of a struct, string or array variable, by appending the struct component name or a valid array index value as an additional parameter. The component selection can handle structs and arrays within structs and arrays to any depth by giving a list component selection parameters. SDL syntax with `!' and "( )" as well as just spaces, can be used to separate the names and the index values.

It is also possible to print a range of an array by giving "FromIndex: ToIndex" after an array name. Note that the space before the `:' is required if FromIndex is a name (enumeration literal), and that no further component selection is possible after a range specification.

To see the possible components that are available in the variable, the variable name must be appended by a space and a `?' on input. A list of components or a type name is then given, after which the input can be continued. After a component name, it is possible to append a `?' again to list possible sub components.

To print the value of the data referenced by a Ref pointer it is possible to use the SDL syntax, i.e. the "*>" notation. If, for example, Iref is a Ref(Integer) variable then Iref*> is the integer referenced by this pointer. If Sref is a Ref of a struct, then Sref*> ! Comp1 is the Comp1 component in the referenced struct. The sequence *> ! can in the monitor be replaced by -> (as for example in C).

If a PId is given within parenthesis the scope is temporarily changed to this process instance instead.

Exit

Parameters:

(None)

The simulation is terminated. If the command is abbreviated the monitor asks for confirmation. This is the same command as Quit.

Finish

Parameters:

(None)

This command will execute the currently executing procedure up to and including its return, i.e. it will finish this procedure. The execution will also be interrupted at the end of the transition. In a process, Finish will behave just like the command Next-Transition.

Go

Parameters:

(None)

The execution of the simulation is resumed. The execution will continue until one of the conditions listed in Activating the Monitor becomes true. To stop the execution of transitions, press <Return> (and only this key). The interactive monitor will then become active when the execution of the current SDL symbol is completed.

This command has to be used with care in the interactive monitor, as it might result in executing the simulation program "forever" (if none of the conditions for activating the monitor becomes true). In a catastrophic situation (e.g. an endless loop within an SDL symbol) it is possible to terminate the program by using the way to stop the execution of a program defined in the operating system (<Ctrl+C> on UNIX).

Go-Forever

Parameters:

(None)

The command Go-Forever behaves, in most situations, in the same way as the command Go.

For Go-Forever to behave differently than Go, there has to be an environment to the SDL system that can send signals to the SDL system (communicating simulations or environment functions). When the command Go is issued and the SDL system becomes completely idle (no possible transition and no active timer) the monitor becomes active again and is entered. If Go-Forever was used instead of Go, the monitor is not entered in this case; instead the simulation continues to wait for external stimulus. This feature is valuable when a simulation communicates with other simulations or applications.

Help

Parameters:

<Optional command name>

Issuing the Help command without a parameter will print all the available commands. If a command name is given as parameter, this command will be explained.

Include-File

Parameters:

<File name>

This command provides the possibility to execute a sequence of monitor commands stored in a text file. The Include-File facility can be useful for including, for example, an initialization sequence or a complete test case. It is allowed to use Include-File in an included sequence of commands; up to five nested levels of include files can be handled.

This command also provides the possibility to perform script calling with variable substitution.

In a script file it is possible to refer to variables using $1, $2, ... , $99. The numbered variables refer to the arguments (actual values) given when calling a script using the command Include-File.

Unix shell script expressions like $0, $#, $? and $* are not available to be given as variable references in script files. Letters are not used as reference variables. For example $a, $1b, $ac are not available to be used as reference variables.

The actual values will be given as parameters in the Include-File command after script-file name. It is possible to pass up to 99 actual values. The numbered variables will be substituted by the actual values during execution of commands in the script files.

Arguments should be separated by spaces. $1 will be substituted by arg1, $2 will be substituted by arg2, $3 will be substituted by arg3, and $4 will be substituted by arg4 and so on.

If there is an argument missing, the corresponding reference variable will not get a value, it is up to the user to provide the correct arguments when using the Include-File command.

List-Breakpoints

Parameters:

(None)

All active breakpoints are listed. Each breakpoint is assigned an entry number that can be used in the Remove-All-Breakpoints and Show-Breakpoint commands.

List-GR-Trace-Values

Parameters:

(None)

The values of all currently defined GR traces are listed. The list contains the trace unit type (system, block, process, PId), the unit name, and the GR trace value (both numeric and a textual explanation). See also the commands Set-GR-Trace and Reset-GR-Trace.

List-Input-Port

Parameters:

[ `(' <PId value> `)' ]

A list of all signal instances in the input port of the process instance given by the current scope is printed (see the Set-Scope command for an explanation of scope). For each signal instance an entry number, the signal type, and the sending process instance is given. A `*' before the entry number indicates that the corresponding signal instance is the signal instance that will be consumed in the next transition performed by the process instance. The entry number can be used in the commands Examine-Signal-Instance, Rearrange-Input-Port and Remove-Signal-Instance.

If a PId is given within parenthesis information about this process instance is printed instead.

List-MSC-Log

Parameters:

(None)

This command returns the current status of the MSC log (off / interactive / batch). See also the commands Start-Interactive-MSC-Log, Start-Batch-MSC-Log and Stop-MSC-Log.

List-MSC-Trace-Values

Parameters:

(None)

This command returns the current status for the MSC trace parameters. The list contains the trace unit type (system, block, process, PId), the unit name, and the MSC trace value (both numeric and a textual explanation). See also the commands Set-MSC-Trace and Reset-MSC-Trace.

List-Process

Parameters:

<Optional process name>

A list of all process instances associated with the specified process type is produced. If no process name is specified all process instances in the system are listed. The list will contain the same details as described for the List-Ready-Queue command.

List-Ready-Queue

Parameters:

(None)

A list is produced containing the process instances in the ready queue, i.e., those instances that have received a signal that can cause an immediate transition, but that have not yet had the opportunity to execute this transition to its end. If the process contains services, the currently active service is also listed. If a process/service instance has active procedure calls, the current executing procedure instance is also listed. For each instance in the list the following information is given:

  1. An entry number (process instances only).
  2. An identification of the process/service/procedure instance.
  3. The name of its current state. If the state name is followed by a `*', then the process/service/procedure is currently executing a transition starting from this state.
  4. The number of signal instances in the input port of the process instance.
  5. The signal name of the signal instance that will cause (or has caused) the transition by the process instance. This signal instance is marked with a `*' before the entry number, if the command List-Input-Port is issued. If the transition has started the signal is no longer in the input port.

The process instance, the state, and the signal instance determine uniquely the transition that will be executed by the process instance when it gets permission to do so.

The entry number can be used in the command Rearrange-Ready-Queue.

List-Signal-Log

Parameters:

(None)

Print information about the currently active signal log; see the command Signal-Log for more details. Each log is assigned an entry number which can be used in subsequent Close-Signal-Log commands.

List-Timer

Parameters:

(None)

A list of all currently active timers is produced. For each timer, its corresponding process instance and associated time is given. An entry number will also be part of the list, which can be used in the command Examine-Timer-Instance.

List-Trace-Values

Parameters:

(None)

The values of all currently defined traces are listed. The list contains the trace unit type (system, block, process, PId), the unit name and the trace value (both numeric and a textual explanation). See also the commands Set-Trace and Reset-Trace.

Log-Off

Parameters:

(None)

The command Log-Off turns off the interaction log facility, which is described in the command Log-On.

Log-On

Parameters:

<Optional file name>

The command Log-On takes an optional file name as a parameter and enables logging of all the interaction between a simulation program and the user that is visible on the screen. The first time the command is entered, a file name for the log file has to be given as parameter. After that any further Log-On commands, without a file name, will append more information to the previous log file, while a Log-On with a file name will close the old log file and start using a new file with the specified file name.

Initially the interaction log facility is turned off. It can be turned off explicitly by using the command Log-Off.

News

Parameters:

(None)

The News command summarizes the changes in the textual monitor user interface from previous releases.

Next-Statement

Parameters:

<Optional number of statements>

This command is used to step statement for statement through SDL transitions. A statement is the same as a symbol, except that a task symbol may contain several assignment statements; compare with the Next-Symbol command.

Next-Statement steps over procedure calls, i.e. all actions in the procedure will be executed and the monitor will be entered again when the statement after the procedure call is reached; compare with the Step-Statement command.

After making the step(s) the monitor is entered, making it possible to, for example, examine the temporary status of the actual process instance.

Note:

The right hand side of an assignment may contain a value returning procedure call.

Next-Symbol

Parameters:

<Optional number of symbols>

This command is used to step symbol for symbol through SDL transitions. A symbol may contain several statements; compare with the Next-Statement command.

Next-Symbol steps over procedure calls, i.e. all actions in the procedure will be executed and the monitor will be entered again when the symbol after the procedure call is reached; compare with the Step-Symbol command.

Using the optional integer parameter, a specified number of symbols can be stepped through. Next-Symbol will, however, never step from within one transition into another transition.

After making the step(s) the monitor is entered, making it possible to, for example, examine the temporary status of the actual process instance.

Note:

Join is not considered a symbol by this command.

To determine how far a transition has been executed, the commands Show-Next-Symbol and Show-Previous-Symbol, together with trace printouts and GR traces can be used. The last trace printout is from the last executed symbol (if it has caused a printout, which depends on the trace level), while the symbol next to be executed is selected by the GR trace, if GR trace is on.

Next-Transition

Parameters:

(None)

The next transition is executed. If real time is used and the next transition is a timer output scheduled in the future (more than a second from now), the command Next-Transition will wait one second, after which the monitor is entered again.

Executing a Next-Transition command within a transition will execute the remaining part of the transition.

Next-Visible-Transition

Parameters:

(None)

A number of transitions are executed up to and including the next transition with a trace value > 0. For a timer output transition, it is the trace value for the corresponding process instance that is considered.

This command should be used with care in the interactive monitor, as it might result in executing the simulation program "forever" (if no transition with trace>0 is ever executed). To stop the execution of transitions, press <Return>. The interactive monitor will then become active when the execution of the current SDL symbol is completed.

Nextstate

Parameters:

<State name>

The state of the process/service/procedure instance given by the current scope is changed (see the Set-Scope command for an explanation of scope). This command implies that all actions in a nextstate are performed, i.e. recalculation of enabling conditions and continuous signals, and searching for a signal to be received according to the input and save sets. As a consequence the ready queue for process instances may change.

Now

Parameters:

(None)

The current value of the simulation time is printed.

Output-From-Env

Parameters:

-

The command will list all signals possible to send into the system, together with receiver. If the signal contains parameters, an empty parenthesis pair will be added after the signal name. Only signals that will trigger a transition directly will be listed. So signals causing an immediate null transition or signals that will be saved are not listed.

By just giving Output-From-Env in the Simulator UI, the possible choices will be given in a dialogue and by selecting one of the signals it is sent into the system. If the signal contains parameters they will be given "null" values.

Output-Internal

Parameters:

<Signal name> <Signal parameters> 
<Receiver's PId value> <Sender's PId value>

The command is used to simulate an output of an internal signal instance between two process instances in the system. The parameter <Sender's PId value> may also denote "env:1". No check is made to ensure that a path of signal routes and channels exists. The monitor responds with either of the three messages below.

Signal <name> is not in valid input signal set of 
process <name>

The signal was not in the valid input signal set of the receiver and can thus not be handled by the receiver. The signal was immediately discarded.

Signal <name> was sent to <receiver> from <sender>

The signal instance was successfully sent and was placed in the input port of the receiver.

Signal <name> caused an immediate null transition

The receiving process instance is currently waiting in a state where the specified signal type neither may cause an input operation, nor is saved. The signal instance is immediately discarded (in SDL this is called a null transition, i.e a transition with no actions, leading back to the same state).

Output-None

Parameters:

<PId value> <Optional service name>

The command is used to send a signal "none" to the specified process instance. If the process instance contains services, one of the services should to be specified as well. The none signal is used to indicate that a spontaneous transition should be initiated in the current state.

Output-To

Parameters:

<Signal name> <Signal parameters> 
<Receiver's PId value>

The command is used to send a signal from the environment of the system to a process instance in the system. It will be checked that a path of channels and signal routes exists from the environment to the specified process instance.

The monitor will respond with either of the messages described below, or by an error message if no path existed.

Signal <name> was sent to <receiver> from <sender>

The signal instance was successfully sent and is placed into the input port of the receiver.

Signal <name> caused an immediate null transition.

The receiving process instance is currently waiting in a state where the specified signal type neither may cause an input operation, nor is saved. The signal instance is immediately discarded (in SDL this is called a null transition, a transition with no actions, leading back to the same state).

Output-Via

Parameters:

<Signal name> <Signal parameters> 
<Optional channel name>

The command is used to send a signal from the environment of the system to a process instance in the system via the specified channel. If no channel is given, it is assumed that any channel from the environment to the system may be selected. It will be checked that there exists one process instance that can receive the signal, according to the rules of outputs in SDL.

The monitor will respond with either of the messages below, or by an error message if the number of possible receivers is not equal to one.

Signal <name> was sent to <receiver> from <sender>

The signal instance was successfully sent and is placed into the input port of the receiver.

Signal <name> caused an immediate null transition.

The receiving process instance is currently waiting in a state where the specified signal type neither may cause an input operation, nor is saved. The signal instance is immediately discarded (in SDL this is called a null transition, a transition with no actions, leading back to the same state).

Print-Coverage-Table

Parameters:

<File name>

This command can be used to obtain test coverage information and profiling information. Each time the command is issued a coverage file, with the name specified as parameter, is produced in the work directory containing the relevant information. The coverage file always reflects the situation from the start of the simulation. To study the information in the coverage file, it can be opened in the Coverage Viewer; see The SDL Coverage Viewer.

Note:

The specified file is always overwritten, i.e. there is no confirmation message if an existing file is specified.

The generated file consists of two sections, first a summary with profiling information, containing the number of transitions and the number of symbols executed by each process type. Secondly the file contains detailed information about how many times each symbol and each state - input combination is executed.

Example 332 : Profiling Information in Coverage File

*************** PROFILING INFORMATION **************

2  System DemonGame : Transitions = 13, Symbols = 40
3  Block GameBlock
4  Process Main : Transitions = 3 (23%),
                  Symbols = 10 (25%), MaxQ = 2
4  Process Game : Transitions = 6 (46%),
                  Symbols = 15 (37%), MaxQ = 2
3  Block DemonBlock
4  Process Demon : Transitions = 4 (30%),
                  Symbols = 15 (37%), MaxQ = 1

This information in Example 332 should be interpreted in the following way:

Note:

To be true, profiling information execution time ought to be measured instead of the number of transitions and number of executed symbols, but this information is still very valuable for getting a feeling for the load distribution.

Example 333 : Coverage Table in Coverage File

************** COVERAGE TABLE DETAILS **************

2 System DemonGame

3 Block GameBlock

4 Process Main
  1 : Start  #SDTREF(SDL,main.spr(1),131(30,10),1)
  1 : Game_Off  Newgame  #SDTREF(SDL,main.spr(1),137
  1 : Game_On  Endgame  #SDTREF(SDL,main.spr(1),119(
  --------------------
  1 START : #SDTREF(SDL,main.spr(1),131(30,10),1)
  1 INPUT : #SDTREF(SDL,main.spr(1),137(31,44),1)
  1 INPUT : #SDTREF(SDL,main.spr(1),119(56,44),1)
  1 NEXTSTATE : #SDTREF(SDL,main.spr(1),134(34,29),1)
  1 CREATE : #SDTREF(SDL,main.spr(1),140(37,59),1)
  1 TASK : #SDTREF(SDL,main.spr(1),143(34,72),1)
  1 NEXTSTATE : #SDTREF(SDL,main.spr(1),146(35,89),1)
  1 OUTPUT : #SDTREF(SDL,main.spr(1),122(56,59),1)
  1 TASK : #SDTREF(SDL,main.spr(1),125(60,72),1)
  1 NEXTSTATE : #SDTREF(SDL,main.spr(1),128(59,89),1)

For each process type two types of information are given, separated by a line of hyphens:

To identify the process symbols, the command Show GR Reference command in the SDL Editor's Tools menu can be used for the printed GR references. (See Show GR Reference.)

Proceed-To-Timer

Parameters:

(None)

This command will execute all transitions up to but not including the next timer output. The timer output will not be executed even if it is the next transition.

Proceed-Until

Parameters:

<Time value>

The execution of the simulation is resumed. The monitor will become active when the value of the simulation time first becomes equal to the time value given as parameter.

Note that relative time values can be given using the `+' sign. Entering "+5.0" as parameter is interpreted as the time value NOW+5.0. See also Input and Output of Data Types.

Quit

Parameters:

(None)

The simulation is terminated. If the command is abbreviated the monitor asks for confirmation. This is the same command as Exit.

Rearrange-Input-Port

Parameters:

<Entry number> <New entry number>

This command is used to change the order of signal instances in the input port of the process instance given by the current scope (see the Set-Scope command for an explanation of scope).

The entry number parameters refer to the numbers assigned by the command List-Input-Port. The signal instance with entry number equal to the first parameter will be moved to a position where it in a subsequent List-Input-Port command will be assigned the entry number given as the second parameter.

Rearrange-Ready-Queue

Parameters:

<Entry number> <New entry number>

This command is used to change the order in which transitions by process instances are executed. The entry number parameters refer to the entry numbers assigned by the command List-Ready-Queue. The process instance with entry number equal to the first parameter will be moved to a position where it in a subsequent List-Ready-Queue command will be assigned the entry number given as the second parameter.

The Rearrange-Ready-Queue command should be used with care when process priorities are used. The ready queue is then sorted in priority order (see also Scheduling), which means that a rearrangement might disturb this order. Such a disturbance does not harm, except when a new process should be inserted into the ready queue. In this situation the insert point might not be the proper one. The following insert algorithm is used: Search from the end of the ready queue until a process with higher or equal priority (lower or equal priority value) is found, then insert the new process after the found process. If no process with higher or equal priority is found, then insert the new process first in the ready queue.

REF-Address-Notation

Parameters:

(None)

REF values (pointers introduced using the generator Ref) are printed as addresses, using the HEX value for the address. The Null value is printed as Null. On input, both this syntax and the Value-Notation (see command REF-Value-Notation) can be used.

The same applies for Own and ORef values.

REF-Value-Notation

Parameters:

(None)

REF values (pointers introduced using the generator Ref) are printed as NEW(<the value the pointer refers to>). This is the default syntax for REF values. It means that complete lists or graphs will be printed. Example:

NEW( (. 1, NEW( (. 2, Null .) ) .) )

To avoid problems in cyclic graphs a special syntax is used if a pointer refers to an address already presented in the output. OLD n, where n is a digit, means a reference to the n:th NEW in the printed value. Example:

NEW( (. 1, NEW( (. 2, OLD 1 .) ) .) )

The Null value is printed as Null. On input both this syntax and the Address-Notation (see command REF-Address-Notation) can be used.

The same applies for Own and ORef values.

Remove-All-Breakpoints

Parameters:

(None)

This command removes all breakpoints.

Remove-At

Parameters:

<SDT reference>

This command removes all breakpoints at the symbol specified by the SDT reference.

Remove-Breakpoint

Parameters:

<Entry number>

This command removes the breakpoint with the specified entry number. The entry number given by List-Breakpoints should be used.

Remove-Signal-Instance

Parameters:

<Entry number>

The signal instance with the given entry number in the input port of the process instance given by the current scope is removed (see the Set-Scope command for an explanation of scope). The entry number given by List-Input-Port should be used. If this signal was selected for the next transition, the process instance will execute an implicit nextstate action.

Note:

Entry numbers are just positions in the input port. The removal of a signal changes the entry numbers of the remaining signals.

Reset-GR-Trace

Parameters:

<Optional unit name>

The GR trace value of the given unit is reset to undefined. If no unit is specified the GR trace value of the system is reset to undefined. As there always has to be a GR trace value defined for the system,
Reset-GR-Trace on the system is considered to be equal to setting the GR trace value to 0. For more information about optional unit names, see the command Set-Trace.

Reset-MSC-Trace

Parameters:

<Optional unit name>

The MSC trace value of the given unit is reset to undefined. If no unit is specified the MSC trace value of the system is reset to undefined. As there always has to be a MSC trace value defined for the system,
Reset-MSC-Trace on the system is considered to be equal to setting the trace value to 0. For more information about optional unit names, see the command Set-MSC-Trace.

Reset-Timer

Parameters:

<Timer name> <Timer parameters>

The result of the command is exactly the same as if the process instance given by the current scope had executed a reset action. If the reset action causes a timer signal to be removed and this signal was selected for the next transition, the process instance will execute an implicit nextstate action.

Reset-Trace

Parameters:

<Optional unit name>

The trace value of the given unit is reset to undefined. If no unit is specified the trace value of the system is reset to undefined. As there always has to be a trace value defined for the system, Reset-Trace on the system is considered to be equal to setting the trace value to 0. For more information about optional unit names, see the command Set-Trace.

Restore-State

Parameters:

<File name>

This command will restore the state of the current simulation to a state given in a file created with the Save-State command. The file name is given as parameter.

The write and read functions for the sorts are used to save and restore the variable values. So if a user has added a sort via the ADT directive, these write and read functions must be consistent.

It is recommended to restart the simulator before giving the Restore-State command. The command is not allowed when the execution is within a transition.

If the SDL system contains the Any construct, the sequence of random numbers will not be the same after the restore.

Only the sdl execution state is restored, no monitor settings are restored. E.g. Show-Previous-Symbol, Show-Next-Symbol does not work directly after a restore. The MSC trace is not restored. Coverage is not restored either.

The ADT package pidlist.pr is not supported, since the PId synonyms that are initialized are not valid after the restore.

Extern C and C++ variables will not be saved and restored since the simulator has no knowledge of them.

Charstar, Voidstar and Voidstarstar variables are not handled.

Since all variables are saved, dangling Ref and ORef variables will cause problems.

Scope

Parameters:

(None)

This command prints the current scope. See the command Set-Scope for a description of scope.

SDL-Value-Notation

Parameters:

(None)

The value notation used in all outputs of values is set to SDL value notation. This is the default value notation. See also the command ASN1-Value-Notation.

Save-Breakpoints

Parameters:

<File name>

This command will save all breakpoints in a file, with the name specified as parameter (in the work directory). It is written as a text file with commands, so the breakpoints can be restored with the Include-File command.

Save-State

Parameters:

<File name>

This command will save the state of the current simulation in a file, with the name specified as parameter (in the work directory). It is written as a text file with special commands, so the state can be restored with the Restore-State command.

Set-GR-Trace

Parameters:

<Optional unit name> <Trace value>

The GR trace value is assigned to the specified unit (system, block, process, or process instance). If no unit is specified the GR trace value is assigned to the system. The initial GR trace value of the system is 0, i.e. no GR trace, while it is undefined for all other units. For more information about optional unit names, see the command Set-Trace.

For a description of the possible GR trace values, see GR Traces.

Set-MSC-Trace

Parameters:

<Optional unit name> <Trace value>

This command enables the trace of SDL events that take place during the simulation and which can be transformed into events in a Message Sequence Chart. Typically, the events that can be transformed are sending and consumption of signals, and creation and termination of processes.

Note:

Setting the MSC trace value with this command does not start the actual logging of MSC events. To do this, the command Start-Interactive-MSC-Log or Start-Batch-MSC-Log is used.

The scope of the trace can be delimited by specifying an optional unit name and a trace value. The general considerations for specifying the unit name for the command Set-Trace are also applicable for Set-MSC-Trace.

Optional Unit Name

Trace Value

The initial MSC trace value of the system is 1. For more information on MSC trace values, see Message Sequence Chart Traces.

Note:

Once the logging of Message Sequence Chart traces has been started (using any of the commands Start-Interactive-MSC-Log or Start-Batch-MSC-Log) modifying the scope of trace may cause unpredictable results, such as Message Sequence Charts with an unexpected appearance.

Set-Scope

Parameters:

<PId value> <Optional service name>

This command sets the scope to the specified process, at the bottom procedure call. If the process contains services, one of the services can be given as parameter to the command. A scope is a reference to a process instance, a reference to a service instance if the process contains services, and possibly a reference to a procedure instance called from this process/service. The scope is used for a number of other commands for examining and changing the local properties of a process instance. The scope is automatically set by the execution commands, when entering the monitor, to the next process in turn to execute.

The command Scope prints out the current scope; i.e. the name of the process instance and possibly the service instance and the called procedure instance. See also the commands Stack, Define-MSC-Trace-Channels and Up.

Set-Timer

Parameters:

<Timer name> <Timer parameters> <Time value>

The result of the command is exactly the same as if the process instance given by the current scope had executed a set action. If the set action causes a timer signal to be removed and this signal was selected for the next transition, the process instance will execute an implicit nextstate action.

Set-Trace

Parameters:

<Optional unit name> <Trace value>

The trace value is assigned to the specified unit (system, block, process, or process instance). If no unit is specified the trace value is assigned to the system. The initial trace value for the system is 4, while it is undefined for all other units. For a description of the possible trace values, see Trace Limit Table.

There might, in some cases, be problems in identifying a specific unit. If more than one unit in the system match the, possibly abbreviated, unit name, the first unit found when searched from the system level will be assigned. To make sure the correct unit is assigned, the unit's diagram type, e.g. "process" (unabbreviated), can be introduced before the unit name. If there still are problems, for instance due to the fact that there are several processes with the same name, a qualifier should be inserted immediately before the unit name. An example can be found in Specifying Unit Names.

To specify a PId value, a colon and an instance number must follow directly after the process name; see also Input and Output of Data Types.

Show-Breakpoint

Parameters:

<Entry number>

This command is only applicable for symbol breakpoints defined with the command Breakpoint-At. The breakpoint with the specified entry number is listed, and the symbol with the breakpoint will be selected in an SDL Editor showing the source GR document. The entry number given by List-Breakpoints should be used.

Show-C-Line-Number

Parameters:

(None)

This command prints the .c file name and line number where the execution of the current SDL transition is suspended. The Text Editor is opened with the cursor positioned on that line in the C source file. The given line number will reference a statement with the following structure:

  XBETWEEN_SYMBOLS(...)

The case label just following this statement is the place where the execution will be resumed when an execute command is given in the monitor.

The Show-C-Line-Number command is mainly thought to be used when the execution is interrupted within an SDL transition. If the command is issued between two transitions, the XBETWEEN_SYMBOLS statement immediately before the last Nextstate or Stop operation will be referenced in the printout, together with a warning that this is not the current position.

Note:

Changes made in the monitor, as for example Rearrange-Ready-Queue, will not affect the printout by this command.

Show-Coverage-Viewer

Parameters:

(None)

This command starts the Coverage Viewer tool with the current test coverage loaded.

Show-Next-Symbol

Parameters:

(None)

The symbol in turn to be executed will be selected in an SDL Editor showing the source GR document. If the simulation is not connected to the SDL Suite or the SDL source document is in SDL/PR, a GR symbol reference or a PR reference will instead be displayed on the screen. The details about GR symbol references are presented in Dynamic Errors. A PR reference is a file name and a line number. See also Syntax.

Note that between the execution of two transitions, i.e. after a Nextstate or Stop operation, no next symbol can be shown. Note also that changes made in the monitor, as for example changing the ready queue using the command Rearrange-Ready-Queue, will not affect the symbol selected by Show-Next-Symbol.

This command uses the same mechanisms to select symbols in the SDL Editor as the GR trace facility, so the same general characteristics as presented in GR Traces are also valid for this command.

Show-Previous-Symbol

Parameters:

(None)

The last executed symbol will be selected in an SDL Editor displaying the source GR document. If the simulation is not connected to the SDL Suite or the SDL source document is in SDL/PR, then a GR symbol reference or a PR reference will instead be displayed on the screen. See the command Show-Next-Symbol for more information.

Show-Versions

Parameters:

(None)

The versions of the SDL to C Compiler and the runtime kernel that generated the currently executing program are presented.

Signal-Log

Parameters:

<Unit name> <File name>

Starts logging of signals to a specified file. See also the commands Close-Signal-Log and List-Signal-Log.

The unit name parameter should be either a channel, a signal route, a system, a block, a process type, or a process instance.

Note that the process "env" is a legal unit in the Signal-Log command. By specifying "env" as unit parameter, the signal interface between the system and the environment is logged. For more information about the unit name parameter, see the command Set-Trace.

Stack

Parameters:

(None)

The procedure call stack for the PId/service defined by the scope is printed. For each entry in the stack, the type of instance (procedure/process/service), the instance name and the current state is printed. See also the commands Set-Scope, Define-MSC-Trace-Channels and Up.

Start-Batch-MSC-Log

Parameters:

<Symbol level> <File name>

This command starts the logging of SDL events which can be translated into the corresponding MSC events in a log file (see Mapping Between SDL and MSC). See also the commands Start-Interactive-MSC-Log and Stop-MSC-Log.

The results will be stored in a log file, whose contents are specific for this purpose. That log file can later on be read by a Message Sequence Chart Editor, where its contents are interpreted as a Message Sequence Chart and displayed as such.

The symbol level parameter determines if states and actions should be included in the MSC log. For a description of the possible symbol level values, see Level of Symbol Logging.

The file name parameter to this command can be any valid file name, although it is recommended to use a file name with the suffix .mpr, since this is the default suffix used when reading a log file into a Message Sequence Chart Editor.

Start-Env

Parameters:

(None)

When the SDL to C Compiler is used to generate applications, interface functions towards the environment of the SDL system must be provided. The InEnv function, which is used to enter signals into the SDL system, is frequently called from the main loop in the process scheduler. During debugging, the polling of the InEnv function can turned on and turned off.

The Start-Env command turns on the polling of InEnv. At start up of the program polling is turned off. See also the commands Stop-Env and Call-Env.

Note:

This command and the commands Stop-Env and Call-Env are only available when the SDL to C Compiler is used to generate applications.

Start-Interactive-MSC-Log

Parameters:

<Symbol level>

This command starts the logging of SDL events which can be translated into the corresponding MSC events in a Message Sequence Chart Editor (see Mapping Between SDL and MSC). See also the commands Start-Batch-MSC-Log and Stop-MSC-Log.

The symbol level parameter determines if states and actions should be included in the MSC log. For a description of the possible symbol level values, see Level of Symbol Logging.

When the command is issued, the following takes place:

  1. An instance of the Message Sequence Chart Editor is started. Each currently existing (SDL) process instance is displayed as an instance, with its instance head and its instance axis.
  2. Following the execution of the simulation, each SDL event which is possible to map to an MSC event and which is within the scope of MSC trace which is currently defined will automatically be displayed in the MSC Editor. Each event will cause the insertion point in the MSC Editor to be moved downwards with one step, which provides a feeling of absolute order between events.

Some drawing conventions and default layouting algorithms are used when drawing the automatically generated Message Sequence Chart. These conventions are described in Drawing Conventions.

Start-SDL-Env

Parameters:

(None)

A simulator can communicate with other simulations using SDL signals and the SDL Suite communication mechanism. Signals sent to the environment in one simulation can enter as signals from the environment in another simulator.

This command is used to tell a simulator to start sending signals that are designated to the environment via the SDL Suite communication mechanism and to start looking for incoming signals (polling) from the SDL Suite communication mechanism. See also the commands Stop-SDL-Env and Call-SDL-Env.

This facility is at program start up turned off, and should only be turned on when a simulator should be able to communicate with other simulators (or applications).

Note:

The command must be given in both communicating simulators.

Start-ITEX-Com

Parameters:

(None)

This command starts the communication with the TTCN Suite.

Stop-ITEX-Com

Parameters:

(None)

This command stops the communication with the TTCN Suite.

Start-SimUI

Parameters:

(None)

This command starts a Simulator UI and connects the running simulator to it. After this it is only possible to give commands in the UI.

Start-UI

Parameters:

(None)

This command attempts to start the program sdtenv in the start directory. The started program is assumed to connect itself to the SDL Suite communication mechanism and can then communicate with the simulation program.

Note:

The command Start-SDL-Env should be given in the simulation program to make it communicate.

Step-Statement

Parameters:

<Optional number of statements>

This command is used to step statement for statement through SDL transitions. A statement is the same as a symbol, except that a task symbol may contain several assignment statements; compare with the command Step-Symbol.

Step-Statement will step into procedure calls; compare with the Next-Statement command.

After making the step(s) the monitor is entered, making it possible to, for example, examine the temporary status of the actual process instance.

Note:

The right hand side of an assignment may contain a value returning procedure call.

Step-Symbol

Parameters:

<Optional number of symbols>

This command is used to step symbol for symbol through SDL transitions. A symbol may contain several statements; compare with the Step-Statement command.

Step-Symbol will step into procedure calls; compare with the Next-Symbol command.

Using the optional parameter, a specified number of symbols can be stepped through. Step-Symbol will, however, never step from within one transition into another transition.

After making the step(s) the monitor is entered, making it possible to, for example, examine the temporary status of the actual process instance.

Note:

Join is not considered a symbol by this command.

Stop

Parameters:

<PId value> <Optional service name>

The specified process instance is stopped. If the process contains services, then either the process can be stopped by giving no service parameter, or one of the services can be stopped. The result of the command is exactly the same as if the process instance or service instance had executed a stop action.

Stop-Env

Parameters:

(None)

This command turns off the polling of the InEnv function; see the Start-Env command for more details.

Note:

This command and the commands Start-Env and Call-Env are only available when the SDL to C Compiler is used to generate applications.

Stop-MSC-Log

Parameters:

(None)

This command stops the logging of Message Sequence Chart events (in interactive mode as well as in batch mode). In the case of a batch mode logging, the log file will be closed. See the commands Start-Interactive-MSC-Log and Start-Batch-MSC-Log for more details.

Following this command, it is possible to log the rest of the session on a new file.

Stop-SDL-Env

Parameters:

(None)

The command turns off the communication mechanism described for the Start-SDL-Env command.

Up

Parameters:

(None)

Moves the scope one step up in the procedure call stack. Up from a service leads to the process containing the service. See also the commands Set-Scope, Stack and Define-MSC-Trace-Channels.


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