Language Reference


Graphical Function Chart Elements


Step

 

A step represents a state of the application. The step can be active or inactive. An active step is indicated by a token. The step has one input port and one output port. The input port can be connected to transitions, exception transitions, and parallel split objects. The output port can be connected to transitions and parallel join objects. Step actions are shown in the action block associated with the step. The action block can be hidden (default) or shown.

A step may have a name. By default the step has no name. The user can give the step a name by clicking on the (invisible) name text-edit field to the left of the step. Steps names are needed in references to the .s and .t attributes of the step.

Changes to the step actions will not take effect until the next time the step is compiled.

Menu Choices:

Shows the action block of the step.
Hides the action block of the step.
Brings up a text-editor window in which the user can enter and edit step actions. The editor supports cut, copy, and paste using the normal keyboard commands. Individual actions should be separated by a semi-colon. The editor can also be brought up by clicking on the action text in the action block. If the step contains actions, the action text is shown as a tool-tip text when the action block is hidden.

Text Methods:


Initial Step


The  initial step  is an ordinary step that is automatically  activated when the application is started. Initial steps may be located on top-level workspaces or within workspace objects. Initial steps within macro steps will currently not be initialised properly.

Initial steps have the same menu choices and text methods as ordinary steps.


Transition


A transition represents a condition for changing from one state to another state. The transition is enabled when all the steps connected to the input port (either directly or through a parallel join object) are active. The transition  fires if it is enabled and its associated condition is true. When the transition fires it deactivates all the steps connected at the input port and activates all the steps connected at the output port (either directly or through a parallel split object).

The input port can be connected to all types of steps and parallel join objects. The output port can be connected to the input port of all types of steps, to parallel split objects, and to the history port of macro steps.

During execution the truth-value of the condition of the transition is indicated using colors. A true condition is indicated by a green transition. A false condition is indicated by a red transition. The condition text can be shown (default) or hidden. With one exception, changes to the transition condition while executing will not take effect until the next time the transition is compiled. The exception is that changes of conditions involving only boolean literals will take effect immediately. For example, it is possible to change the condition from "1" to "0" at run-time and vice versa.

Transitions currently have no name.

Menu Choices:

Shows the condition of the transition.
Hides the condition of the transition. When the condition is hidden it is shown as a tool-tip text.
Brings up a text-editor through which the transition condition can be changed. The same editor can also be brought up by simply clicking on the condition text.
Forces an enabled transition to be fired by overriding the transition condition.

Text Methods:

Since transitions have no name there is no way to create references to them and, hence, transitions have no text methods. This is subject to change in future releases.


Parallel Split

The parallel split is used to split up the execution in two parallel branches. If more than two branches are needed the parallel split objects can be connected in series (an output port of the first parallel split object is connected to the input port of the second parallel split).

The input port of a parallel split may be connected to the output ports of transitions and exception transitions and to a output port of other parallel split objects. The output port of a parallel split object may be connected to the input port of an arbitrary step and to the input port of another parallel split object. When a transition preceding the parallel split is fired all steps connected directly or indirectly to the output ports of the parallel split are activated.

Parallel splits have no menu choices and no text methods.



Parallel Join

  

The parallel join is used to merge together the execution in two parallel paths into a single path. If more than two branches need to be joined the parallel join objects can be connected in series (the output port of the first parallel join is connected to an input port of the second parallel join).

The input port of a parallel join may be connected to the output ports of arbitrary steps and to the output port of another parallel join objects. The output port of a parallel join may be connected to the input port of a transition. The transitions connected to the output port of a parallel join are not enabled unless all the steps connected directly or indirectly to the input ports of the parallel join are active. When the transition fires all the preceding steps are deactivated.

Parallel joins have no menu choices and no text methods.



Macro Step


A macro step represents a hierarchical step containing a substructure of steps and transition on the subworkspace of the macro step.A macro step may have one or several input ports and one or several output ports. By default a macro step has one input port and one output port. An enter step located on the subworkspace of the macro step is associated with each input port. The association is based upon the x-position of the enter step. The leftmost enter step is associated with the leftmost input port et cetera. An exit step located on the subworkspace of the macro step is associated with each output port, Also in this case it is the geographical location of the exit step that decides the association. The input ports may be connected to the output ports of transitions, exception transitions, and parallel splits. The output ports may be connected to the input ports of transition, exception transitions, and parallel joins.

When a macro step is activated through a certain input port, the corresponding enter step is activated. When an exit step is activated the transitions connected to the output port associated with the exit step are enabled. When any of these transitions fires both the exit step and the entire macro step are deactivated.

On the left-hand side of the macro step is a special exception output port. To this port it is only possible to connect the input ports of exception transitions. The exception transitions are enabled all the time while the macro step is active. If fired they will abort the execution of the macro step. Exception transitions have priority over "ordinary" transitions. Macro steps remember the state they were in when they last were aborted. By activating the macro step through the history input port on the right hand side of the macro step the macro step is resumed in the state it was in when it last was aborted. Resuming a macro step that never has been aborted before is considered an error.

A macro step may have actions in the same way as ordinary steps. The stored actions of the macro step are executed before the stored actions of the enter step. Similarly, the exit actions of the macro step are executed after the execution of the exit actions of the exit step. The periodic actions of the macro step are executed while the macro step is active, independently of which internal step that is active. The abort actions of the macro step are executed when the macro step has been aborted due to the firing of an exception transition. The abort actions of the macro step are executed after the abort actions of the internal steps of the macro steps.

A macro step may have a name. By default the macro step has no name. The user can give the macro step a name by clicking on the (invisible) name text-edit field to the right of the step (see the figure above). Macro steps names are needed in references to the .s, .x and .t attributes of the macro step.

Menu Choices:

A toggle menu choice that shows the subworkspace of the macro step if it is hidden and shows the subworkspace if it is shown. The subworkspace remembers its actual position, size, and scale factor when it is hidden.

Brings up a table containing all internal variables, analog inputs and outputs, digital inputs and outputs, and all hierarchical elements (macro steps, workspace objects, XML Message In, XML Message Out, procedures) found inside the macro step. By double clicking on the value of an internal variable or input/output it is possible to change the current value of the object. This is, however, only possible if the workspace that the object resides in is not locked, and, in the case the object is an internal variable, the internal variable has not been declared constant. By double-clicking on the value column for a hierarchical object, a new table is shown contain the internals of the hierarchical object. The variable values in the table are dynamically updated. The table is shown below:


Brings up the step action editor.
Adds or removes input and output port stubs in such a way that the number of port stubs corresponds to the number of enter and exit steps on the subworkspace of the macro step. To create a macro step with multiple input port and/or output ports the user adds new enter steps and/or exit steps to the subworkspace and then updates the stubs. Enter steps and exit steps are not available in the palette. Therefore, they must be created using copy and paste.

Text Methods:

Sets the color of the subworkspace to the given integer RGB color.
Returns the color of the subworkspace as an integer.
Shows the subworkspace of the macro step.
Hides the subworkspace of the macro step.

Enter Step

The enter step is an ordinary step that is activated when a macro step is activated through an input port or when a  procedure call is made. The enter step has an action block and may have actions in the same way as ordinary steps. The connection rules for the output port are the same as for ordinary steps. A macro step may contain multiple enter steps, but a procedure may only contain one enter step.

