The schema editor is used to define the external interface and some other attributes of an action block (both elementary and compound actions). It is found on the "Schema" tab after selecting either an elementary or a compound action in the navigation tree.
The block's interface consists of the input and output pins and its trigger behavior. The editor shows a box representation of the action, where inputs are located on the left, outputs on the right. This is the "outside view" of the action; i.e. the action's look when placed as a step in a diagram.
To the right, you see an example for the interface of a action with a single input pin (in) and a single output pin (out). In a network, a step with this action will trigger when all connected input pins have received a value ("AndConnected" trigger condition).
Schema editors can also be invoked on actions that are write protected, e.g. actions from imported libraries, such as the standard library or your own block libraries. Such components cannot be modified, but they can however be shown and inspected by the editor.
- 1 Pins
- 1.1 Adding & Removing Pins
- 1.2 Special Pins
- 1.3 Renaming of Pins
- 1.4 Edit Functions for Existing Pins
- 1.5 Setup / Change Datatype
- 1.6 Default Values for Pins
- 1.7 Pin Specific Options (Context Menu)
- 2 Action
- 3 Declaring Semantic Attributes
- 4 Execution Debugging Attributes
- 5 Adding Pre- and Post Actions
- 6 Advanced and Expert Settings
- 7 Keyboard Shortcuts
Adding & Removing Pins
New input and output pins can be added using the icon buttons in the top corners of each side of the action's representation box ( / ). Existing inputs and outputs can be removed using the icon buttons directly beside the buttons for adding (), but a pin has to be selected for this operation first. Please note that some builtin blocks, like shell command blocks, have a fixed set of pins which can not be removed.
When new pins are added, they get default names attached with a sequential number, like in1, in2, out1, out2, etc.
Some actions (i.e. script and bridged execution actions) support additional special pins, with a predefined (and hardcoded) functionality. For script actions, these are used to provide the execution directory, environment variables, standard input, exitCode handling and output line buffering options. For bridged actions, these provide the bridge connection handle and/or script interpreter handle on which the script is to be executed.
Special pins are added with the "Special Pins" menu, and removed by selecting the pin and deleting it (via key or menu).
Renaming of Pins
The name of a pin can be changed (*) by clicking on the name field, which then turns into an input text field. There, type in a new name for the pin. The pin will be renamed when either the Enter key is pressed, or the input field is left (i.e. clicking on any other element in the editor). The Escape key cancels the rename operation.
(*): except for special pins; these cannot be renamed.
Restrictions on Pin Naming for Elementary Blocks
In practice, the identifier should be a sequence of letters, digits or the underline character (_), where the very first character should not be a digit. It may also not be a keyword of the language (i.e. "
function" in Groovy, "
self" in Smalltalk). Such restrictions do not apply to compound blocks (however, if you ever plan to convert or generate elementary code, it is a good idea to restrict your naming there too).
The syntax of those two languages contains a much larger number of language keywords, which cannot be used as identifier. For example, "
for" and "
in" are all reserved words in those languages and cannot be used. Otherwise, a syntax error will be reported when code is entered.
It is a good practice to name pins as "inPin1" or "textPin" or "xxxPin" in general, to avoid such conflicts right from the beginning. Such naming convention also make the code more readable, as it reduces chances for confusing the name of a pin with a name of a variable used for a pin's data value (remember: in the code, the pin-name refers to the pin - not the pin's value).
Edit Functions for Existing Pins
For all other pin operations, the pin to be modified has to be selected first. To select a pin, click on it with the left mouse button. You can select multiple pins: keep the Ctrl key down while clicking, to toggle the pin into or out of the selection. Press the Shift-key while clicking to select all pins in between the previously selected pin and the clicked-on pin. The selected pin(s) will appear highlighted in a red color.
To open the context menu for a pin or group of pins, first select the pin(s), then press the right mouse button. The context menu provides additional pin related functions. Since input and output pins have slightly different properties, their context menus are different and described below.
Setup / Change Datatype
Each pin has a data type attribute that determines which kind of data is expected or generated by the pin. Every new pin initially gets the data type that was last used; initially the data type "Any" is assigned by default. This type is also used as default, whenever no other reasonable data type can be predicted. The pin's data type is displayed beside the pin, outside of the representation box. The data type for a pin can be changed in the context menu, through its "datatype" sub-menu, which brings up a list of available types. Note that when you have already placed step instances of the modified action block in any activity diagram, a change in the data type of a pin may affect existing connections in which the pin is involved. If the new type is incompatible with a connection, it is drawn as dotted line in the diagram, or when a preset value becomes incompatible, the value is displayed in a red color.
Default Values for Pins
Default values for unconnected step-pins can be defined here, by "freezing" a pin in this schema editor. Both constant-value and environment-freeze values are possible.
Pin Specific Options (Context Menu)
- Undo last change(s). The text shown after the word "Undo" (in parentheses) is the name of operation that will be undone.
- Copy Pin
- Copy all attributes from selected pin.
- Remove Pin
- This option simply removes the selected pin.
- This option is used to specify the data type of the selected pin. This brings up a list of the available data types.
- Default Value Editor
- This option allows you to specify the editor type for the freeze value, e.g. strings can be entered single line, multi-line or as a password string.
- Show Datatype
- This option opens a view which shows the pins data type. Note that you can not change the datatype in this view.
- Default Value As
- This option allows, for most standard data types, presetting the input value according to the data type, by typing a valid value into a text input field. The identifier of the data type in the menu entry differs depending on the data type of the pin. A freeze value defined in this schema defines the input value of unconnected step-pins. It will only be in effect, if the action is placed as a step and the corresponding step-pin is not connected or frozen.
- Default Value from Clipboard
- Freeze pin with the data stored in the clipboard.
- Default Value from Environment Variable
- This option causes a dialog to open up, allowing specifying the environment variable's name in a text input field. For more information see: Environment Freeze Value. This freeze value is only effective for unconnected step pins (read description above).
- Delete Default Value
- This option is only available if the selected pin is frozen to a value or to an environment variable. No matter if the pin was preset with a direct value or with an environment variable, the preset information will be lost.
- Parameter (Non Consuming;Non Triggering)
- This option determines whether the select input pin is a parameter pin. For more information see: Diagram Elements.
- Telegram (Non Consuming;Non Triggering;Deliver While Executing)
- This option determines whether the selected input pin is a telegram pin. For more Information see: Telegram Pin.
- This option sets the buffering mode of the selected output pin to on or off. For more information see: Diagram Elements - Output Pin
- Special Attributs
- A submenu offering additional functions (see below)
- This option causes a text editor to open on the pin's comment. That comment will be displayed as a tooltip of the selected pin.
- Move Up/Down
- With those options you can change the sequence of the pins.
The input pin behavior can be controlled in more detail here. Individual control of the triggering/non-triggering, consuming/non-consuming and buffered/passed-through attributes is offered here.
- Consuming / Non-Consuming
- This option determines whether the input pin consumes its input value from the input basket or leaves it. Non-consuming pins are sometimes required, when the step is executed in a loop, and the input value should be reused for each iteration. Also, frozen parameter pins should be defined as non-consuming, as otherwise, the freeze value is only available once (in the first loop iteration). More info in: Diagram Elements.
- Triggering / Non Triggering
- This option determines whether the input pin is considered in the action triggering process or not. Triggering pins must have a value present in order for an activity to be created. Non-triggering pins are not. More info in: Diagram Elements.
- Mailbox / Non-Mailbox (also called "Telegram Pin")
- This option determines whether the selected pin is a telegram pin. For more Information see: Telegram Pin | Diagram Elements - Telegram Pin.
The last input- and output pin can be specified as "variable-number-of-pins". Such a pin appears as a single pin in the block's description (the schema), but may be instantiated as a step with multiple pins. In other words, the number of pins can be determined individually for each step.
- Variable Number of Pins in Steps
- This option sets the "Variable Number" attribute for the last pin. If checked, the number of pins can be changed in the step, and the last schema pin can be "replicated" an arbitrary number of times. This option is only possible for elementary actions, and the elementary code must be written to access this pin pin with a pin index. See also in Diagram Elements - Variable Number of Pins.
- Variable Number of Remaining Pins in Steps
- This is a new feature of the 2.8 version of expecco. Similar to the above "Variable Number" of the last pin, this defines a group of pins to be possible repeated in the step. If checked, the number of pins can be changed in multiples of the group size in the step, and the N-last schema pins can be "replicated" an arbitrary number of times. This option is only possible for elementary actions, and the elementary code must be written to access this pin pin with a pin index. See also in Diagram Elements - Variable Number of Pins.
To open the context menu for an action, select the box representation of the action, then press the right mouse button. The context menu supports the following functions.
Changing Triggering Conditions
The triggering condition of an action block defines which input pins must have received data on order for a new activity to be triggered and started. The so called "triggering condition" can be:
- AndConnected (Default)
- All connected input pins which are "triggering" must have received data - unconnected pins are ignored.
- All triggering input pins must have received data.
- At least one triggering input pin must have received data.
The most common trigger condition is 'AndConnected'. The 'Or' condition allows for a step to be activated whenever any input arrives on any of its pins. It is especially useful to handle events or input data coming from different sources (i.e. a demultiplexer action).
You can also change the triggering conditions by a left click on the trigger-condition field (located at the top left of the block) and select one of the conditions.
New in the 2.8 version of expecco: The default triggering condition for new compound action blocks is "And", and "AndConnected" for all other (elementary) actions. It used to be "AndConnected" for all action blocks in previous versions.
Renaming of Actions
An action can be renamed either using the context menu option or rename the action in the project menu. The name of the action in project tree and the Scheme editor are identical.
The rename of an action will also rename all already placed step instances of this action containing the previous (original) action name. If a step was renamed itself, the step will keep its name.
Action Specific Options (Context Menu)
- Undo last change(s).
- Open an inplace editor within the headline of the representing box for the action. Initially the current name of the action is selected and the editor will replace the current name with the new name. On lost focus (enter, cursor down, mouse click) the changes will be saved. Cancel editing without saving the changes can be done by pressing the "ESC" key.
- Copy Pin Interface
- Copy all pins (input/output) with all attributes
- Paste Pin Interface
- Paste a previous copied pin interface
- Paste Pin
- Paste a previous copied single pin (see pin context menu)
- Trigger Condition
- see Changing Triggering Conditions
- Role in Load and Performance Tests
- These settings are also not yet used. They are only effective for load and performance tests, which are not yet officially released.
- Semantic Attributes
- see Declaring Semantic Attributes below
- Execution Debugging Attributes
- see Execution Debugging Attributes below
- Open an editor to define the background and frame color besides the tag and name settings for this action.
Declaring Semantic Attributes
The block's pop up menu also allows for a number of semantic attributes to be defined for the action. Except for the "Blocking" attribute, these are only relevant for the error checker and the code generator, which is not yet officially released in pre-3.0 versions. When set, these flags allow for the error checker to make more specific tests and the code generator / executor to optimize the execution speed of the action.
Currently, semantic attributes are:
- Blocking (Immediately Start new Activity Process)
- Tells the executor, that this action may block for a noticeable time, by reading from an external stream (typically a socket), or by opening a user-dialog, or by waiting for some other external event. By default, the executor will wait for some grace period and then start another execution thread to continue processing other action blocks. However, this grace period may be too long (a few seconds, by default) and the overall execution time may be shortened, if this is done immediately. Of course, this only makes sense if it is known in advance, that this action will block the executor, and that there might be other activities to be executed in parallel.
Notice also, that this flag can also be set for individual steps - and it is usually a better place to set this flag.
- Operator Required
- Informational flag that the action needs operator assistance. Please set this flag if a containing action opens a UI dialog, or otherwise needs an operator assistance. This will help to identify test cases which can be run without operator assistance. You can find blocks with inconsistent "Operator required" setting in the "Special" test suite search. If the "Operator Needed" Flag missing option is enabled all those blocks will be listed. The operator required flag can be validated against a test case's "Operator Required" flag, which is actually used by QM systems to effectively schedule tests which require human personal.
- Hint for the code generator, and the execution engine, that the action's code is purely functional. This means, that the output value(s) only depend(s) on the input value(s), and that neither the input values themselves nor any other global data is modified by any side effect. Purely functional blocks can be executed in parallel without a need for synchronization.
- Modifies an Input Object (Side Effect)
- Hint for the code generator and executor, that the action's code is modifying any of its input values. This means basically, that probably no other step which possibly uses this value should execute concurrently.
- Modifies an Object or External State (Side Effect)
- Hint for the code generator and executor, that the action's code is modifying any object. This means basically, that probably no other step at all should execute concurrently.
- Writes all Output(s) exactly Once
- Hint for the code generator, that the elementary code writes all of the output pins, but only once. This allows for the code generator to eliminate any data queues along the output connections, and pass these values to follow up action code as a function call; effectively allowing for faster execution.
- Writes any Output exactly Once
- Hint for the code generator, that the elementary code writes any of the output pins, but only once. This also allows for the code generator to generate shorter, more efficient code.
- May write an Output more than Once
- Hint for the code generator, that the elementary code may write any of the output pins more than once. The code generator will create data queues for the output pins. Also, the error checker makes use of this flag, when looking for input values being consumed in a loop or consumed multiple times even if only written once.
Notice: these flags may only be set if you are absolutely sure about what you do and how the elementary code behaves. In a future version, a more advanced code analysis might be added, which may make these flag settings obsolete. If in doubt, leave these flags unchanged (the worst thing that happens in this case, is that any generated elementary code executes slightly slower, and that the error checker finds less errors).
Execution Debugging Attributes
The debug menu allows for both breakpoints to be added/removed on the block (i.e. any step which resulted from placing this block into a network), and to define additional debug checks:
- Assert Executed
- Adds a check to the executor, that any step of this kind must be executed if present inside a compound action's diagram.
If a compound action which has such a step in its activity diagram, finishes execution and that step was not executed, an error is reported. Use this, to ensure that verifying actions which are placed into a diagram are certain to be executed (i.e. not skipped due to missing data)
- Assert Any Output Written
- Adds a check to the executor, that steps of this kind must generate a datum on at least one of its output pins.
If a compound action which has such a step in its activity diagram, finishes execution and that step did not generate at least one output value, an error is reported.
- Assert All Outputs Written
- Adds a check to the executor, that steps of this kind must generate a datum on every of its output pins.
If a compound action which has such a step in its activity diagram, finishes execution and that step did not generate output values for every output pin, an error is reported.
Notice that these flags can also be set on a per-step basis. The settings here will be ored with the flag settings of individual steps. (i.e. the check will be done if either the block, OR the individual step has the flag set.
Adding Pre- and Post Actions
Compound blocks can have pre- and post-actions. The pre-action block will be executed each time the owning block is triggered; the post execution block is executed after the owning block is finished, but not if a pre-action was present and that pre-action failed. This can be useful e.g. to allocate and/or release resources. To add a pre- or post-action, drag and drop any action from the navigation tree into the corresponding field at the bottom. Please note that these blocks cannot not have input pins.
Advanced and Expert Settings
Defining the Implemented Interface
A virtual action defines the interface (number of pins and their datatypes) of an action, but not its implementation. They can be placed into a network like any other action.
At execution time, a real (concrete) action must be provided for it, either explicitly, via a performer input pin, or implicit, via an imported library which contains a concrete action which implements that virtual action. The "Interface" field at the bottom of the editor assigns such an interface to a concrete action, and specifies that the edited action is able to play that virtual action's role.
Add / Remove / Test Action User Interface (Action-UI)
You can specify a graphical user interface (UI) for an action. If defined, that UI will be displayed as long as the action is executed during a test run. The action can communicate with the UI using environment variables. The environment variables will be created by the UI Editor during creation / editing the UI.
- Ctrl-i - "New InputPin".
Adds a new input pin - same as clicking on the "Add Input Pin" button.
- Ctrl-o - "New OutputPin".
Adds a new output pin - same as clicking on the "Add Output Pin" button.
- Ctrl-n - "New Pin".
Adds a new input or output pin, depending on the currently selected pin's type.
- Ctrl-e - "Environment".
Adds an environment-freeze (the value is read from a variable, if unconnected)
- Ctrl-p - "Parameter".
Toggles the "is parameter pin" attribute of the pin