Visvap 216 e
Visvap 216 e
Visvap 216 e
16
USER MANUAL
1 Introduction 5
3 General Conventions 15
5 VAP Functions 23
6 Parameters 31
6.1 VAP-Parameters 32
6.2 User-Defined Parameters and Constants 33
8 Subroutines 39
VisVAP enhances the use of freely-definable signal control logics using the
VAP language (Vehicle Actuated Programming) in offering a comfortable
tool for creating and editing program logics as flow charts. The appearance
and design of flow charts in VisVAP is similar to RiLSA 2010 (German de-
facto law for signal controls) and has been enhanced to facilitate loops and
other features. VisVAP can be used for both stage and signal group oriented
design.
The program logic is defined in VisVAP which also checks for structural
correctness and if successful exports it to a VAP file. This way the creation
of VAP files for the use with Vissim is much easier than writing VAP code
directly. Experienced programmers who like to use text editors may prefer
direct programming of VAP code. However, then the VisVAP debugger (see
chapter 10) cannot be used.
For the use of a stage oriented signal control the creation of interstages
should be done using Vissig. Vissig exports a text file (*.PUA) which includes
all signal group, stage and interstage information necessary for VAP.
The flow chart and parameters of a VisVAP document can be saved to a text
file with extension *.VV.
Your Vissim installation contains in \Examples\Training\SignalControl the
folder RiLSA_37d.VAP which contains an example from RiLSA (partly in
German language). It is very much suited to show the interaction of Vissim,
Vissig, VAP und VisVAP. Further information is contained in the VAP user
manual (PDF file).
2.1 Desktop
The Desktop of VisVAP compounds of the main window containing the
menu, tool, symbol and status bars and of one or more program windows.
Within a program window one signal control logic can be designed. For each
kind of information it contains a dedicated section. Altogether there are five
sections holding information on:
program logic (flow chart),
parameters,
arrays,
expressions and
subroutines.
Parameters table
Arrays table
Expressions table
Flow chart editor
Subroutines table
Each section is structured with rows and columns. Except for the flow chart
and arrays table the number of columns is fixed whereas the number of rows
is variable. All column widths can be adjusted individually. The row height
can be adapted for each section. The current column and row is shown in
the status bar, starting with column 0, row 0 for the top left corner.
Every VisVAP program compounds of the data of all sections. Each section
can be activated for editing by clicking the left mouse button within the
section. The name of the section currently active is shown in the title bar of
the program window.
Similar to most Windows applications the layout of program windows can be
controlled using the W INDOW menu. Sections can also be hidden there. The
size of a section can be adapted while holding the left mouse button down
when the cursor is placed on the edge between two sections and dragging
the mouse accordingly. The layout of the windows and sections may be
stored to an external layout file (see chapter 2.3.1).
All data of the program window can be saved to a VV-file. For compatibility
reasons with VAP, the filename must begin with a character and may contain
only alpha-numerical characters and the underscore sign (_).
Shortcut Action
PAGE DOWN Scroll one page down
INS Toggle switch for overwrite and insert mode. If
overwrite mode is active, the indicator OVR is
shown in the status bar.
Inserting clipboard data while in overwrite mode overwrites all existing data
without warning.
There are some preconditions and hints for smooth compilation of a VAP file
from VisVAP. These are relevant both for VisVAP and VAP. Additional
information on the VAP program language can be found in the VAP manual.
Data types
Variables defined within VisVAP can be declared as INTEGER or REAL
type. Integer variables can hold values between -2 147 483 639 and 2 147
483 639. If greater values are needed, a variable needs to be defined as
REAL type. This is done by adding .0 to the initial value. Those numbers
are represented as a usual 64 bit floating point value. In case a REAL
variable is used as an argument for a function that expects INTEGER
values, Vissim will check whether the variables decimal value is zero and if
the variable is within the valid range for integer numbers. If one of these
requirements is not met, Vissim produces a run time error message and
halts the simulation.
Operators
For expressions and conditions a range of common mathematical operators
can be used. See the table below for all possible operators within VisVAP.
Operator (VisVAP) Operator (VAP) Meaning
6 (, ) (, ) Parentheses
5 NOT, NICHT, ~, ! NOT logical NOT (unary)
4 AND, UND, &&, &, ^ AND logical AND (binary)
4 *, / *, / Multiplication, Division
4 %, \ %, \ Modulo, integer division
3 OR, ODER, v, V OR logical OR (binary)
3 +, - +, - Addition, Subtraction
(binary)
2 =, <>, <, <=, >, >= =, <>, <, <=, >, >= comparison
1 - - sign (unary)
The operator precedence is shown in the first column starting with highest
precedence (6). Parentheses must be used for expressions with unary
operators.
Examples:
The program logic is designed as flow chart within the chart section. It
consists of columns and rows and is internally restricted to 20 columns and
500 rows. Bigger charts can be designed using subroutines.
Extensive symbol texts can be split into two or more lines using
CTRL+ENTER.
Insert lines
At first the symbol type Line needs to be selected (button or shortcut
CTRL+SHIFT+L). Then select the start cell of the line with the left mouse
button. After the right mouse button has been pressed at the destination cell
of the line it will be drawn automatically.
VisVAP allows the linking of several symbols with one line at once. Most
likely symbols of a VisVAP logic will be placed in consecutive order from top
to bottom and/or left to right. Partial lines can be drawn consecutively until
the desired path has been established. If flow of control is directed towards
left or up in most cases a small detour needs to be inserted because of the
conventions for entries and exits of symbols (see 4.1).
Arrows
Because of the conventions mentioned above arrows are not necessarily
required. As default for clarity reasons the arrows of all entry lines of
symbols are shown. While debugging the flow chart it may be helpful to
show the arrows of all cells. To achieve this, the command SHOW ALL ARROWS
may be used. These are the functions for switching arrows on and off:
Symbol Element Description
Show arrows Toggles the display of arrows of all entry lines
of symbols (on by default).
Show all Toggles the display of all arrows within the
arrows chart. This may be useful for finding wrong
connections in flow charts when checking the
flow chart results in an error message.
Example: The following steps describe how to draw the lines as shown
above:
Mark start cell (condition) by clicking the left mouse button (1L). Continue to
draw a line down by pressing the right mouse button in the cell below the
condition (2R). Another right mouse click at the far end (3R) finishes the
first line. To draw the second line two mouse clicks are sufficient: Starting
again from the condition (mark with left mouse click, 4L) the line will
automatically be drawn through the statement and round the corner as
soon as the right mouse button will be pressed at position 5R since VisVAP
first draws to the rightmost cell and then moves down to finish the line.
Bridges
When two lines cross each other VisVAP automatically creates a bridge
since crossings of lines would be ambiguous. The figure below shows a
bridge (all arrows are shown).
Deleting lines
Cells containing lines only can be deleted by simply pressing the DEL key or
using the command EDIT DELETE. After the first deletion of a line the same
command can be used again to update the connecting lines of the
surrounding cells. This is especially useful when fragments of lines are still
left in the surrounding cells.
When a symbol (not a line) is deleted, all corresponding lines (or line
fragments) in the same cell will be deleted as well.
VAP functions are listed in groups. After a group has been chosen all
corresponding VAP functions are shown in a list. While browsing the list of
functions a short information on each function is shown below the list boxes.
A selected function can be inserted at the current cursor position within the
edit box by using the Paste button. There is a choice to enter either the long
or short name of a function. When using the Paste functionality VisVAP
inserts the function with the exact syntax of VAP. It only needs to be
completed with the function arguments.
It is also possible to insert more than one function in the edit box and to
combine those using operators (see 3). For line feeds within the symbol,
simply enter Ctrl+ENTER at the corresponding positions within the edit box.
When the window is closed the contents of the edit box is copied into the
symbol.
Below follows a list of all VAP functions, commands and parameters
available in the current version. There is a choice of a long or short syntax of
a function. For clarity reasons the argument lists have been omitted for the
short names. They are identical to those of the long names.
For further information on VAP functions please refer to the VAP user
manual.
6.1 VAP-Parameters
COMPILE - VAP PARAMETERS opens the window VAP Parameters. Here the
Controller frequency of the signal controller is defined. Possible values range
from 1 to 10. When generating a VAP file, this parameter is added to the
VAP file automatically.
The controller frequency defines how often within one simulation second the
VisVAP logic is executed. This value must correspond to the simulation
resolution defined in Vissim, i.e. the simulation resolution must be equal to or
a multiple of the controller frequency. Possible combinations are e.g.
Controller frequency Simulation resolution
1 1
2 2
2 4
2 8
2 10
5 5
5 10
10 10
All signal controllers within the same simulation need to have the same
controller frequency.
Array reference
Constants defined with an integer value (not a reference) between 1 and
1000 can also be used as a reference for the definition of array dimensions.
If a constant is referenced by an array, then it cannot be deleted or
overwritten. However, its name can be modified (and is modified
automatically in all references as well) and also its value can be changed to
any integer value between 1 and 1000. Upon value change the array is
automatically adapted.
The variable init is initialized with 0 at program start. Hence the condition
NOT init is true and so the value 5 is assigned to Var1 and 8 to Var2.
Before continuing with the program execution, the variable init needs to
be set to 1 so that in all subsequent program runs the condition NOT init
will be false and the initialization branch will not be executed again.
Arrays
Array variables need to be defined in the Array table. After entering an
identifier name, the array can be defined either one- or two-dimensional by
entering a dimension value in the corresponding column. Alternatively, the
identifier of a constant defined in the Constants table may be used (certain
restrictions apply - see the Constants section for details).
The number of columns Dim1 needs to be entered before the optional
number of rows Dim2 may be defined. Then VisVAP automatically expands
the table to allow for entering all initial values. By default, all field cells of an
array are initialized with 0. Empty fields that do not belong to an array
definition cannot be edited. The dimensions of an existing array can be
changed simply by entering a new value to the corresponding dimension. As
a result the array will automatically grow/shrink accordingly. This also
happens if a referenced constant is modified in the Constants table.
Copy and paste functions can only be used in cells that contain values or
comments. Rows can be inserted only between identifiers of different arrays.
An array is deleted by deleting its identifier. Consequently VisVAP deletes all
cells that belonged to that array.
7.2 Expressions
To avoid long lines of text or expressions within symbols, VisVAP offers the
definition of expressions. An expression is for example a combination of
logical terms which is tested in a condition. An expression is defined in the
Expressions table by entering its identifier in the first column and the
expression itself in the second column. It is also possible to launch the VAP
functions library from within the second column (see chapter 5). The last
column can take any comments for documentation purposes.
The width of columns can be adjusted individually using VIEW - ADJUST
DIMENSIONS.
Expressions are evaluated each controller time step prior to the run of any
other parts of the logic. Hence it is ensured that the expressions are always
updated before the main program is executed.
Since all variables in VisVAP are global, they can be accessed both in a
main program and in all subroutines. On the other hand care needs to be
taken that all identifiers (e.g. of parameters, expressions, variables and
subroutines) of all parts of the program are unique. If there are duplicate
identifiers with different definitions VisVAP generates an error message
when trying to compile the program to VAP code.
As the debug mode is an interaction between Vissim and VisVAP there are
occasions when either application does not respond immediately to mouse
or keyboard input. This is a normal behavior and originates of the fact that
only one of both applications can have control at the same time.
not been defined within the General column as these remain constant.
The current values of arrays are displayed directly at the corresponding
position within the Arrays section (temporarily replacing the initial
values). After finishing the debug mode, the original tables are restored.
The number of decimal places displayed of the current debug values of
parameters, variables and expressions can be changed using the + and -
keys of the numeric keypad. Possible values are 0 to 3. The settings are
stored for each section individually and are saved to the INI file.
The editor colors described in this chapter apply only to the main debug
window. If any subroutines are opened while in debug mode the colors may
be differently
When debug mode is active all VisVAP files related to that signal control
logic are locked and cannot be modified except for toggling breakpoints.
If the Vissim is in Single Step mode and the number of time steps is greater
than 1, the SIMULATION SINGLE STEP button needs to be pressed as often
as the simulation time in the status bar is increased. Because the VAP
signal control logic is activated according to the controller frequency (not
necessarily every simulation time step) all intermediate time steps will not
affect the display of the signal logic.
10.3 Breakpoints
During continuous debug mode breakpoints stop the program execution as
soon as a command is approached that is marked with a breakpoint.
Breakpoints may be defined or removed by selecting the desired cell and
choosing DEBUG - TOGGLE BREAKPOINT. The symbol of a command where a
breakpoint is defined is filled with light red. If a breakpoint is reached during
a debug run the corresponding symbol is filled with bright red color.
Breakpoints may be defined or removed also when debug mode is active.
They are stored in the VisVAP file.
When closing the VisVAP file or the VisVAP application while the debug
mode is active a sequence of error messages will occur in Vissim. In most
cases these messages can be confirmed by Ok and Vissim will stop the
simulation run. However, it is not recommended to stop the debug mode in
that manner as data loss may occur.
All data of a VisVAP program can be saved to a test file with extension *.VV.
For compatibility with the VAP program language the filename must begin
with a letter and may then only contain letters, numbers or the underscore
sign (_).
It is not recommended to change the contents of a VisVAP file directly since
then it is not always guaranteed that it can be opened in VisVAP again and
so loss of data may occur. If it is still necessary to alter the contents of a
VisVAP file directly (e.g. to adapt data from other programs to be imported in
VisVAP) the file can be edited in a text editor.
The structure of a VisVAP file looks like the following:
Title row including VisVAP Version number (e.g. VISVAP VERSION 2.16-00)
Controller frequency (e.g. FREQUENZ 4)
Flow chart block containing one row for each symbol
(e.g. Z3|S1|U|Calculate_Expressions|10100011|0#)
Parameters block consisting of
- block identifier (KONSTANTEN)
- one row per table row (e.g. DK1|1||||||||#)
Arrays block consisting of
- block identifier (ARRAYS)
- one row per table row
(e.g. DU||8|11|13|15|17|16|14|12|10|Display unit no#)
Expressions block consisting of
- block identifier (AUSDRUECKE)
- one row per table row
(e.g. L1|headway( DK5 ) >= 3.0|min Headway#)
Subroutines block consisting of
- block identifier (UPROG)
- one row per table row
(e.g. Calculate_Expressions|ril_sub.vv|# )
Optional layout file block consisting of
- block identifier (INI-DATEI)
- filename (e.g. C:\Visvap\Doc\ril_d21e.INI)
The column separator is ASCII sign 124 (|) and the line end marker is ASCII
sign 35 (#). These characters must not been used in any character string. A
row within the flow chart block contains its position (column no. after S, row
no. after Z), its type (one of A,B,L,S,T,U,Z) and encoded information about the
connecting lines and breakpoints.