Enter steps have the same menu choices and text methods as ordinary steps.





Exit Step

The exit step is an ordinary step that marks the last step within a macro step or within a procedure. When the exit step of a macro step is activated the transitions connected at the corresponding output port of the macro step are enabled. When the exit step of a procedure is activated the behavior differs depending in which way the procedure was invoked. If the procedure was invoked from a procedure step then the transitions connected at the output port of the procedure step is enabled. When it fires the exit step and the procedure step are deactivated and the actual procedure call is terminated. If the procedure is invoked directly from the procedure object or if it is invoked from a process step then the procedure call is immediately terminated without executing any of the actions of the exit step.A macro step may contain multiple exit steps, but a procedure may only contain one exit step. The connections rules for the input port are the same as for ordinary steps.

Exit steps have the same menu choices and text methods as ordinary steps.


Exception Transition

An exception transitions is a special transition for which the input port only may be connected to the exception output port of macro steps and of procedure steps. When the exception transition is fired the macro step or procedure step is aborted and the corresponding abort actions are executed. Exception transitions have priority over ordinary transitions. When connected to a macro step it is possible to refer to the internal state of the macro step from the condition. For example, it is possible to express that an exception only may be fired if the macro step is in a certain internal state. The connection rules for the output port are the same as for ordinary transitions.

Exception transitions have the same menu choices as ordinary transitions and it has currently no text methods.




 Procedure

Step-transition sequences that are used in several different contexts can be represented as procedures. A procedure has a procedure body stored on the subworkspace of the procedure. The body begins with one enter step and ends with one exit step. Procedures are re-entrant and may be recursive. 

A procedure can be called in three different ways: When a procedure is called from a procedure step, the transition(s) after the procedure step does not become enabled until the execution has reached the exit step of the procedure. Hence, this corresponds to an ordinary procedure call, When a procedure is called from a process step the transition(s) after the procedure step is enabled immediately. Conceptually, the procedure call is spawned and executed in a separate execution thread.

The procedure step may contain arbitrary language elements, except other procedures, input variables, and output variables.

Procedures may have parameters. All internal variables in the procedure body can be used as parameters. In addition it is also possible to use workspace objects as parameters if the workspace objects only contain internal variables and other workspace objects with the same restriction. Workspace objects of this type represent structured variables. Internal variable parameters can be assigned values both using call-by-value and call-by-reference. Workspace object parameters can only be assigned values using call-by value.

Menu Choices:

A toggle menu choice that shows the subworkspace of the procedure if it is hidden and shows the subworkspace if it is shown. The subworkspace remembers its actual position, size, and scale factor when it is hidden.

Brings up a table containing all internal variables, analog inputs and outputs, digital inputs and outputs, and all hierarchical elements (macro steps, workspace objects, XML Message In, XML Message Out, procedures) found inside the procedure. By double clicking on the value of an internal variable or input/output it is possible to change the current value of the object. This is, however, only possible if the workspace that the object resides in is not locked, and, in the case the object is an internal variable, the internal variable has not been declared constant. By double-clicking on the value column for a hierarchical object, a new table is shown contain the internals of the hierarchical object. The table is shown below:



Brings up a parameter text editor. This editor is used to set the parameter values when the procedure is called directly from the procedure object.



The syntax for call-by-value parameter assignments is

V <internal_variable> = <expression>;

In the example above the internal variable Y1 in the procedure body will be assigned the value of variable Y2 when the procedure is called.

The syntax for call-by-reference parameter assignments is

R <internal_variable> = <variable>;

In the example above a redirection link is set up between the internal variable Y3 in the procedure body and the variable Y4. Every reference and assignment to Y3 within the procedure body will be redirected to Y4. In this way it is possible to pass out values from the call to a procedure.
Brings up a parameter from which it is possible to call the procedure.



When invoked in this way each procedure call will be executed by a separate execution thread. The thread sleep interval decides the scan period of this thread. The simulator mode checkbox decides whether analog and digital input and output variables should be connected to the IO or only to the graphical user interface.(NOTE: Should probably be removed. Not relevant since procedures may not contain input and output variables.)
Brings up a menu showing all currently executing invocations of the procedure. By selecting one of them the body of that particular procedure call is shown.



Text Methods:

Starts a call to the procedures as a separate execution thread in the same way as if the procedure had been started with a Process Step. The parameter argument is a string containing a parameter list with same format as for a Procedure Step or Process Step. The parameters are evaluated in the context of the action that the method call is part of, i.e., within the context of the Step or Button that contains the corresponding action.


Procedure Step

A procedure represents a call to a procedure. The input port and the output port can be connected in the same way as for an ordinary step. The exception output port behaves in the same way as the exception output port of a macro step. However, it is not possible to resume the execution of a procedure. The transitions connected to the output port are enabled when the enter step of the procedure is activated. When any of the transitions are fired the exit step is deactivated, the procedure call is terminated, and the procedure step is deactivated.

Menu Choices:

Brings up a editor from which the users sets the procedure to be called, the procedure parameters, and the procedure step actions.



The procedure to be called is entered in the Procedure field.The reference can be written in several ways:
The procedure parameters are entered in the Procedure parameters field. The syntax for call-by-value parameter assignments is

V <internal_variable> = <expression>;

In the example above the internal variable Y1 in the procedure body will be assigned the value of variable Y2 when the procedure is called. The expression will be evaluated in the context of the procedure step.

The syntax for call-by-reference parameter assignments is

R <internal_variable> = <variable>;

In the example above a redirection link is set up between the internal variable Y3 in the procedure body and the variable Y4. Every reference and assignment to Y3 within the procedure body will be redirected to Y4. in this way it is possible to pass out values from the call to a procedure.

Procedure step actions are entered in the Step actions field. The normal step action syntax is used.
Brings up the body of the procedure call.

Text Methods:


Process Step

A process step is a special version of a procedure step where the call to the procedure is started as a separate execution thread. The transitions connected at  the output port are enabled immediately when the procedure has been started. It is possible to have several executing procedure calls emanating from the same process step. When the execution within a procedure call reaches the exit step the procedure call is terminated without executing any actions of the exit step. Process steps have no exception output ports.

Menu Choices:

Brings up a editor from which the users sets the procedure to be started, the procedure parameters, and the process step actions. The editor is the same as for the procedure step.
Brings up a menu showing all currently executing invocations of the procedure. By selecting one of them the body of that particular procedure call is shown.

Text Methods:




Workspace Object


A workspace is an object that contains a subworkspace. On the subworkspace it is possible to place arbitrary JGrafchart elements. The workspace object can be used for several purposes, e.g.;

Menu Choices:

A toggle menu choice that shows the subworkspace of the workspace object if it is hidden and hidess the subworkspace if it is shown. The subworkspace remembers its actual position, size, and scale factor when it is hidden.
Brings up a table containing all internal variables, analog inputs and outputs, digital inputs and outputs, and all hierarchical elements (macro steps, workspace objects, XML Message In, XML Message Out, procedures) found inside the workspace object. By double clicking on the value of an internal variable or input/output it is possible to change the current value of the object. This is, however, only possible if the workspace that the object resides in is not locked, and, in the case the object is an internal variable, the internal variable has not been declared constant. By double-clicking on the value column for a hierarchical object, a new table is shown contain the internals of the hierarchical object. The variable values in the table are dynamically updated. The table is shown below:


