S T R U C T O R I Z E R - User Guide
Features > Executor

Preliminary Remarks

The executor is that part of Structorizer that tries to interpret and execute a diagram. It is available e.g. via the "Debug" menu:

Debug menu with the Executor item selected

Please note, that Nassi-Shneiderman (NS) diagrams are designed to be free of any syntax. That means you may put arbitrary descriptive text into the elements. It depends on the level of detail, of course, how much sense that makes. Often it is more practical to use more formal notations like pseudo code or even more or less commonly accepted programming language constructs.

In order to "execute" an NS diagram, however, you have to stick to some kind of syntax. For the same reason, not all diagrams nor all contained structures can be interpreted. The executor has been added to allow beginners to easily catch and understand control structures and execution flows. Over the time, however, several enhancements and accomplishments have made it a lot mightier than originally planned. You find an overview of the executible dialect used in Structorizer on the Syntax page of this user guide.

Overview of the remaining subsections of this manual page:

Launching Executor

To launch the executor, you may use the menu item "Debug => Executor ..." (see above) or click on the following toolbar icon: . This will pop up the Executor Control panel (the functions of which will be described in section "Executor Control" further below):

Executor Control dialog

If your algorithm contains Turtleizer-specific subroutines, however, then you must click on the Turtle icon in the toolbar or select the menu item "Debug => Turtleizer ..." instead (unless the Turtleizer window is already open): Icon Turtle.

Note: You cannot close the control panel by the operating-system-typical close button (e.g. the top-right red 'X' in Windows, see image above, or the red traffic-light button in OS-X) while an execution is running or pending.From release 3.27 on, you will be warned if you try.

The control panel will automatically close on execution termination (unless Run Data Tracking is active), thus also on pressing the Stop button button. You may iconize the control panel in the usual way, though.

Executor Control

When having pressed one of the buttons or Icon Turtle, the Executor Control panel will pop up (see the figure near the top of this page). Here its details will be described.

"Player" buttons

The most important controls are the four "player" buttons in the fourth row, having the following effect (from left to right):

  • Stop button (Stop): Aborts execution immediately and closes the control window (unless Run Data Tracking is active), all execution status will be lost (tracked run data will survive, though).
  • Run button (Run): Starts or resumes execution with the current instruction, running with the delay set via the slider in the first row.
  • Pause button (Pause): Interrupts execution but retains current execution status such that, after some inspection and interaction, execution may be resumed.
  • Step button (Step): Just executes the current instruction and then automatically pauses before the next instruction or the end of the algorithm.

When having started with button "Run", the execution will terminate in one of the following cases:

  1. The last instruction of the algorithm is reached and has been executed.
  2. A Jump element with an exit instruction has been executed.
  3. A Jump element with a return instruction has been executed and the currently executed diagram is at top level.
  4. The Stop button has been pressed.
  5. A syntax or execution error has occurred.

The execution will pause (i.e. may be resumed) on one of the following events:

  1. Execution was carried out with the Step button.
  2. The Pause or Step button was pressed during execution.
  3. A breakpoint (see below) is reached.
  4. An input instruction is executed and the user pressed the "Cancel" button in the popped-up input dialog.
  5. An output instruction is executed (unless output mode is "output to window") and the user pressed the "Pause" button in the popped-up display dialog.

Some activities (like Call Stack display) are only enabled in paused state.

You resume execution via the Run or Step button.

Execution delay

Delay control

With the slider in the top row you may control the execution delay between the instructions (for better observation). Whereas the mouse handling is rather rough, you may use cursor keys (left / right) for fine-tuning the delay value by steps of 1 while the slider is selected. If you reduce the delay to 0 then some displayed information (like variable values, execution counts etc.) will not be updated unless you press the "Pause" button or the algorithm reaches the paused state due to one of the other events described above.

Output mode

Output control

The second row provides a checkbox "Output to window" allowing you to specify how output instructions are presented: If the checkbox is not selected then output instructions will pop up a message box showing the output value and having to be quit each time in order to resume, otherwise a console-like text window (see section "Output Console Window" below) will permanently be open into which all output will be written without pausing or waiting. Since the output is always logged to that console window (even while it is not visible), it is even possible to inspect the entire output history of the program execution by selecting the checkbox after having executed the algorithm in the traditional mode (checkbox not selected). You may possibly have to open the Executor Control again to do so, because it usually closes after execution has terminated and closes the Console window. Some examples are given in the section "Output Console Window" further below.

