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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setWorkspaceColor(int color)
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.
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- Directly from the procedure object.
- Through a procedure step.
- Through a process step.
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- Proc1 - A reference to the procedure
named Proc1.
- "Proc1" - A reference to the procedure
named Proc1.
- StringVar - A reference to the variable
named by the string variable StringVar.
- "Proc" + "1" - A reference to the procedure
named Proc1.
- ObjectVar + "." + MethodVar - A reference
to the procedure named by taking the value of the string variable
ObjectVar and the value of the string variable MethodVar and concatenating
them with a "." in between,
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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.;
- As a structuring element for decomposing large applications.
- As a way of representing structured variables. In this
case the workspace object should only contain variables and other workspace
objects only containing variables. References to the variables are
made using dot-notation.
- As a way of representing objects. In this case the
workspace should only contain variables (attributes/state) and procedures
(methods/behaviour)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
- setWorkspaceColor(int color)
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.
- setEnabled(boolean value)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
- boolean isUpdated()
Returns true if the variable receives it value from the update
expression.
- setUpdated(boolean value)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
- boolean isUpdated()
Returns true if the variable receives it value from the update
expression.
- setUpdated(boolean value)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
- boolean isUpdated()
Returns true if the variable receives it value from the update
expression.
- setUpdated(boolean value)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
- boolean isUpdated()
Returns true if the variable receives it value from the update
expression.
- setUpdated(boolean value)
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.
- add(int position, boolean val)
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.
- boolean get(int position)
Returns the boolean value at the given position.
- int indexOf(boolean value)
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.
- set(int position, boolean value)
Sets a new value for the element at the given position.
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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.
- add(int position, int val)
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.
- set(int position, int value)
Sets a new value for the element at the given position.
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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.
- add(int position, real val)
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.
- set(int position, real value)
Sets a new value for the element at the given position.
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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.
- add(int position, string val)
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.
- int indexOf(string value)
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.
- set(int position, string value)
Sets a new value for the element at the given position.
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
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:
- 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.
- 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:
- 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.
- The necessary XML Message out attributes are set either interactively
or programmatically.
- 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:
- 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.
- The necessary XML Message out attributes are set either interactively
or programmatically.
- 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:
- 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.
- 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:
- All variables inside the XML Message In object are initialised
to their initial values (if they have any initial values).
- 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:
- 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.
- 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.
- Procedure
Brings up an edit dialog for information about the detection
procedure associated with the XML; Message In object
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
- setWorkspaceColor(int color)
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:
- setLocation(int x, int y)
- int getXLocation()
- int getYLocation()
- int getHeight()
- int getWidth()
- setWidth(int width)
- setHeight(int height)
- setVisible(boolean visible)
- setWorkspaceColor(int color)
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.
- void setType(String value)
Sets the value of the Type attribute.
Returns the value of the Handle attribute.
- void setHandle(int value)
Sets the value of the Handle attribute.
Returns the value of the MustReply attribute.
- void setMustReply(String value)
Sets the value of the MustReply attribute.
Returns the value of the Origin attribute.
- void setOrigin(String value)
Sets the value of the Origin attribute.
Returns the value publish/send attribute. True means publish.
- void setPublish(boolean value)
Sets the value of the publish/send attribute.
Returns the value of the topic/destination attribute.
- void setDestination(String value)
Sets the value of the topic/destination attribute.
Returns the value of the topic/destination attribute.The same
as getDestination()
- void setTopic(String value)
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
- ( ... ) means one occurrence
- [ ... ] means zero or one occurrence
- ( ... )* means zero or multiple occurrences
- | means OR
- - means an ASCII sequence
- // line comment
Comments:
- The identifier in a method call may consist of a object
reference followed by a method reference, e.g., r1.getWidth().
It may also only consist of a function reference, e.g., max(b1,b2,b3)
- The identifier may only contain one evaluation of a
string variable name-pointer. For example, the following expression
is not allowed objectref^.attributeref^ (The same
functionality can be obtained by using an intermediary help variable.
- There are three special method calls that do not take
any arguments and do not use any argument list parentheses:
- Stepname.x returns true if the corresponding
step is active and false otherwise
- Stepname.t returns the number of scan cycles that
have elapsed since the step last was activated
- Stepname.s returns the number of seconds that have
elapsed since the step last was activated.
- The keywords S, s, X, x, P, p, N, n, A, a, V,
v, and R, r, are reserved and may not
be used as identifiers.
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:
- Raising edge event detection.
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.
- Falling edge event detection.
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.
- real max(real arg1, .... , real argn)
Returns the maximum value of its arguments.
- real min(real arg1, .... , real argn)
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.
- void writeMessage(string arg)
Writes the string in the message menu on the toolbar.
- void clearMessages(string arg)
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.
- returnType stringApply(string object, string method,
string returnType, string arg1Type, arg1Type arg1, ...., string argNType,
argNType argN)
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:
- int RGBToInt(real red, real green, real blue)
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:
- string load(string absoluteFileName)
Loads the application named by absoluteFileName into JGrafchart.
Returns the top-level workspace name of the application.
- boolean compile(string name)
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.
- void new(string class, string name, string workspace,int x, int
y)
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.
- void exec(string command)
Executes the command in a separate operating system process.
- returnType applyStaticMethod(string class, string method,
string returnType, string arg1Type, arg1Type arg1, ...., string argNType,
argNType argN)
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.
- void setCCOMServer(string IPaddress)
Sets the IP address of the CCOM server.
Returns the IP address to the CCOM server.
- void setCCOMPort(string port)
Sets the CCOM port. (Default = 3412).
Returns the CCOM port.
- void setCCOMLoginName(string name)
Sets the CCOM login name. (Default = JGrafchart)
- string getCCOMLoginName()
Returns the CCOM login name.
- void subscribe(string topic)
Subscribes to a CCOM topic.
- void unsubscribe(string 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:
- A transition condition is evaluated as a boolean expression.
- In an assignment statement it is the type of the assigned
variable that decides how the expression for the assigned value should
be evaluated. For example, consider the following stored action:
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".
- A action consisting only of a method call will be evaluated
as a real expression.
- A boolean value will return the numerical values 0 or
1 when evaluated as an integer.
- A boolean value will return the numerical values 0.0
or 1.0 when evaluated as a real.
- A boolean value will return the strings "0" or "1" when
evaluated as a string.
- An integer value will return the boolean value 1 if
the value is 1 and the boolean value 0 otherwise when evaluated as
a boolean.
- An integer value will return the corresponding real
value when evaluated as a real (ordinary Java casting).
- An integer value will return the value as a string when
evaluated as a string.
- A real value will return the boolean value 1 if the
value is equal to 1 when cast to an integer, and the boolean value
0 otherwise when evaluated as a boolean.
- A real value will be cast to an integer when evaluated
as an integer.
- A real value will return the value as a string when
evaluated as a string.
- A string value will return the boolean value 1 if equal
to "1", and the boolean value 0 otherwise when evaluated as a boolean.
- A string value will return the corresponding integer
if it can successfully be parsed to an integer, and 0 otherwise, when
evaluated as an integer.
- A string value will return the corresponding real if
it can successfully be parsed to a double, and 0.0 otherwise, when
evaluated as a real.
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:
- For each transition and exception transition two lists
are built-up. The precedingList contains references to all
steps that precede the transition. The succeedingList contains
references to all steps that succeed the transition.
- The textual expressions are parsed. During the parsing
syntax trees are generated. If the parsing is successful the syntax
trees are interpreted and all name references are resolved.
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:
- boolean x - An attribute that is true if
the step is active in the current scan.
- boolean newx - An attribute that is true if the
step should be active in the next scan.
In every scan the following operations are performed:
- Digital and analog inputs are read.
- 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.
- Phase Two: The transitions are traversed. For every
transition that is marked for firing the following operations are
performed:
- The newx attribute is set to false for
every step in the precedingList. The exit actions of these
steps are executed.
- The newx attribute is set to true
for every step in the succeedingList. The enter actions of
these steps are executed.
- Phase Three: All steps are traversed. The
following operations are performed for every step:
- The state of the step is updated by assigning newx
to x (x = newx;).
- The timer of the step (accessed through stepname.t or
stepname.s) is updated.
- If the step is currently active and will remain so also
in the next scan then the periodic actions of the step are executed.
- If the activation status of the step has changed since
the last scan the normal actions of the step are evaluated.
- For every digital output that has been modified by the
evaluation of normal actions, the total effect of the evaluation is
effectuated.
- 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:
- In a serial chain of steps and transitions at most one
transition will be fired in each scan cycle.
- The model effects how alternative transitions with non-mutually
exclusive conditions are handled. In JGrafchart all of these alternative
transitions will be fired. This conforms to the Grafcet standard. It
is also gives a fully deterministic behavior. It is good programming
practice to make sure that alternative transitions always are mutually
exclusive.
- The order in which the transitions and steps are evaluated
in the execution algorithm is irrelevant. This greatly simplifies the
implementation.
- Digital outputs modified by normal actions will behave
according to the Grafcet definition. For example, a digital output that
is set by normal actions in two succeeding steps will remain true.