Brings up an edit dialog




Relative scan period:
By default the contents of a workspace object execute at the same rate as the top-level workspace that it is contained in. However by setting the relative scan period it is possible to have the workspace object execute at a slower rate. If the value is set to 2 the contents of the workspace object will only be executed every second time that that the workspace object is executed, etc. This is useful if the application contains parts with different execution rate demands.

Enabled:
When a workspace object is disabled the contents of the workspace object will not be executed. This only effects the execution of transitions and exception transitions. For, example, it is still possible to call a procedure that is located within a disabled workspace object. Input variables located within the workspace object will also still receive new values.

Use Icon:
Determines if the workspace object should use its default graphical presentation or if it should replace this by the icon given by the Icon text field.

Icon:
The file name to a .gif or .jpg file that may be used as an alternative graphical presentation of the workspace object.

Def.Size:
The size of the icon is modified to the default size of the icon associated with the workspace object.

Text Methods:

Set the color of the subworkspace of the workspace object.
Returns the color of the subworkspace of the workspace object.
Shows the subworkspace.
Hides the workspace.
Determines whether the workspace object should be enabled or disabled.
Returns the tick length in milliseconds for the subworkspace context of the workspace. Takes the relative scan period into account. Can also be applied to top-level workspaces.



Step Fusion Set

A step fusion set makes it possible to have steps with  multiple views. Each step that belongs to a step fusion set constitutes one view of the same conceptual step. When one of the steps in the set become active, all the steps in the set are activated, and when one of the steps is deactivated, all are deactivated. The steps that should belong to the same set are specified by Free Text objects on the subworkspace of the step fusion set. Global (qualified) references must be used. Step fusion sets may contain steps, macro steps, and procedure steps. Neither the step fusion set itself or any of its views may be contained within a procedure. In principle it should be possible for a step to be a member of multiple step fusion sets, although this has not been tested.

A step fusion set may be non-abortive or abortive.

Non-abortive step fusion sets:

In a non-abortive fusion set, all the transitions connected to the output of any of the step fusion set views must be enabled in order for one of the transitions to be enabled. When an enabled transition is fired, all the steps in the set are deactivated and their exit actions are executed. The different steps of a non-abortive fusion set behave as if they all are connected in parallel.

Abortive step fusion sets:

In an abortive fusion set, a transition connected to the output of one of the steps in the set is enabled  independently of the status of the other steps in the set. When an enabled transition is fired, the step connected to the transition is terminated in the normal way and its exit actions are executed. The other steps in the fusion set are aborted and their abortive actions are executed.

Double clicking on the step fusion works as a Show/Hide Body menu choice on a workspace object.

Text Methods:



Connection Post

Connection posts are used to connect JGrafchart language elements without graphical connections. They can be used to split up a function chart and separate it on multiple workspaces. It can also conveniently be used to avoid "spaghetti function charts". A connection post connection consists of one Connection Post In object and one Connection Post Out object.

Double-clicking on a connection post brings up a dialog window where the user should enter the name of the remote connection post to which the connection should be created. Similarly, the corresponding name has to be entered in the remote connection post. Note: Global (qualified) references
must be used.


When moving the mouse over a connection post the two connected connection posts are highlighted in red. The name of the remote connection posts is shown as a tool tip.









Variables and lists




Boolean Variable



A boolean variable has the value true (represented by the literal 1) or false (represented by the literal 0). A boolean variable can be used in a transition condition and in an action. By default, a variable retains its value when the application is stopped and later restarted. Optionally, the user may give a variable an initial value. If the variable has an initial value its value will be set to the initial value when the application is started.

A boolean variable can be declared as being constant. A constant variable may not be changed at run-time, neither from a JGrafchart application nor by the user. A variable that is declared constant is shown with a blue icon.

A boolean variable may have an associated update expression. In this case the variable automatically receives a new value in the beginning of every scan cycle through an evaluation of the update expression. The update expression will be evaluated as a boolean expression. Boolean variables that receive their values from an update expression may be used in  falling edge and raising edge event expression in the same way as Digital Inputs.

Double-clicking on the variable brings up an edit menu.




Initial value:
The initial value of the variable. An empty initial value field means that no initial value should be used.

Constant:
If selected the variable will be considered a constant which may not be written to.

Automatic Update?:
If selected the variable will automatically receive a new value in the beginning of every scan cycle through an evaluation of the update expression.

Update expression:
The automatic update expression for the variable.

The user can edit the value of the variable during execution.

Text Methods:

Returns true if the variable receives it value from the update expression.

Decides if the value should receive its value from the update expression or not. May only be used to turn the updating on or off, if the updating was on when the variable was last compiled.





Integer Variable


An integer variable has a value that is represented by a Java int. An integer variable can be used in a transition condition and in an action. By default, a variable retains its value when the application is stopped and later restarted. Optionally, the user may give a variable an initial value. If the variable has an initial value its value will be set to the initial value when the application is started.

An integer variable can be declared as being constant. A constant variable may not be changed at run-time, neither from a JGrafchart application nor by the user. A variable that is declared constant is shown with a blue icon.

An integer variable may have an associated update expression. In this case the variable automatically receives a new value in the beginning of every scan cycle through an evaluation of the update expression. The update expression will be evaluated as an integer expression.


Double-clicking on the variable brings up an edit menu.




Initial value:
The initial value of the variable. An empty initial value field means that no initial value should be used.

Constant:
If selected the variable will be considered a constant which may not be written to.

Automatic Update?:
If selected the variable will automatically receive a new value in the beginning of every scan cycle through an evaluation of the update expression.

Update expression:
The automatic update expression for the variable.

The user can edit the value of the variable during execution.

Text Methods:

Returns true if the variable receives it value from the update expression.

Decides if the value should receive its value from the update expression or not. May only be used to turn the updating on or off, if the updating was on when the variable was last compiled.


Real Variable


A real variable has a value that is represented by a Java double. A real variable can be used in a transition condition and in an action. By default, a variable retains its value when the application is stopped and later restarted. Optionally, the user may give a variable an initial value. If the variable has an initial value its value will be set to the initial value when the application is started,

A real variable can be declared as being constant. A constant variable may not be changed at run-time, neither from a JGrafchart application nor by the user. A variable that is declared constant is shown with a blue icon.

A real variable may have an associated update expression. In this case the variable automatically receives a new value in the beginning of every scan cycle through an evaluation of the update expression. The update expression will be evaluated as a real expression.


Double-clicking on the variable brings up an edit menu.




Initial value:
The initial value of the variable. An empty initial value field means that no initial value should be used.

Constant:
If selected the variable will be considered a constant which may not be written to.

Automatic Update?:
If selected the variable will automatically receive a new value in the beginning of every scan cycle through an evaluation of the update expression.

Update expression:
The automatic update expression for the variable.

The user can edit the value of the variable during execution.

Text Methods:

Returns true if the variable receives it value from the update expression.

Decides if the value should receive its value from the update expression or not. May only be used to turn the updating on or off, if the updating was on when the variable was last compiled.

String Variable

A string variable has a value that is represented by a Java String. A string variable can be used in a transition condition and in an action. By default, a variable retains its value when the application is stopped and later restarted. Optionally, the user may give a variable an initial value. If the variable has an initial value its value will be set to the initial value when the application is started,

