![]() |
![]() |
![]() |
![]() |
![]() |
SDL Target Tester Commands
Syntax of SDL Target Tester Commands
Command Names
Command names are entered character by character on the keyboard. Each command consists of ASCII characters, terminated by a carriage return. A command is interpreted, after the carriage return is given. Commands may have parameters. Command names may be abbreviated by giving sufficient characters to distinguish it from other command names. The command names are interpreted from left to right. There is no distinction between upper and lower case letters.
Consider, as an example, the command ?Breaklist. The command may be entered as "?b". However, if only `?' is typed, sdtmt will respond with the error message:
Command was ambigous, choose one from:< list of commands >since the command cannot be distinguished from, for example, the ?Queue command. As additional information a list of all commands which would fit to the entered command and which are allowed in the current context is given.
Command Parameters
A parameter is separated from the command name by one or more spaces. The same is applicable to the separation of two parameters. There is no distinction between upper and lower case letters.
Each parameter is mandatory from a syntactical point of view and must be specified. No parameters may be left out.
If the parameter list following a command name is not complete, a dialog window is opened to enter the missing parameter(s).
Specifying more parameters than the command can handle, sdtmt prompts
**ERR:Extra parameters specified in command.If the type of any parameter, which was entered, does not match the expected one, then sdtmt responds with an appropriate error message according to the expected type. Type
help commandnameAbbreviation of SDL Names
Command parameters that are SDL names, may also be abbreviated, as long as the abbreviation is unique. If a name is equal to the first part of another name, as for example Wait and Wait_For_Me, then any abbreviation of Wait is ambiguous. However, if all characters of the shorter name are given (Wait in this example), this is considered as an exact match and the short name will be selected.
Errors in Commands
If an error is detected in a command name or in one of its parameters, an appropriate, self explanatory error message is displayed on the screen. The command will be ignored.
Input and Output of Data Types
<Processtype Instance>
Process type is an ASCII string identifying the SDL name of the process. Process names must be unique for all processes within the system. It is also possible to use the decimal value of the process type. The decimal value can be found by looking into the symbol file, which is also automatically generated.
The separator for process type and instance is a blank.
Instance
The value of the instance number is a decimal value beginning from 0 for the first instance of a process type. If the SDL System contains only (x, 1) declarations on SDL level, then the user has to specify "0" in any case.
If no symbol file was specified, then neither process type nor instance is checked within sdtmt! If the target is compiled without error checks, that might lead to a fatal error in the target system.
Symbols
Symbols are read in from a file called <systemname>.sym. There are a lot of error checks within the SDL Target Tester's host site which only work if a symbol file has been loaded.
Help
SDL Target Tester gives the user some quick help when entering:
helpA complete list of commands will be displayed on the screen. Commands, which are available in the current mode, are marked with an asterisk. If a command is entered which is not available in the current context the SDL Target Tester responds with:
Sorry. The current mode of sdtmt does not allow you to enter that command.The command has been ignored.To get a short explanation, type:
help <commandname>help helpTo get a complete list of commands, type:
help *Most of the commands marked with the type "Remote" can only be executed (in the target) if the flag XMK_ADD_MICRO_COMMAND is defined in the file ml_mcf.h. See Manual Scaling.
Alphabetical List of Commands
??
(None)Open a dialog with a list of all allowed commands. By pressing the OK-Button the selected command is copied to the Input line.
Active-Timer
<Processtype Instance> <Timername> <Timerparameter>Check, if a specific timer is set by a process, and has not been expired.
The input of a timer parameter is mandatory. The type of the parameter has to be an integer value. For a timer without parameter enter a 0 in the parameter dialog.
?All-Processes
(None)
This command is obsolete. Use ?Process-State * * instead.
BA
(None)This command requests to clear all the breakpoints in the break list.
BC
<breakpoint number>This command requests to clear the given breakpoint number from the breakpoint list. The breakpoint number depends on the total number of defined breakpoints.
BP
<Processtype Instance> <SignalName> <StateName>This command sets a breakpoint on the input and the state of a process. Execution is halted only if the given input in the given state is detected.
No parameter is optional. These combinations are allowed:
processname nr * statename ->Use command BPSprocessname nr signalname * ->Use command BPIprocessname nr * *processname nr signalname statenameBPI
<Processtype Instance> <SignalName>This command sets a breakpoint on the input of a given process. Execution is halted on any input of the signal in this process.
It is not mandatory to provide a parameter. These combinations are allowed:
processname nr *processname nr signalnameprocessname *processname signalnameBPS
<Processtype Instance> <StateName>This command sets a breakpoint on the state of a given process. Execution is halted if the given state is reached.
No parameter is optional. These combinations are allowed:
processname nr statenameprocessname *processname statenameprocessname nr *?Breaklist
(None)This command requests the current breaklist from the target and displays it on the screen as it was entered. If a symbol file has been specified during the invocation of sdtmt, then process IDs, signal IDs and state IDs are displayed with their symbolic value.
Change-Directory
<directoryname>The working directory of the current SDL Target Tester session is switched to <directoryname>.
Close-File
<filename>The current output/input file (including binary trace) with the name <filename> will be closed when using this command. (See Output-File and Input-File)
?Coder
(None)After invoking this command the current settings of the Target Message Coder TMCOD are display in the text area. The settings given here have to be previously made in the configuration file sdtmt.opt or have been sent by the target itself. See Preparing the Host to Target Communication.
Continue
(None)This command can be used to continue processing, i.e. after a breakpoint was h. Notification is given when the command cannot be processed within the target system.
Convert-File
<input filename> <output filename>This command converts the trace messages of the target (stored in the <input filename>) into readable ASCII trace. This ASCII trace is stored into the <output filename>.
Create
<Parent-Processtype Instance> <Child-Processtype>This command creates an SDL process of the given type
<Child-Processtype>. The creating process must be specified in <Parent-Processtype Instance>. If there is a free process instance, which is currently dormant, it will be created and the start transition will be executed. This can be seen in the trace.If the system is under a break condition, the command will be ignored as it is not possible to send signals (dynamic creation uses signal mechanism).
Please specify the <Parent-Processtype Instance> according to the SDL system. There is no check if the parent is specified correctly from the semantic point of view.
Disable-Timer
(None)This command disables the processing of timers.
The command affects the SDL timers only! However, timers which are already expired and are in the queue will be input as normal. Keep in mind that the disabling of timers changes the system behavior.
Display-Off
(None)The ASCII trace into the text area is switched off.
Display-On
(None)The ASCII trace into the text area is switched on.
Enable-Timer
(None)This command enables the processing of timers again, if it was previously disabled with the command Disable-Timer. Due to the fact that time (and so the system time) cannot be stopped, it might happen that all the timers set earlier may expire at the same time this command is entered. This may cause illegal system behavior, i.e. a queue overflow and the call of the ErrorHandler or another illegal behavior.
?Errors
<const>Query last occurred error. The target system traces the last error within the SDL execution and stores it. The result will be displayed on the screen, both as a decimal value and as ASCII text with an explanation of the error situation.
If the value <const> is not equal to zero, further information about the error is given from this manual (the on-line Help Viewer is started).
Especially, when the SDL system is executed for the first time in a new hardware environment, the command may help in finding problems. It is also useful after a long execution of the SDL system, as any error situation arising may be detected. All the errors, warnings and information, which are handled by the ErrorHandler are explained in the section User Defined Actions for System Errors - the ErrorHandler.
Exit-Single-Step
(None)The single step mode (which has been entered with Single-Step) is finished.
Get-Configuration
(None)The target responds with its configuration. Compiled features are displayed in the text area as well as the current settings (e.g. trace on/off).
Go-Forever
(None)After initializing the target (for example switching the recorder mode on) the target is started with this command. It is necessary that the target is compiled with the flag XMK_WAIT_ON_HOST.
Help
[<commandname> or *]A complete list of commands will be displayed on the screen. Commands available in the current mode of the SDL Target Tester are marked with an asterisk.
Command>help <commandname> ,to get a short explanation of one or several commands, e.g.
help helphe heA list of all commands beginning with b can be requested by typing:
help bA complete list of commands can be requested by typing:
help *Input-File
<filename>The file named <filename> is opened to get the stored trace information (binary format). This command must be used if, for example, a recorded session should be replayed. The file <filename> must contain trace information in binary format.
Line
(None)The command displays the line status of the communications interface. It can be used for checking if characters, frames and XONs / XOFFs have been received/transmitted and the kind of device that is actually connected.
?Memory
(None)If the Cmicro Memory Management is selected (the flag XMK_USE_SDL_MEM must be defined, please view Use of Memory) this command offers the advantage of checking currently allocated memory.
News
(None)The SDL Target Tester Release's news are displayed in the text area.
Next-Step
(None)This command performs one step (one transition) if single step is active. The Single-Step command must be given prior to this.
Nextstate
<Processtype Instance> <Statename>This command sets the state of the given process instance to the value of <Statename>. <Statename> must be one of the states which are defined for the corresponding process type in SDL. Normally, that only makes sense if the system is under break condition or is idle.
Output-File
<filename>All the target's trace information is stored as binary data into the file <filename>. This command can be used to store the information of a recording session in binary format.
Output-NPAR
<Receiver-Processtype Instance> <Signalname>An Output from the environment without any parameters is sent into the SDL system.
Output-PAR
<Receiver-Processtype Instance> <Signalname> <Signal Parameter>An output from the environment into the SDL system with a signal including parameters is sent into the SDL system. The
<Signal Parameter> has to be given as a buffer of hexadecimal values. See Example 619.Example 619 : Output with parameters
Output-PAR Process_A 0 Signal_1 "00-12-a3"Signal `Signal_1' is sent to the instance 0 of process type `Process_A'. `Signal_1' contains parameters with the length of three octets and the values 0x00, 0x12 and oxa3. The ordering of the parameter octets must fit into the signal's parameter structure and the target's memory layout (alignment, endian etc.).
Options-File
<filename>The options file <filename> is read in so that the message coder can be initialized. By default the options file sdtmt.opt (see Preparing the Host to Target Communication) is read in when the SDL Target Tester is started.
Page-File
<filename> <EventsPerPage>The file <filename> containing trace information (in binary format) is read in and displayed as ASCII trace in the text area. The constant decimal value <EventsPerPage> gives the amount of trace information to be displayed until the user confirms the next page.
Print-Conf
(None)This command gives all configuration information together, see the commands -?Coder and Line.
?Process-Profile
<Processtype Instance>The profiling of one process instance can be requested with this command. The result is the transition execution time of the longest transition and the last transition of the specified process instance. The flag XMK_ADD_PROFILE must be set when compiling the target executable to have access to this command in the target.
Please view the section Initialization.
?Process-State
<Processtype Instance>Query the state of the given process(es).
The amount of queried process instances can be configured:
- If you specify a valid process instance (?Process-State P1 0), the current state of this instance is printed.
- If you enter a process type and * (?Process-State P1 *) you get the states of all instances of this type.
- If you enter ?Process-State * * all possible Process instances of the system are queried.
Depending on the traffic load on the communications interface the responses may be delayed.
The results printed on the screen may be inconsistent. That depends on what the SDL system is doing during the query procedure. The results will be correct, however, if the whole SDL system is idle.
?Queue
(None)Some characteristics of the queue will be displayed. The command is very useful for determining the queue's dimensions. There is a peak hold, which shows the maximum number of entries in the queue since the system's start.
After typing the command, information is printed on the screen, which may look like:
Current Queue state:Queue size dimensioned to:Max.20 entriesPeak hold :1 entry/entriesCurrently :0 entry/entries in queueQueue memory located at :36a40010,xThe explanation for this is: a maximum of 20 entries in the queue can be handled by the system. Since system start, there was never more than one entry being used. Currently, no signal instance has been detected in any process input port. The last value displays the physical memory allocation of the queue, which helps in debugging.
Recorder-Delay
<duration>If a recorded session should be replayed it is possible to insert each environment signal with a delay of <duration> seconds. This feature can be used instead of the real-time play (Recorder-Realtime).
Recorder-Off
(None)Switches the Cmicro Recorder off. This command may be specified any time during a recording session. It can be used in order to reduce the amount of information sent via the communication interface.
Recorder-On
(None)Switch Cmicro Recorder to record mode. It is not a good idea to enter this command when the SDL system is not idle. (Furthermore, the question is, whether it makes sense to start a record session in the middle of an SDL execution or from the start-up of the SDL system.) It may not be relevant to start a recording session after the system has started.
The SDL Target Tester's Record and Play functions are only available if a Cmicro Recorder license is available.
Recorder-Play
(None)The Cmicro Recorder's play mode will be set. This command can be entered in a few states of the Cmicro Kernel only. Notification is given if necessary. The same explanation as for Recorder-on apply.
The SDL Target Tester's Record and Play functions are only available if a Cmicro Recorder license is available.
Recorder-Realtime
(None)The play mode of the SDL Target Tester is started as real-time play. It is necessary to compile the target with signals including time stamps.
The SDL Target Tester's host sends all environment signals with the recorded time stamp into the target while replaying. Without using this command all signals are inserted with time 0 which leads to an immediate execution in the target.
Reinitialize
(None)This command tries to reinitialize the system. The reinitialization may fail, if the hardware drivers cannot be reinitialized again. Furthermore, all global auto variables in the user's C program parts cannot be reinitialized. However, if there is a clean implementation of driver initialization and de-initialization, and initialization of global variables, the command will work well.
Remove-All-Signals
<Processtype Instance>Remove all signals of the given receiver from the signal queue.
Remove-Command
(None)For each command, which is sent to the target, the host waits for an explicit acknowledgment. The last command can be removed, so that the host does not wait for that acknowledgment. That can be used when the communication is hanging for any reason, for example, when the command could not be sent to the target, or was not received by the target, or the acknowledgment could not be received by the host.
Remove-Queue
(None)All signal instances in the queue will be removed. The signal queue will be empty.
Remove-Signal
<Processtype Instance> <Signalname>Remove a specific signal of the given receiver from the queue.
E.g. when a breakpoint is hit the signal which led to the current transition still remains in the signal queue. This means the first signal in the queue cannot be removed.
Reset-All-Timers
<Processtype Instance>This command resets all SDL timers of the given process instance.
Reset-Timer
<Processtype> <Instance> <Timername> <Timerparameter>This command resets a specific SDL timer of the given process instance and with a specific timer value.
The input of a timer parameter is mandatory. The type of the parameter has to be an integer value. For a timer without parameter enter a 0 in the parameter dialog.
Resume
(None)Resume Cmicro Kernel, after a suspend has been accepted. The same explanations as for the Suspend command apply.
Run-Cmd-Log
<filename>The initialization commands in the log file <filename> will be executed.
Scale-Timers
<factor>Scale time when setting a timer.
Often there is a need to simulate time during an SDL execution. By specifying this command, it is possible to make SDL timers run faster or slower. The command is applied on newly set timers only, i.e. if a timer is already running then it remains unaffected from the time scale. Due to this fact, the command should only be given at the start of the SDL system.
In record mode the scaled time will be stored. This results in time being scaled in play mode. It is impossible to scale time manually in play mode!
Set-Timer
<Processtype Instance> <Time value> <Timername> <Timerparameter>Set an SDL Timer for the given process instance with the given time value in units. The time value is a float value re-calculated to the target's timer ticks. Please view UNIT-NAME, UNIT-SCALE.
.
The input of a timer parameter is mandatory. The type of the parameter has to be an integer value. For a timer without parameter enter a 0 in the parameter dialog.
Example 621 Setting a timer without parameters
set <Processtype> <Instance> 4711 < timername> 0set <Processtype> <Instance> 1.456 <timername> 0Shutdown
(None)The command tries to shutdown the system, which means normally to exit the main program. The user can define the actions on exit within the target. The same explanations as for the reinitialization command apply.
Single-Step
(None)This command switches the single step mode on. Either Next-Step or Continue may follow.
Start-Cmd-Log
<filename>All the initialization commands will be written to the log file <filename>. Please view the command Run-Cmd-Log, too.
Start-Gateway
(None)This command is used to start the communication in the default implementation of the sdtgate or a host simulation.
Start-MSC-Log
<level> <"Diagramname">The MSC Editor is started and the target's trace messages will be displayed in the MSC Editor. The <level> specifies the amount of MSC symbols:
- 0 - Basic Message Sequence Chart
- 1 - like level 0 but with the trace of states
- 2 - like level 1 plus the trace of actions
- 4 - Basic Message Sequence Chart to file
- 5 - like level 0 but with the trace of states to file
- 6 - like level 1 plus the trace of actions to file
Start-SDLE-Trace
<Processtype> or*The trace on SDL symbol level is started for the specified process. The Organizer has to be running and the target needs to be compiled with the flag XMK_ADD_SDLE_TRACE (see Trace).
Start-Trace-Log
<filename>A log file containing the whole ASCII trace of the SDL Target Tester will be written.
Stop
<Processtype Instance>This command stops an SDL Process according to the SDL semantics, no matter if the system is suspended or under break condition. The command is, after it is received, directly executed within the target. All signals which are in the queue for this process are removed, including create signals.
Stop-Cmd-Log
<None>The write of initialization commands will be stopped. Please view the command Run-Cmd-Log, too.
Stop-Gateway
(None)This command is used to stop the XON communication in the default implementation of the sdtgate.
Stop-MSC-Log
(None)The trace on the MSC Editor is stopped.
Stop-SDLE-Trace
<None>The trace on SDL symbol level is stopped.
Stop-Trace-Log
<None>The trace to the trace log file is stopped. The file is closed.
Suspend
(None)Disables the Cmicro Kernel from scheduling. The transition currently running will not be affected and will be ended first, before the command is accepted. The suspended SDL system cannot process any signals, neither internal signals nor signals coming from the environment. This may lead to a queue overflow. It is recommended to disable the timers to prevent this.
System
<systemname>.symThe automatically generated symbol file <systemname>.sym is loaded. The symbolic names for process types and Signal IDs can only be used if this file is read in.
Additional error checks can be performed within the SDL Target Tester's host if this file is read in.
?Timer-Table
(None)Some characteristics of the current timer tables are displayed. The command is useful in order to inspect the state of the SDL system, or to see if it is hanging.
After typing the command, information is printed on screen which may look like:
Current Timer states:SDL NOW :9147,dTimer dimensioned to :6Currently :0 timer(s) activeTimer memory location at :36bf0014,Where SDL NOW represents the amount of units since system start. The value of 6 shows the maximum number of timer instances in the system. The third line is self explanatory. The last line gives the physical memory allocation of the timer linked lists which may ease debugging.
Tr-Detail
<level>Define Trace detail. The command is applied locally within the SDL Target Tester's host and it works on ASCII traces to the text area only.
Output to either a file or to the MSC Editor will not be affected by this command. Thus if the target is configured correctly no inconsistency can occur and no information stored in a file or in the MSC Editor will be incomplete.
Five levels are defined (0-5). The higher the level, the more SDL events are traced. Different events are assigned the levels depicted in the following table:
Tr-Params
<const>The trace of signal parameters can be switched on or off. This command has an influence on the display in the text area only.
- 0 - to switch trace off or
- 1 - to switch the trace of signal parameters on
Tr-Process
<Processtype Instance> <Bitmask> orENV <Bitmask> or* <Bitmask>This command defines which processes in the system are traced. It is applied in the target (remote command), so that the traffic load on the communications interface can be reduced interactively.
This trace command works for all instances of the given process type. No differentiation is possible between different instances of one type.
Tr-Signal
<signalname> <flag>This command defines the trace for one or all signals in the system. It is applied in the target (remote command), so that the communications interface's traffic load can be reduced interactively.
The signal name is the one from the SDL system. No qualifiers are possible, which means, that signal names have to be unique for the whole SDL system. The flag may be 0 (trace off) or any other value (trace on). If an asterisk is specified for signal name, then flag is applied to all signal types. The command works for SDL output only.
Tr-Off
(None)The command switches the SDL Target Tester's tracer off within the target. The current option settings stored in the target will not be affected. After this command is received within the target, the trace is immediately suspended and can only be resumed with the command Tr-On. The output trace that has been written is interrupted.
The user has to consider misinterpretation of the trace because of missing traces after resuming the trace via Tr-On.
Tr-On
(None)This command switches the Cmicro Tracer on, if it is compiled within the target. None of the current option settings concerning trace within the target will be affected.
Unit-Name
<unitname>The timer unit's name can be assigned with this command, e.g. if the target's system time is `milliseconds' and the Unit-Scale is dimensioned to 1000, the <unit> should be named as `sec'.
Unit-Scale
(realvalue)The target's system time, which is received with the trace data, is multiplied by this constant factor to get a "readable" system time. See Unit-Name too.
http://www.ibm.com/rational |
![]() |
![]() |
![]() |
![]() |