Run data tracking control

Run Data Tracking control

The third row provides a checkbox and a visualisation mode choicelist for Run Data Tracking. The checkbox on the left-hand side enables the tracking mode, the choicelist modifies the kind of element highlighting in dependency of the purpose of the analysis. The controls are partially disabled while execution is ongoing. See the Run Data Tracking page for details.

Call stack display

CallStack control

The fifth row shows you the current subroutine call level on the right-hand side: Every Call instruction, which the execution dived into, increments the subroutine level by one, on returning from a called subroutine (and thus leaving the pending Call element) the subroutine level is decremented. The top level (program level) is 0. Note that built-in functions or procedures do not affect the displayed subroutine level; only called Nassi-Shneiderman diagrams have an impact. In paused execution state, a click on the "Call Stack" button will pop up a scrollable list view showing the current content of the Call Stack (see section "Call Stack" below).

Variable display

Variable display with pulldown buttons

The lower region of the control panel is occupied by the variable display. As soon as a new variable is introduced, a new line will be added with the variable name in the left column and a string representation of its current value in the right column. In lines with a composed value (i.e. an array or record) the central column will show a pulldown button.

By the way: These are the three (and a half) ways to introduce a variable in Structorizer (the variables are named id1 through id5 in the examples):

  1. as parameter of the (currently executed) subroutine, e.g.: function(id1, id2)
  2. as target of an assignment instruction, e.g.: id3 <- expression
  3. as target of an input instruction, e.g.: INPUT id4
  4. by means of a declaration, e.g.: var id5: integer
    (Note that a mere declaration without assignment leaves a variable in an uninitialized state.)

Whenever execution pauses (see above), you may double-click into a field in the right column of the variable display and edit the value for testing purposes or have a look at the farther-right elements of a large array exceeding the column width. (The value of a displayed constant may not be edited, though. Constant values are indicated by a pink table cell background.)

You may inspect or change structured values by pressing the associated pulldown button in the central column. This will open a table view similar to the variable display, allowing to inspect (and possiby modify) the content in a structured way:

Value editor for structured types      Value editor for a record variable in read-only mode

The value inspection works recursively into nested data structures. The respective title string reflects the access path:

Recursive inspection of nested data

If the inspected value was a constant then you will not be able to apply changes, the icon will be a magnifying glass instead of a pencil, and there is only an "OK" button instead of a "Discard" and a "Commit"/"OK" button.

When you resume the execution, the algorithm will continue with the modified value(s). Note that the Start and Step buttons will be locked until you finish or discard editing (by <Enter> or <Esc> or by clicking elsewhere).

Animation

The currently executed or paused instruction is highlighted in light orange background. Compound elements with pending execution, i.e. nested components of which being currently executed (or paused), are highlighted in a faint yellowish tinge. So you may easily follow the execution progress (see image in next section).

Within Parallel elements, those parts of the threads that have already been passed are also marked with the yellowish tinge; because of the randomly leaping execution you would otherwise hardly be able to tell how far the different threads may have proceeded.

Additionally, in Run Data Tracking mode, elements already passed by one of a series of performed test executions can be highlighted in bright green to visualize test coverage. Alternatively, elements may be highlighted in a spectral colour range depending on their relative execution count or the number of involved "atomic" operations. This colouring is lower prioritized than the above mentioned highlighting for the current execution status (currently executed element and structured elements with pending execution completion).

The speed of the animation is controlled by the delay slider in a range between 0 and 2000. The default is 50.

Breakpoints

You may place breakpoints on as many elements of your diagram as you like. Execution will pause as soon as an element with breakpoint is reached (for possible actions in paused state see above).

To set or remove a breakpoint select the respective element and now either right-click and select/unselect menu item "Breakpoint icon (in menus etc.) Toggle breakpoint" in either the "Debug" or context menu or double-click and select/unselect the checkbox "Breakpoint" at the bottom of the element editor. Alternatively, you may press accelerator key <Ctrl><Shift><B>.

Debug menu with active element-related items

In the diagram, a breakpoint is shown as a horizontal red bar at the top of the element frame (except for Repeat loops, where the red bar will appear between loop body and exit condition, sensibly):