A string variable can be declared as being constant. A constant variable may not be changed at run-time, neither from a JGrafchart application nor by the user. A variable that is declared constant is shown with a blue icon.

A string variable may have an associated update expression. In this case the variable automatically receives a new value in the beginning of every scan cycle through an evaluation of the update expression. The update
expression will be evaluated as a string expression.


Double-clicking on the variable brings up an edit menu.




Initial value:
The initial value of the variable. An empty initial value field means that no initial value should be used.

Constant:
If selected the variable will be considered a constant which may not be written to.

Automatic Update?:
If selected the variable will automatically receive a new value in the beginning of every scan cycle through an evaluation of the update expression.

Update expression:
The automatic update expression for the variable.

The user can edit the value of the variable during execution.

Text Methods:

Returns true if the variable receives it value from the update expression.

Decides if the value should receive its value from the update expression or not. May only be used to turn the updating on or off, if the updating was on when the variable was last compiled.

Boolean List

A boolean list is a list that contains boolean values. When an application is started the list will be empty, unless an initial value has been defined for the list. Selecting the list brings up an edit window. In the edit window the current content of the list is shown and it is possible to enter the initial value for the list. The initial values are separated by semi-colons.




Text Methods:

Returns true if the list is empty and false if the list is non-empty.
Empties the list.
Returns the number of elements in the list.
Adds an element at the end of the list.
Adds an element at the specified position in the list. The first element in the list corresponds to position 0.
Adds an element at the beginning of the list.
Returns the boolean value at the given position.
Returns the index of the first occurrence of value in the list. Returns -1 if the value is not found.
Removes the value at the given position from the list.
Sets a new value for the element at the given position.

Integer List

An integer list is a list that contains integer values. When an application is started the list will be empty, unless an initial value has been defined for the list. Selecting the list brings up an edit window. In the edit window the current content of the list is shown and it is possible to enter the initial value for the list. The initial values are separated by semi-colons.




Text Methods:

Returns true if the list is empty and false if the list is non-empty.
Empties the list.
Returns the number of elements in the list.
Adds an element at the end of the list.
Adds an element at the specified position in the list. The first element in the list corresponds to position 0.
Adds an element at the beginning of the list.
Returns the integer value at the given position.
Returns the index of the first occurrence of value in the list. Returns -1 if the value is not found.
Removes the value at the given position from the list.
Sets a new value for the element at the given position.

Real List

A real list is a list that contains real values. When an application is started the list will be empty, unless an initial value has been defined for the list. Selecting the list brings up an edit window. In the edit window the current content of the list is shown and it is possible to enter the initial value for the list. The initial values are separated by semi-colons.




Text Methods:

Returns true if the list is empty and false if the list is non-empty.
Empties the list.
Returns the number of elements in the list.
Adds an element at the end of the list.
Adds an element at the specified position in the list. The first element in the list corresponds to position 0.
Adds an element at the beginning of the list.
Returns the integer value at the given position.
Returns the index of the first occurrence of value in the list. Returns -1 if the value is not found.
Removes the value at the given position from the list.
Sets a new value for the element at the given position.


String List

A string list is a list that contains text strings. When an application is started the list will be empty, unless an initial value has been defined for the list. Selecting the list brings up an edit window. In the edit window the current content of the list is shown and it is possible to enter the initial value for the list. The initial values are separated by semi-colons.The values in the initial-value description may not themselves contain any semi-colons.




Text Methods:

Returns true if the list is empty and false if the list is non-empty.
Empties the list.
Returns the number of elements in the list.
Adds an element at the end of the list.
Adds an element at the specified position in the list. The first element in the list corresponds to position 0.
Adds an element at the beginning of the list.
Returns the integer value at the given position.
Returns the index of the first occurrence of value in the list. Returns -1 if the value is not found.
Removes the value at the given position from the list.
Sets a new value for the element at the given position.

Inputs and Outputs


Digital Input

A digital input is a boolean variable that is connected to a digital input channel. The digital input has a name and a channel number. The channel number should be an integer. The color of the icon is red when the value is false and green when the value is true. The value of the digital input can be changed on-line by the user using editing or by double-clicking on the icon (will cause a toggle of the binary value).

A digital input can be referenced from a transition or an action. It is not allowed to try to assign a new value to a digital input from an action. The digital input will only be connected to the external environment when the Simulator mode checkbox in the workspace properties is not set. By default this check box is set.

By default the digital input is associated with the Department of Automatic Control  Java digital input channel class. It is possible for the user to attach the digital input object to a custom user-provided implementation of a digital input channel. In this way it is possible to connect JGrafchart to arbitrary IO cards, etc. The details for how to do this are found in custom IO information

Text Methods:


Digital Input (Inverse Logic)

A digital input with inverse logic is a boolean variable that is connected to a digital input channel. The digital input has a name and a channel number. The channel number should be an integer. The digital input has the value 1 (0) when the value of the corresponding digital input channel is false (true). The color of the main part of the icon is red when the value is false and green when the value is true. The value of the digital input can be changed on-line by the user using editing or by double-clicking on the icon (will cause a toggle of the binary value).

A digital input can be referenced from a transition or an action. It is not allowed to try to assign a new value to a digital input from an action. The digital input will only be connected to the external environment when the Simulator mode checkbox in the workspace properties is not set. By default this check box is set.

By default the digital input is associated with the Department of Automatic Control Java digital input channel class. It is possible for the user to attach the digital input object to a custom user-provided implementation of a digital input channel. In this way it is possible to connect JGrafchart to arbitrary IO cards, etc. The details for how to do this are found in custom IO information

Text Methods:


Digital Output

A digital output is a boolean variable that is connected to a digital output channel. The digital output has a name and a channel number. The channel number should be an integer. The color of the icon is red when the value is false, green when the value is true, and black if no value has been assigned to it. The value of the digital output may not be changed on-line by the user through editing or by double-clicking on the icon.

A digital output is assigned its value from an action. A digital output can also be referenced from a transition or an action.  The digital output will only be connected to the external environment when the Simulator mode checkbox in the workspace properties is not set. By default this check box is set.

By default the digital output is associated with the Department of Automatic Control Java digital output channel class. It is possible for the user to attach the digital output object to a custom user-provided implementation of a digital output channel. In this way it is possible to connect JGrafchart to arbitrary IO cards, etc. The details for how to do this are found in custom IO information

Text Methods:


Digital Output (Inverse Logic)

A digital output with inverse logic is a boolean variable that is connected to a digital output channel. The digital output has a name and a channel number. The channel number should be an integer. The digital output channel will be set to true (false) when the value of the digital output is 0 (1). The color of the main part of the icon is red when the value is false, green when the value is true, and black if no value has been assigned to it. The value of the digital output may not be changed on-line by the user through editing or by double-clicking on the icon.

A digital output is assigned its value from an action. A digital output can also be referenced from a transition or an action.  The digital output will only be connected to the external environment when the Simulator mode checkbox in the workspace properties is not set. By default this check box is set.

By default the digital output is associated with the Department of Automatic Control Java digital output channel class. It is possible for the user to attach the digital output object to a custom user-provided implementation of a digital output channel. In this way it is possible to connect JGrafchart to arbitrary IO cards, etc. The details for how to do this are found in custom IO information

Text Methods:


Analog Input

An analog input is a real variable that is connected to a analog input channel. The analog input has a name and a channel number. The channel number should be an integer.  The value of the input can be changed on-line by the user using editing.

An analog input can be referenced from a transition or an action. It is not allowed to try to assign a new value to an analog input from an action. The analog input will only be connected to the external environment when the Simulator mode checkbox in the workspace properties is not set. By default this check box is set.

By default the analog input is associated with the Department of Automatic Control Java analog input channel class. It is possible for the user to attach the analog input object to a custom user-provided implementation of a analog input channel. In this way it is possible to connect JGrafchart to arbitrary IO cards, etc. The details for how to do this are found in custom IO information

Text Methods:


Analog Output

An analog output is a real variable that is connected to a digital output channel. The analog output has a name and a channel number. The channel number should be an integer.  The value of the analog output may not be changed on-line by the user through editing or by double-clicking on the icon.

An analog output is assigned its value from an action. An analog output can also be referenced from a transition or an action.  The analog output will only be connected to the external environment when the Simulator mode checkbox in the workspace properties is not set. By default this check box is set.

By default the analog output is associated with the Department of Automatic Control Java analog output channel class. It is possible for the user to attach the analog output object to a custom user-provided implementation of a analog output channel. In this way it is possible to connect JGrafchart to arbitrary IO cards, etc. The details for how to do this are found in custom IO information

Text Methods:


Socket IO

Each top-level workspace can act as the client in a TCP socket connection with some user-defined TCP server. For each of the four basic data types there is one socket input variable type and one socket output variable type. For socket output variables a TCP message is being sent each time the variable receives a new value. Similarly, a socket input variable receives a new value when a matching TCP message is received.

The TCP message uses a simple text protocol. A message consists of

"identifier"  |  "value"

The identifier is the local (non-qualified) name of the variable, unless a special identifier has been defined for the variable, in which case this identifier will be used. Since it is the local name that is used it is possible for several socket input variables to be updated as the result of one incoming TCP message.

The host name (or URL) and the port of the TCP server is entered through the Properties menu of the top-level workspace. An empty socket name and a port number of -1 means that no socket connection will be established. An established connection remains open until the Shutdown Client menu choice is entered.


Boolean Socket Input 

A boolean socket input variable is a boolean input variable that receives its value through a TCP message. The variable receives a new value when a matching TCP message is received. If the identifier of the variable has a value then the message identifier should equal this value. If not, the message identifier should equal the local name of the variable.

The identifier is set from the edit-menu of the variable.



Text Methods:


Integer Socket Input

An integer socket input variable is an integer input variable that receives its value through a TCP message. The variable receives a new value when a matching TCP message is received. If the identifier of the variable has a value then the message identifier should equal this value. If not, the message identifier should equal the local name of the variable.

The identifier is set from the edit-menu of the variable.




Text Methods:


Real Socket Input

A real socket input variable is a real input variable that receives its value through a TCP message. The variable receives a new value when a matching TCP message is received. If the identifier of the variable has a value then the message identifier should equal this value. If not, the message identifier should equal the local name of the variable.

The identifier is set from the edit-menu of the variable.




Text Methods:


String Socket Input

A string socket input variable is a string input variable that receives its value through a TCP message. The variable receives a new value when a matching TCP message is received. If the identifier of the variable has a value then the message identifier should equal this value. If not, the message identifier should equal the local name of the variable.

The identifier is set from the edit-menu of the variable.




Text Methods:


Boolean Socket Output 

A boolean socket output variable is a boolean output variable that is connected to a TCP socket. A TCP message is being sent each time the variable receives a new value.  If the identifier of the variable has a value then this value is used as message identifier. Otherwise, the local (unqualified) name of the variable is used as message identifier.

The identifier is set from the edit-menu of the variable.



The Procel check box is for a special purpose IO and should be ignored.

Text Methods:


Integer Socket Output


An integer socket output variable is an integer output variable that is connected to a TCP socket. A TCP message is being sent each time the variable receives a new value.  If the identifier of the variable has a value then this value is used as message identifier. Otherwise, the local (unqualified) name of the variable is used as message identifier.

The identifier is set from the edit-menu of the variable.



The Procel check box is for a special purpose IO and should be ignored.

Text Methods:


Real Socket Output

A real socket output variable is a real output variable that is connected to a TCP socket. A TCP message is being sent each time the variable receives a new value.  If the identifier of the variable has a value then this value is used as message identifier. Otherwise, the local (unqualified) name of the variable is used as message identifier.

The identifier is set from the edit-menu of the variable.


 

The Procel check box is for a special purpose IO and should be ignored.


Text Methods:


String Socket Output

A string socket output variable is a string output variable that is connected to a TCP socket. A TCP message is being sent each time the variable receives a new value.  If the identifier of the variable has a value then this value is used as message identifier. Otherwise, the local (unqualified) name of the variable is used as message identifier.

The identifier is set from the edit-menu of the variable.


 

The Procel check box is for a special purpose IO and should be ignored.


Text Methods:


CHEM and CCOM

JGrafchart has been developed within the EU/GROWTH FP5 project CHEM - Advanced Decision Systems for the Chemical/Petrochemical Manufacturing Industries. Within CHEM a large number of operator support toolboxes for different tasks (e.g., alarm analysis, fault detection, diagnosis, planning) are being developed. The toolboxes are implemented in different languages and run on different platforms. They are integrated through the CCOM infrastructure.

CCOM (Chem Communications Manager) allows toolboxes to communicate using message passing. It is based on the message-oriented middleware xmlBlaster. The messages are represented by XML structures. CCOM supports publish/subscribe and point-to-point communication. The messages can be of different type, e.g., data messages, event messages, RPC invocation messages, and RPC response messages. The CHEM information model establishes a common syntax for data messages.

Representing XML structures

XML structures are represented by XML Message objects. XML Message In objects are used to receive XML messages and XML Message Out objects are used to send XML messages. The XML Message objects are hierarchically structured objects similar to workspace objects. They may only contain internal variables and workspace objects.

The identifier of the XML Message object determines the tag of the main XML element. If the identifier has no value the name of the XML Message object is used instead. Internal variables within the XML Message object represent either simple XML elements or XML attributes. The name of the internal variable maps to the element or attribute name and the value of the internal variable maps to the value of the element or attribute. Workspace objects within the XML Message object represent structured XML elements (elements that contain child elements and/or attributes). The name of the workspace objects maps to the name of the structured element.
The top-down order of the objects on the subworkspace of the XML Message object determines the order of the elements and attributes in the XML structure.

Example: Representing XML Structures

An example showing an XML structure and its corresponding XML Message represented is shown below. Here it is the name of the XML Message Out object that corresponds to the main element tag name.



In order to indicate that an internal variable should represent an XML attribute rather than a simple XML element, special Attribute Variable objects are used. The attribute variable objects are subclasses of the corresponding internal variable class.

Example: Representing XML Structures with Attributes

This example contains both elements and attributes.



XML structures that contain multiple occurrences of elements with the same tag name are represented in a special way. Special index variables (a subclass of integer variable) are used to represent the multiplicity of the element. The name of the index variable maps to the tag name of the multiple element. The value of the index variable determines the number of occurrences of the multiple element. The individual occurrences of the multiple element are represented as ordinary elements (using internal variables or workspace objects). They should be named "element name" + "integer index", where the integer index goes from 1 up to the number of occurrences of the multiple element.