Diagram stopped at a breakpoint

If you place a breakpoint on a loop (For, While, Repeat) then the execution will pause every time the loop condition is going to be checked again.

Note that you can't place a breakpoint on an Endless loop (since it hasn't got any means of control). You may place a breakpoint on the first element of its body instead.

While Run Data Tracking mode is active you can also make use of conditioned breakpoints: You may specify an execution count value that is to trigger the breakpoint on going to be reached. That means while the element hasn't been executed as often as specified, the breakpoint will be passed as if it weren't there. Only when the current execution count (on entering the element) exactly equals the specified trigger value minus one (such that it would draw level with it on completion), the breakpoint will go off. Conditioned breakpoints are shown as a dotted red line, and their trigger value will - coloured in red - precede the run data numbers as shown in the T(RUE)-branch in the folowing screenshot (where the return statement just triggered it):

Element with conditioned breakpoint just triggered

A trigger value of 0 specifies an unconditioned breakpoint as described before.

Since a conditioned breakpoint won't fire again after the (non-zero) trigger count has been exceeded, you are allowed to modify the trigger value whenever the execution is paused. To do so for a selected element you may use the menu item "Specify break trigger..." in menu "Debug" or in the context menu, or just enter the key combination <Ctrl><Alt><B>:

Context menu item for breakpont trigger control

Wenn you toggle off the breakpoint then its trigger value won't get lost but is preserved for later re-activation.

To eliminate the breakpoints all over a diagram at once press the speed button Icon of the toolbar button to clear all breakpoints in the toolbar or the respective menu item "Clear breakpoints" in the "Debug" menu.

Note: Breakpoints are not saved to file. Nor are setting, modifying, or removing a breakoint actions inducing an entry in the undo or redo stack. However, any undoable (substantial) change to a diagram will be associated with a snapshot of all currently set breakpoints, such that on undoing a previous diagram modification the former breakpoint status would be restored. The same holds on redoing undone modifications.

Output Console Window

As mentioned in section Executor Control above, you will open a text window logging all done output and input if you select the "Output to window" checkbox. While unchecked, the window is just hidden but still exists and gathers the texts printed during execution in the background.

The new output text window for Executor

On starting execution, any previous content is deleted, an automatically generated line names the executed program (or top-level routine) and shows the starting time. Conversely, on terminating an execution a similar line with the termination time will be displayed (see image above).

There is no way to input or edit something in the logging window. Input instructions will always be carried out via an interactive question box, but both the automatically generated prompt text and the input will be reflected here (the former in yellow colour, the latter as green text for better distinction). The regular output produced by the algorithm output instructions is shown in white colour. Every output instruction induces a new line:

Output Console with input prompts and input

With checkbox "Output to window" not being selected, the window will just stay hidden while output instructions will pop up message boxes in the traditional way. With "Output to window" selected, you actually suppress the output message boxes and bring the logging window to display. With an algorithm generating a lot of output, this mode will significantly accelerate the execution and relieve you from the necessity to confirm every single output.

You may change the output option at any time during or after an execution without losing the window content. It can be reactivated by unselecting and re-selecting the "Output to window" checkbox.

Closing the output window will not destroy its content.

The font of the output window may be changed by menu, via the + and - keys of the number pad in combination with the <Ctrl> key, or - from version 3.28-01 on - via the mouse wheel with the <Ctrl> key being pressed:

Properties menu on the outpout console

Execution errors will also be logged in red colour to the output text window after having popped up as error message box. See an example in section "Custom subroutines" above.

Call Stack

As mentioned in section Executor Control above, you may display the call stack (makes only sense with diagrams containing - possibly nested - CALLs, of course). The Call Stack window is opened by clicking the button "Call Stack". To show a Call Stack requires a begun execution (of a diagram contaning CALL elements) being currently paused (e.g. by pause button or breakpoint or in step mode).

The top line always represents the innermost call (i.e. the currently executed subroutine call), the bottom line (level 0) stands for the main program or routine initially started. Some examples for call stack views are shown below:

Displayed Call stack for a QuickSort solution 

Scrollbars are automatically added when required, e.g.:

Call stack view with vertical scrollbar

Wide Call stack display with horizontal scroll bar