Example: Representing XML structures containing Multiple Elements

In the following example multiple occurrences of the element MultipleElement exist.



Since the index variable MultipleElement has the value 2 only two occurrences of the MultipleElement element will be present in the XML structure that is created. Similarly, if an XML structure is received that may contain multiple occurrences of MultipleElement, then the value of the index variable will indicate how many occurrences that were present in the actual message that was received. The number of  individual instances of a multiple element (in this case MultipleElement1, MultipleElement2, MultipleElement3) must be equal to the maximum number of occurrences (worst-case).

Connecting to CCOM

In order to use the CCOM XML messaging service, JGrafchart must first be connected to CCOM. JGrafchart can be connected to CCOM in two different ways:
  1. Manual CCOM Connection
    Here the server properties (Server IP address, server port, and login name) are entered manually using the CCOM Server menu action in the Misc menu. Once this is done  the connection is established using the Connect CCOM menu action. JGrafchart is disconnected from the server using the menu action Disconnect CCOM.
  1. Automatic CCOM Connection.
    JGrafchart is automatically connected to CCOM if it is started using the command line options -connect 1 -serverIP "xyz.zyx.zyx.zyx" -port 3412 -name JGrafchart. The default value for port is 3412 and for name (the login name) is JGrafchart. JGrafchart is automatically disconnected from CCOM when it is terminated.

Publishing Data Messages

The message to be published is represented by an XML Message Out object. Attributes of the XML Message Out object are used to decide the topic under which the data message should be published, the CCOM type of the data message (Data or Event), the origin of the publication (i.e., JGrafchart), etc.

To publish a data message the following steps are performed:
  1. The content of the message is built up using ordinary actions, For example, the values of the different elements and attributes within the XML Message out object are set using assignment actions.
  2. The necessary XML Message out attributes are set either interactively or programmatically.
  3. The message is published by calling the method publishMessage() of the XML Message Out object. When this is done an XML Message structure is created from the XML Message Out object. The XML Message is embedded in an CCOM envelope and then send to the CCOM server.

Sending Data Messages

The message to be sent is represented by an XML Message Out object. Attributes of the XML Message Out object are used to decide the destination of the message, the CCOM type of the data message (Data or Event), the origin of the publication (i.e., JGrafchart), etc.

To send a data message the following steps are performed:
  1. The content of the message is built up using ordinary actions, For example, the values of the different elements and attributes within the XML Message out object are set using assignment actions.
  2. The necessary XML Message out attributes are set either interactively or programmatically.
  3. The message is sent by calling the method sendMessage() of the XML Message Out object. When this is done an XML Message structure is created from the XML Message Out object. The XML Message is embedded in an CCOM envelope and then send to the CCOM server.

Subscriptions

In order to receive messages that published under a certain topic the toolbox must first have subscribed to the topic. Subscription and unsubscription can be made in two different ways:
  1. Implicit subscription
    When the application is started an automatic subscription is made to the topics of all the XML Message In objects of the application. Similarly, when the application is stopped an automatic unsubscription is made to the topics of all the XML Message Out objects in the application. Implicit subscription is always activated.
  2. Explicit subscription.
    A topic is subscribed to using the function subscribe(aTopic). Similarly a topic is unsubscribed to using the function unsubscribe(aTopic)

Receiving Data Messages

All XML Messages are received using  XML Message In objects. An XML Message In object will receive an XML Message if the application is executing and the identifier of the XML Message In object is equal to the main tag name of the message. (If the identifier has no value the local name of the XML Message In is used instead). A special case exists for messages with the main tag name ChemContentMessage. If these messages contain a Subject element they will only be received in an XML Message In object if the value of the subject attribute of the XML Message In is equal to the value of the Subject element.

Multiple XML Message In objects may (and most likely will) receive the same message. When an XML Message In object is received two things occur:
  1. All variables inside the XML Message In object are initialised to their initial values (if they have any initial values).
  2. The XML structure in the message is decoded (using the DOM XML parser) and mapped to the corresponding element/attribute variables within the XML Message In object. The mapping is done according to best effort. This means that elements in the message for which there are no corresponding element/attribute variables are ignored. It also means that element/attribute variables for which there are no corresponding XML elements/attributes will not be assigned any new value. The initialisation of all variables is used to be able to detect if a variable really has been assigned a new value from the message.

Detecting Message Arrival

The reception of an XML Message by an XML Message In object can be detected in two different ways:
  1. Using an event transition expression
    The event expression /In1 is true whenever a new message is received by the XML Message In object named In1. The main advantage with is approach is that it is fast and simple. The disadvantage is that it only works if the transition is enabled. If this is not the case there is a risk that the message is lost due to overwriting by a new message. Also, the approach currently does not work for XML Message In objects that are contained within procedures.
  2. Using a procedure.
    It is possible to associate a procedure with an XML Message In object. Whenever a message is received a new call  to the procedure is spawned (similar to a process step). The entire contents of the message can be passed in as a call-by-value parameter to the procedure. The advantage of this approach is that no messages may be lost. The disadvantage is that the spawning of a procedure is quite time consuming.
Example: Detecting Message Arrival Using Transitions

An example of how the arrival of a message is detected using an event expression is shown below.


Example: Detecting Message Arrival Using a Procedure

An example of how the arrival of a message is detected using a procedure is shown below:

.
In the Procedure Menu action dialog the user indicates which procedure that should be associated with the XML Message In object. The entire object is passed in to the procedure invocation (V Message = In1;) Here it is important that the object at the left hand side in the assignment is a workspace object and not an XML Message In object.

Sending Reply Messages

When a message is received for which the MustReply attributes has the value "yes" then a reply message is required. The handle attribute of the reply message should be set to the value of the handle of the received message.

Example: Sending a Reply Message

An example of how a reply message is generated is shown below:


Receiving Message Replies

In many situations it is necessary to be able to match an incoming reply message with the original data request message. This can be done with the help of the getSendHandle() method of the XML Message Out object. The method returns the handle that was associated with the message being sent by CCOM. This handle will be a part of the reply message and can there be used to detect the correct reply message (the one that corresponds to the data request message).

Example: Receiving a Reply Message

An example of how a reply message can br replied and identified is shown below:


The DataReply message will only be decoded if it matches the DataMess message being sent.

Remote Procedure Calls

Sending RPC requests (invocations) and receiving RPC responses are done according to the same principles as for ordinary data messages.

External Calls to JGrafchart procedures

Calls from external components or toolboxes to JGrafchart procedures are handled as in the figure below.



An XML  Message In message is used to receive the RPC invocation message. The identifier/name of the XML Message In object should be Rpc. The arrival detection is implemented by a separate procedure associated with the XML Message In object (here named RPCDispatcher). The RPCDispatcher may be common to all RPCs. The RPCDispatcher calls a wrapper procedure associated with the JGrafchart procedure, e.g., by adding the "Wrapper" prefix to the procedure name.. The wrapper procedure extracts the procedure parameters from the message, calls the actual procedure, collects the out parameters, and generates an RPCResponse message that is sent back to the external caller.

Complete examples of external calls to JGrafchart procedures can be found in the on-line tutorial.

Calling External RPCs

When JGrafchart should call an RPC in another component/toolbox it is convenient to use a Grafchart procedure as a proxy for the remote procedure according to the example below.


The proxy procedure, which may have the same name as the external procedure, generates an RPCInvocation message using a local XML Message Out object, awaits the RPCResponse message using a local XML Message In object, extracts the reply parameters, and returns the reply to the context of the procedure step.

Complete examples of calling external procedures from JGrafchart can be found in the on-line tutorial.

CCOM RPC Libraries

RPC libraries with proxy procedures for the different CCOM components can be found in the grafchart/CCOM folder. To use them you need to load them and compile them. The procedures can then be called from ordinary procedure steps.

Currently the only libraries supported are the DTM Library and the Generic RTM Library.



CCOM XML Object Reference



XML Message In

An XML Message In object is an hierarchical object that is used to represent received XML Messages. It contains a subworkspace on which it is only allowed to place internal variables and workspace objects. The internal variables represent simple XML elements or XML attributes. The workspace objects represent structured XML elements. 

Menu Choices:

A toggle menu choice that shows the subworkspace of the XML Message In object if it is hidden and hides the subworkspace if it is shown. The subworkspace remembers its actual position, size, and scale factor when it is hidden.
Brings up a table containing all internal variables, analog inputs and outputs, digital inputs and outputs, and all hierarchical elements (macro steps, workspace objects, XML Message In, XML Message Out, procedures) found inside the XML Message In. By double clicking on the value of an internal variable or input/output it is possible to change the current value of the object. This is, however, only possible if the workspace that the object resides in is not locked, and, in the case the object is an internal variable, the internal variable has not been declared constant. By double-clicking on the value column for a hierarchical object, a new table is shown contain the internals of the hierarchical object. The variables values in the table are dynamically updated. The table is shown below:


Brings up an edit dialog




Identifier:
Determines which XML messages that will be received by the XML Message In object. If it has a value then only messages with this as its main element tag will be received. If the identifier has no value then the local name of the object will be used instead.

Subject:
If the value of the identifier is ChemContentMessage then Subject acts as a secondary reception filter for incoming messages. Only messages that contain a Subject element with a corresponding value will be received by the XML Message In object.

Topic:
If topic has a value then JGrafchart will automatically subscribe to this topic when the application is started. and unsubscribe to this topic when the application is stopped.

Type:
The CCOM type of the most recently received message.

Origin:
The origin (sender) of the most recently received message.

MustReply:
If this has the value "yes" then the most recently received message expects a reply message.

Handle:
The handle of the most recently received message.



Use procedure:
A checkbox that decides if a procedure call should be spawned each time a new message is received. Default = no.

Procedure:
The procedure that will be spawned when the message is received.

Procedure parameters:
The parameters to the procedure. It is common to pass in the entire XML Message In object as a parameter to a local workspace object within the procedure. In this way the content of the received message is saved and may not be overwritten by later messages.

Brings up a menu showing all currently executing invocations of the procedure. By selecting one of them the body of that particular procedure call is shown.

Text Methods:

Set the color of the subworkspace of the workspace object.
Returns the color of the subworkspace of the workspace object.
Shows the subworkspace.
Hides the workspace.
Returns the CCOM type of the most recently received message.
Returns the origin (the sender) of the most recently received message.
Returns the handle of the most recently received message.
Returns the value of the MustReply attribute of the most recently received message.
Returns the XML string of the most recently received message including the CCOM envelope.


XML Message Out   

An XML Message Out object is an hierarchical object that is used to represent sent XML Messages. It contains a subworkspace on which it is only allowed to place internal variables and workspace objects. The internal variables represent simple XML elements or XML attributes. The workspace objects represent structured XML elements. 

Menu Choices:

A toggle menu choice that shows the subworkspace of the XML Message Out object if it is hidden and hides the subworkspace if it is shown. The subworkspace remembers its actual position, size, and scale factor when it is hidden.
Brings up a table containing all internal variables, analog inputs and outputs, digital inputs and outputs, and all hierarchical elements (macro steps, workspace objects, XML Message In, XML Message Out, procedures) found inside the XML Message Out. By double clicking on the value of an internal variable or input/output it is possible to change the current value of the object. This is, however, only possible if the workspace that the object resides in is not locked, and, in the case the object is an internal variable, the internal variable has not been declared constant. By double-clicking on the value column for a hierarchical object, a new table is shown contain the internals of the hierarchical object. The variables values in the table are dynamically updated. The table is shown below:


Brings up an edit dialog




Identifier:
Determines the tag of the main element. If it has no value then the local name is used instead.

Publish (otherwise send):
A checkbox that decides if the message should be published or sent when the method outputMessage() is called. Default = publish.

Topic/Destination:
The value of this field is used as the topic when the message is published and as the destination when the message is sent. A message can only be sent to a single destination at a time.

Type:
The CCOM type of the message.

Origin:
The origin of the message. Should normally be the same as the CCOM login name, i.e., JGrafchart.

MustReply:
If this has the value "yes" then the receiver of the message is required to send a response. Otherwise it should have the value "no".

Handle:
If the message is a reply message then this attribute should contain the handle of the original message. A value of 0 means that the message is not a reply message (Default = 0).

Text Methods:

Set the color of the subworkspace of the workspace object.
Returns the color of the subworkspace of the workspace object.
Shows the subworkspace.
Hides the workspace.
Returns value of the Type attribute.
Sets the value of the Type attribute.
Returns the value of the Handle attribute.
Sets the value of the Handle attribute.
Returns the value of the MustReply attribute.
Sets the value of the MustReply attribute.
Returns the value of the Origin attribute.
Sets the value of the Origin attribute.
Returns the value publish/send attribute. True means publish.
Sets the value of the publish/send attribute.
Returns the value of the topic/destination attribute.
Sets the value of the topic/destination attribute.
Returns the value of the topic/destination attribute.The same as getDestination()
Sets the value of the topic/destination attribute. The same as setDestination(String value).
Publishes the message under the topic given by the topic/destination attribute.
Sends the message to the destination given by the topic/destination attribute.
Equivalent either to sendMessage or publishMessage depending on the value of the publish attribute.
Returns the XML message generated from the XML Message Out object excluding the CCOM envelope.
Returns the handle assigned to the most recent message being sent.


Integer Attribute

A subclass of  integer variable  that is used within XML Message In & Out objects to indicate that the variable should be represented as an XML attribute rather than an XML element.

Integer Attribute has the same menu choices and text methods as Integer Variable.


Real Attribute

A subclass of  real variable  that is used within XML Message In & Out objects to indicate that the variable should be represented as an XML attribute rather than an XML element.

Real Attribute has the same menu choices and text methods as Real Variable.



String Attribute

A subclass of  string variable  that is used within XML Message In & Out objects to indicate that the variable should be represented as an XML attribute rather than an XML element.

String Attribute has the same menu choices and text methods as String Variable.




Index Variable

A subclass of  integer variable  that is used within XML Message In & Out objects to count the number of occurrences of multiple elements.

Index Variable has the same menu choices and text methods as Integer Variable.






JGrafchart Textual Language

The JGrafchart textual language is  used in actions and in transition conditions.

Action Language

The action language syntax is defined by the following abstract grammar:

action ->  actionStmt ';' (actionStmt ';')*

actionStmt ->  storeStmt | periodicStmt | exitStmt | normalStmt | abortStmt

storeStmt -> 'S' ( assignment | methodCall )

periodicStmt -> 'P' ( assignment | methodCall )

exitStmt -> 'X' (assignment | methodCall )

normalStmt -> 'N' id            // id must reference a digital output or a boolean variable

abortStmt -> 'A' (assigment | methodCall)

assignment -> id '=' exp       // id may not reference an input variable

methodCall -> id '(' [argumentList] ')' | id '.x' | id '.t' | id '.s'

argumentList -> exp ( ',' exp )*

exp -> exp '?' exp ':' exp |   // conditional expression
       exp '&' exp |           // boolean and
       exp '|' exp |           // boolean or
       exp '==' exp |          // equality
       exp '!=' exp |          // non-equality
       exp '<' exp |           // numerical less than
       exp '>' exp |           // numerical greater than
       exp '<=' exp |          // numerical less than or equal
       exp '>=' exp |          // numerical greater than or equal
       exp '+' exp |           // addition or string concatenation
       exp '-' exp |           // subtraction
       exp '*' exp |           // multiplication
       exp '/' exp |           // division
       '-' exp |               // numerical negation
       '!' exp |               // boolean negation
       string |
       number |
       methodCall |
       id |
       '(' exp ')'

id -> ( 'a' - 'z'| 'A' - 'Z' ) ( 'a' - 'z' | 'A' - 'Z' | '_' | '.' | '^' | '0' - '9' )*

string -> '"' arbitrary ASCII characters '"'

number -> digit ( digit )*

digit -> '0' - '9' | '.'
where

Comments:

Condition Language

The textual language used in transition conditions is equivalent to the expression (exp) in the abstract syntax grammar for the action grammar with one exception. The additional  / unary prefix operator is allowed. It may be used in the following ways:
The expression '/'id is true if the value of  id is true in the current scan cycle and if the value of id was false in the previous scan cycle. Id may only refer to a digital input variable. For example, the expression /stop  returns true if stop was false in the previous scan and is true in the current scan.
The expression '\'id is true if the value of  id is false in the current scan cycle and if the value of id was true in the previous scan cycle. Id may only refer to a digital input variable. For example, the expression \stop  returns true if stop was true in the previous scan and is false in the current scan.
The expression '/'id is true if an incoming CCOM message has arrived and has been decoded into the XML Message In structure reference by id.

Functions

The textual language contains a number of predefined functions:

Mathematical functions:
Returns the sine of the argument.
Returns the cosine of the argument.
Returns the maximum value of its arguments.
Returns the minimum value of its arguments.
Returns a uniformly distributed value between 0.0 and 1.0.
Returns the square root of the argument.
Text and time functions:
Writes the string on the command window from which JGrafchart was started.
Writes the string in the message menu on the toolbar.
Removes all messages from the message menu on the toolbar.
Returns a string containing the formatted value of the argument. The formatting is performed using the Java DecimalFormatSymbols with MaximumFractionDigits = 3 and MinimumFractionDigits = 1
Returns a string containing the current date and time.
Returns a string containing the CHEM timestamp format version of the current time. No millisecond or timezone information is used. An example of what the string might look like is "2003-06-06T11:29:31".
Return the scan interval for a top-level workspace or for the subworkspace of a workspace object in milli seconds.
Generic function that makes it possible to apply an arbitrary Java method to a string. The function is implemented using Java Reflection. The first argument is the string that the method should be applied to. The second argument is a string containing the name of the method to be invoked. The third argument is a string that decides the return argument type of the method. This type will also be the type of the returned value of  stringApply. Legal values are "string", "real", "int", and "boolean". The remaining arguments consist of argument pairs where the first argument in the pair decides how the second argument should be evaluated. The legal values are the same as for the return type. For example, the following call to stringApply extracts the substring "Graf" from the argument "JGrafchart", stringApply("JGrafchart","substring","string","int",1,"int",5).


Colour functions:
Converts a color represented by three real RGB components in the interval 0.0 - 1.0 to an integer RGB value.
Extracts the red color component as a value in the range 0.0 - 1.0 from an integer RGB value.
Extracts the green color component as a value in the range 0.0 - 1.0 from an integer RGB value.
Extracts the blue color component as a value in the range 0.0 - 1.0 from an integer RGB value.
Debug functions:
Print the amount of free memory of JGrafchart in the command window from which JGrafchart was started.
Print the amount of total  memory used by JGrafchart in the command window from which JGrafchart was started.

Dynamic Loading and Creation Functions:

Loads the application named by absoluteFileName into JGrafchart. Returns the top-level workspace name of the application.
Compiles the top-level workspace named by name. Returns true if the compilation was successful.
Starts the top-level workspace named by name. Requires that the workspace has been successfully compiled.
Stops the top-level workspace named by name.
Deletes and removes the top-level workspace named by name.
Creates a new object of the given class. The name of the object is set to the name argument. The object is added to the workspace denoted by workspace at the x and y position.
Currently only the classes Rectangle and Ellipse are supported.

Misc. functions:
Adds the palette if it was previously hidden.
Hides the palette if it was previously visible.
Executes the command in a separate operating system process.
Generic function that makes it possible to call an arbitrary static method of any Java class. The function is implemented using Java Reflection. The first argument is the name of Java class. The second argument is a string containing the name of the method to be invoked. The third argument is a string that decides the return argument type of the method. This type will also be the type of the returned value of  applyStaticMethod.  Legal values are "string", "real", "int", and "boolean". The remaining arguments consist of argument pairs where the first argument in the pair decides how the second argument should be evaluated. The legal values are the same as for the return type. For example, the following call to applyStaticMethod calls the random() method of the Math class. applyStaticMethod("java.lang.Math","random","real").
CCOM functions:
Programmatic connect to CCOM.
Programmatic disconnect from CCOM.
Sets the IP address of the CCOM server.
Returns the IP address to the CCOM server.
Sets the CCOM port. (Default = 3412).
Returns the CCOM port.
Sets the CCOM login name. (Default = JGrafchart)
Returns the CCOM login name.
Subscribes to a CCOM topic.
Unsubscribes from a CCOM topic.

Evaluation Rules

The JGrafchart textual language uses loose typing and automatic type-casting whenever possible. It is the context that decides how an expression is evaluated. The following rules apply:
S Variable = 0;
If Variable is of boolean type the expression will be evaluated as the boolean literal 0. If Variable is of real or integer type the expression will be evaluated numerically. Finally, if Variable is a string then the expression will be evaluated as a string. In this case this will give rise to the value "0".

JGrafchart Execution Model

In order for a JGrafchart application to be started it must first have been successfully compiled.

Compilation

During the compilation the following things are performed:

Execution

If the compilation was successful the JGrafchart application can be started. The execution is performed as a three-phase operation. Each step has two attributes that controls the execution:
 In every scan the following operations are performed:
  1. Digital and analog inputs are read.
  2. Phase One: The transitions are traversed and every transition for which the preceding steps are all active and for which the transition condition evaluates to true is marked for firing.
  3. Phase Two: The transitions are traversed. For every transition that is marked for firing the following operations are performed:
  1. Phase Three: All steps are traversed. The following operations are performed for every step:
  1. For every digital output that has been modified by the evaluation of normal actions, the total effect of the evaluation is effectuated.
  2. The execution thread sleeps until the start of the next scan cycle. The period of the execution thread is determined by the thread sleep interval of the top-level workspace.
The above execution model has the following properties: