Manual - VisVAP 216 ENG

VISVAP 2.
16
USER MANUAL
PTV Planung Transport Verkehr AG, Karlsruhe, Germany
Last update: October 2017

Contents
1 Introduction 5
2 Working with VisVAP 7

2.1 Desktop 8
2.2 Keyboard Shortcuts 10
2.3 Screen Layout, Font and Symbol Sizes 12
2.3.1 Layout Files 12
2.3.2 Column Widths and Row Heights 13
2.4 Find and Replace 15
3 General Conventions 17
4 Drawing the Flow Chart 19

4.1 Symbol types 20
4.2 Connection Lines and Arrows 23
5 VAP Functions 25
6 Parameters 33
6.1 VAP-Parameters 34
6.2 User-Defined Parameters and Constants 35
7 Variables, Arrays and Expressions 37

7.1 Variables & Arrays 38
7.2 Expressions 39
8 Subroutines 41
9 Check of Flow Chart and Generating a VAP File 43

9.1 Structural Consistency 44
9.2 Generating a VAP File 45
9.3 Syntactic Correctness 46
10 Debugging a Signal Control Logic 47

10.1 Starting the Debug Mode 48
10.2 VisVAP Debug Commands 50
10.3 Breakpoints 52
VisVAP 2.16 © PTV AG 2

10.4 Leaving the Debug Mode 53
11 Structure of a VisVAP File (VV-File) 55

1 Introduction
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-based and signal group oriented
design.
In VisVAP the program logic is defined and checked for structural correctness.
If successful, it exports to a VAP file. This way the creation of VAP files for the
use with Vissim is much easier than writing VAP program 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-based signal control we strongly recommend the use
of Vissig to create the interstages. Vissig exports a text file (*.PUA) which
includes all signal group, stage and interstage information necessary for VAP
to be run.
The flow chart and parameters of a VisVAP document are saved to a text file
with extension *.VV.
Your Vissim installation contains several VAP and VisVAP examples in the
directory \Examples Training\SignalControl. There you also find the folder

‘Knoten 3-armig RiLSA.VAP’ which contains an example from the German
RiLSA (in German language).

2 Working with VisVAP

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 tables 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

Desktop
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 (‘_‘).

2.2 Keyboard Shortcuts

VisVAP uses several standard shortcuts and additional shortcuts for
convenience:
Shortcut Action
ALT + O Sets all columns in all sections to their optimum
width
Double click on a word Marks current word
CTRL + SHIFT + ← Marks current word from cursor position (left)
CTRL + SHIFT + → Marks current word from cursor position (right)
SHIFT + END Marks to end of row
CTRL + X, SHIFT + DEL Cut out marked text
CTRL + C, CTRL + INS Copy marked text
CTRL + V, SHIFT + INS Paste of cut or copied text
CTRL + F Opens Find and Replace window
CTRL + M Opens Adjust Dimensions window
CTRL + U Opens subroutine
F2 Edit text of current symbol
SHIFT + F2 Opens the VAP functions window
F3 Debug Mode only: Step In
SHIFT + F3 Debug Mode only: Step Out
F4 Debug Mode only: Executes the next command
F5 Debug Mode only: Switches into continuous mode
F7 Insert Column(s)
SHIFT + F7 Delete Column(s)
F8 Insert Row(s)
SHIFT + F8 Delete Row(s)
F9 Toggle parameters table on/off
SHIFT + F9 Toggle flow chart section on/off
CTRL + F9 View chart only
F10 Toggle arrays table on/off
F11 Toggle expressions table on/off
F12 Toggle subroutines table on/off
CTRL + F12 View all sections

Keyboard Shortcuts
Shortcut Action
PAGE UP Scroll one page up
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.

2.3 Screen Layout, Font and Symbol Sizes

VisVAP offers several functions to adapt the layout of each section
individually. There are functions for changing the font size, column width, row
height and window and zoom size. All sections can be split vertically and
horizontally. The page setup parameters contain zoom factors to adapt the
size of the chart and tables for the printing.
2.3.1 Layout Files

A layout file contains information about the screen layout including column
widths and print settings. The table below shows most of the information that
will be stored in a layout file (all the rows where *.INI is ticked).
If the menu option VIEW - AUTO SAVE LAYOUT is active, the layout is
automatically saved to a layout file (with the same filename as the VisVAP file)
upon closure of a VisVAP file. When loading a VisVAP file, the system looks
for the optional layout filename included in the VisVAP file and tries to open it.
If such a file cannot be found it looks for a layout file with the same name as
the VisVAP file and if existing, loads its layout information. If both attempts
fail, the current standard layout is used. If the AUTO SAVE LAYOUT option is not
activated, the filename of the last INI-file loaded (or saved) is saved within the
VisVAP file.
Additionally, layout files can be saved and loaded manually using VIEW - SAVE
LAYOUT... and LOAD LAYOUT...
*.INI Menu command Action
 VIEW - Adjusting the column width for each column
ADJUST DIMENSIONS individually and the general row height (relative
to 100% Zoom)
 VIEW - ZOOM – Zoom in by 20% (of previous size)
ZOOM IN
 VIEW - ZOOM – Zoom out by 20% (of previous size)
ZOOM OUT
 VIEW - ZOOM - Adjusting the view size using a custom zoom
CUSTOM ZOOM factor
 VIEW – FONT - Changing font name and size (relative to 100%
SELECT FONT Zoom)
 VIEW - FONT - Increase the font size by ca. 20% (relative to
LARGER FONT previous size)
 VIEW - FONT - Reduce the font size by ca. 20% (relative to
SMALLER FONT previous size)

Screen Layout, Font and Symbol Sizes
*.INI Menu command Action

 VIEW - Switches grid on or off (default for section 2, 3
GRID and 4)
VIEW - ARROWS – Adjusting the style of arrows (narrow, wide,
ARROW STYLE solid/hollow)
FILE - PRINT SETUP Settings of page layout for printing and printer
settings
 FILE - PAGE SETUP Settings of header and footer, margins, line
width and zoom factors for printing
 W INDOW ... Adjusting the window positions, sizes and splits
2.3.2 Column Widths and Row Heights

The Auto Column Width mode (toggled by VIEW - AUTO COLUMN W IDTH)
provides a comfortable way of editing the chart and tables as column widths
are adapted automatically according to the largest text within each column.
Column widths and row heights may also be adjusted individually using the
menu command VIEW - ADJUST DIMENSIONS (or Ctrl+M). The window Adjust
Dimensions opens for data input.

The following options are available:

► The width of each column that is currently shown can be set to a user-
defined value (the smallest possible value is 1).
► The row heights can be defined for each window section separately.
► ALL W IDTHS SAME AS COLUMN 0: Sets all subsequent column widths to the
width of column 0.
► OPTIMAL COLUMN W IDTH: Sets all column widths of the corresponding
window section to the width that is needed in order to completely display
the largest text of each column.
► PREVIEW : Applies the currently entered dimensions to all views in order to
see their impact. When pressing the CANCEL button the original widths will
be restored.

Find and Replace
2.4 Find and Replace

The Find and Replace function provides searching for an expression, a
variable or a VAP function. You can use special characters. Regular
expressions cannot be used.
Using the menu command EDIT – FIND AND REPLACE (Strg+F) opens the Find
and Replace window:
Restrict the search area:

• Current window: Restricts the search to a diagram or a table. The
search is started on the left side line by line.
• Current file: Restricts the search to a diagram and the tables of a
vv-file. The search order corresponds to the display order of the
objects: diagram, parameters, arrays, expressions, subprograms.
• Current file with subprograms: a diagram, all tables and all files of
the linked subprograms.
You can replace the search phrase. Replace all replaces all occurrences of
the search phrase.
Further search criteria: Case sensitive and Match whole word only search
functions are available.
The first search result is shown and selected automatically.
The Find and Replace window cannot be opened, when the debug mode is
active. If the Find and Replace window is opened when the debug mode is
started, VisVap closes the window Find and Replace automatically.

3 General Conventions
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.
Identifiers of parameters, expressions, variables and subroutines

Following conditions apply to these identifiers:
1. The first character must be a letter
2. All subsequent characters must either be letters, numbers or the
underscore sign (‘_‘).
3. The length of an identifier must not exceed 32 characters.
4. There is no difference in using upper- or lowercase. However, it is
advisable for clarity reasons to use CAPITALS for parameters and
lowercase for variables and expressions. Identifiers of VAP functions and
commands are inserted with the first character being a capital letter.
Identifiers of signal groups and detectors

Within Vissim signal groups and detectors are represented by integer
numbers. Consequently arguments of corresponding VAP functions (such as
set_sg( 9 )) also need to be integer numbers. For the use of alphanumeric
identifiers parameters may be defined for signal group and detector numbers.
Example: Detector DV_12 can be used rather than 12 (which is its Vissim
representation) if DV_12 is defined as a parameter with the value 12.
In VAP the integer range of signal group and detector identifiers is restricted
to 1...999. Thus in Vissim all signal groups and detectors that will be used in
VisVAP must be defined as values within that range.
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 variable’s 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.

3 General Conventions
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.
In order for VisVAP to recognize operators correctly, blanks have to be

inserted before and behind the following operators: AND, OR, v, V, NOT.
Examples:
wrong L1ANDL2vL3, L1AND L2v L3, L1 ANDL2 vL3,
correct L1 AND L2 v L3, L1&L2 v L3

4 Drawing the Flow Chart
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.

4.1 Symbol types

In VisVAP a flow chart can be designed using lines and seven types of
symbols. These include definition of start and end of the program, conditions,
actions and calls of subroutines. Except for page separators lines can enter a
symbol only from the top and/or left (terminus symbols: from top only) and exit
only towards the right or down (conditions: towards right AND down, terminus:
down only). Page separators may be inserted in any vertical line thus having
either a top entry and bottom exit or vice versa.
A symbol type can be selected by using a shortcut (e.g. pressing Ctrl+Shift+A
simultaneously) or by clicking the corresponding button in the symbol bar.
After a symbol type has been selected symbols can be placed within the chart
by double-clicking the left mouse button or pressing ENTER. Subsequently a
symbol text may be entered. If the AUTO COLUMN W IDTH mode is active, the
column width is adjusted automatically after the text has been entered. For
expressions and conditions the VAP functions window can be launched using
the context menu (see 5).
Extensive symbol texts can be split into two or more lines using CTRL+ENTER.
Below follows a description of all the symbol types:

Sym Shortcuts Element Description
bol
CTRL+SHIFT+M Terminus Defines the start and the end of the
program logic. Every program needs
to have exactly one start and exactly
one end. Optionally a comment can
be entered within the symbol. (e.g.
‘START‘, ‘END‘).
CTRL+SHIFT+A Statement Use for commands and assignments.

E.g. countZ1 := 3 assigns the value 3
to the variable countZ1. For
assignments use ‘:=‘ rather than ‘=’.
At least one statement must be
entered within the symbol. If more
than one statement is entered, the
statements need to be separated by
semicolons (;). No semicolon must
be entered after the last statement.

Symbol types

bol
Example: Both the following statements assign the value 0 to the variables
L6 and L8. When typing L6 := 0; CTRL+ENTER L8 := 0 the statements will
appear within the symbol as follows:
CTRL+SHIFT+B Condition Use for logical conditions. If the

condition is true the next command to
the right will be executed.
Consequently the branch leading
down represents the false-case.
Since this is unambiguous there is no
labeling of the branches.
Example: In case the occupancy time of detector T23 (OccT( T23 )) is
greater than 0 flow of control continues towards the right, otherwise down.
CTRL+SHIFT+U Call of Calls the corresponding subroutine.

subroutine Within the section of assignments of
subroutines the subroutine must be
declared and assigned to a valid
filename. The structure of a VisVAP
subroutine logic does not differ from
the structure of a „normal“ program
logic. That means, an existing
VisVAP program logic can simply be
used as a subroutine by assignment
within the subroutines section. If no
filename has been entered for a
subroutine identifier an error
message will be displayed during the
program check.
Example: Within the subroutines section the identifier ‘PT_MODUL‘ is
assigned to a VisVAP file (here: C:\VISVAP\DOC\PT_MODUL.VV).
The subroutine ‘PT_MODUL‘ is called within the flow chart like that:


bol
CTRL+SHIFT+S Page Defines a page break on the printout

separator of the chart. It may only be inserted
in a vertical line. A page separator
does neither affect the display on the
screen nor the flow of control but will
affect the printout. A short text may
be entered within the symbol.
CTRL+SHIFT+T Text Optional commentary text for

documentation purposes. It is
ignored by flow of control.
CTRL+SHIFT+L Line Use for drawing lines to connect

symbols. A line is drawn from the
currently selected cell (select with the
left mouse button) to the cell where
the right mouse button is clicked.
Refer to 4.2 for detailed information.

Connection Lines and Arrows
4.2 Connection Lines and Arrows
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
If 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 useful to remove line fragments from surrounding cells.
If a symbol (not a line) is deleted, all corresponding lines (or line fragments) in
the same cell will be deleted as well.

5 VAP Functions
In contrast to standard drawing software products in VisVAP all available VAP

functions and commands can be chosen from the VAP Functions window for
the use within conditions, statements and expressions. The window can be
launched from any condition or statement within the chart or from the second
column of the expressions section using
► context menu (right mouse button) or
► Shift+F2 or
► Edit - VAP-Functions...
VAP functions are listed in groups. After a group is selected all corresponding
VAP functions are shown in a list. While browsing the list of functions, a short
information text on the function currently highlighted 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. If using the ‚Paste‘ functionality VisVAP
inserts the function with the exact syntax of VAP. It only needs to be completed
with any function arguments.
It is also possible to insert more than one function in the edit box and to
combine those using operators (see chapter 3). For a line feed within the
symbol, simply press Ctrl+ENTER at the desired position. As the window is
closed the contents of the edit box is copied to 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.

5 VAP Functions
Long name Short Meaning

Any_interstage_active Aia Returns 1 if any interstage is active,
otherwise 0.
Clear_front_ends( <no> ) Cfe Clears the number of detected vehicle
front ends on detector <no>.
Clear_rear_ends( <no> ) Cre Clears the number of detected vehicle
rear ends on detector <no>.
Current_state( <no>, Cst Returns 1 if the current state of signal
<display> )
group <no> is <display>, else 0.
Cycle_second T Returns current cycle second.
Cycle_second_between Csb Returns 1 if the current cycle second (t)
( <begin>, <end>, <op.type> )
is between <begin> (b) and <end> (e),
otherwise 0. <operatortype>
determines the exact meaning of
"between" (including or excluding): 0: b
< t < e;
1: b < t <= e; 2: b <= t < e; 3: b <= t <=
e.
Cycle_time Tc Returns current cycle length.
Desired_state( <no>, Dst Returns 1 if the last desired state (set
<display> )
by Interstage or Set_sg commands) of
signal group <no> is <display>, else 0.
See Set_sg for a list of possible values
for <display>.
Detection( <no> ) Det Returns 1 if the impulse memory of
detector <no> is 1 (i.e. a vehicle front
end has been detected) or a vehicle is
on the detector, else 0.
Front_ends( <no> ) F_e Returns the number of detected vehicle
front ends on detector <no> (the total
amount since the last call of
clear_front_ends()).
Headway( <no> ) Hdw Returns headway of detector <no>
since last activation
Headway10( <no> ) Hdw10 Returns headway of detector <no>
since last activation in tenth of seconds
(10 times the value of “Headway”).
In_Frame( <no> ) InFr Returns the elapsed time since the start
of the frame of line <no> in the current
frame plan (according to the current
active program number).

Intergreen(<sg1>, <sg2>) IntG Returns the intergreen time between
signal groups <sg1> and <sg2> as
defined in the PUA file.
Interstage( <stage1>, Is Runs an interstage
<stage2> )
Interstage_active( <stage1>, IsA Returns 1 if any interstage is active,
<stage2> )
otherwise 0.
Interstage_duration( <stage1>, IsT Returns the current second of the
<stage2> )
interstage or 0 in case the interstage is
not active
Interstage_length( <stage1>, IsL Returns length of interstage.
<stage2> )
Marker_get( <no> )) MGet Returns the value from input channel
<no> .
Marker_put( <no>, <value> ) MPut Writes the <value> to the output
channel <no>.
Notrace Notrace Stops trace mode.
Occup_rate( <no> ) OccR Returns smoothened occupancy rate of
detector <no> [0..1].
Occupancy( <no> ) OccT Returns the elapsed time since detector
<no> has been activated or 0 if no
vehicle is present at end of time step.
Occupancy10( <no> ) OccT10 Returns the elapsed time since detector
<no> has been activated in tenth of
seconds (10 times the value of
“Occupancy”) or 0 if no vehicle is
present at end of time step.
P_interstage( <no>, <sec> ) Pis Calls the interstage <no>, starting in its
second <sec> (usually 0).
P_interstage_active( <no> ) Pisa Returns 1 if interstage <no> is active,
otherwise 0.
P_interstage_duration( <no> ) Pist Returns the current second of the
interstage <no> according to its
definition in the PUA file.
P_interstage_length( <no> ) Pisl Returns the static length of the
interstage <no> as defined in the PUA
file.
Parameter( <no> ) Par Returns the value of parameter P<no>
as defined in the PUA file.

5 VAP Functions

Presence( <no> ) Call Returns 1, if detector <no> was
activated since last check. In the next
time step it will be reset automatically.
Prog_active PAct Returns the no of active program
selected in Vissim [1..16]
Rear_ends( <no> ) R_e Returns the number of detected vehicle
rear ends on detector <no> (the total
amount since the last call of
clear_rear_ends()).
Record_value( <no>, <value> ) RecVal Transmits <value> to Vissim for output
in the SC/detector record in the column
"variable no. <no>"
Remaining_intergreen( <no> ) Rig Returns the time in seconds until signal
group <no> can get green according to
the intergreen matrix.
Reset( <timer> ) Rst Resets timer <timer> to 0.
Set_cycle_second( <sec> ) SetT Sets the current cycle second to <sec>
[1...999]
Set_des_speed( <desSpDecNo>, Sdsp Assigns the desired speed distribution
<vehClassNo>, <desSpDistrNo> )
<desSpDistrNo> to the vehicle class
<vehClassNo> in the desired speed
decision <desSpDecNo>.
Set_prog( <no> ) Sprg Sets the no of the active program to
<no> [1..16].
Set_route( <routDecNo>, Srou Sets the relative flow of the route
<routeNo>,<flow> )
<routeNo> of the routing decision
<routDecNo> in the current time
interval (or the next one, if no interval is
currently active) to <flow>.
Set_sg( <no>, <display> ) Ssg Sets display of signal group <no> to
<display> including all transitions.
<display> can have one of the following
values:
red amber green
red_f amber_f green_f
off redamber redgreen_f
off_red greenamber

Set_sg_direct( <no>, Ssgd Sets display of signal group <no>
<display> )
immediately to <display> without any
transitions and disregarding minimum
display times.
set_stop_time_dist( <stop_no>, Sst Selects the dwell time distribution
<veh_cl_no>, <dist_no> )
<dist_no> for vehicle class
<veh_cl_no> at the stop sign
<stop_no>.
Sg_green( <no> ) SetG Sets signal group <no> to green.
Sg_red( <no> ) SetR Sets signal group <no> to red.
Sqrt( <value> ) - Returns the square root of <value>.
Stage_active( <stage> ) StgA Returns 1, if stage <stage> is active
otherwise 0.
Stage_duration( <stage> ) StgT Returns elapsed duration of stage
<stage> or 0 if stage is not active.
Start( <timer> ) - Start Timer <timer>.
Start_at( <timer>, <value> ) - Starts the timer <timer> with starting
value <value>. The first timer
increment will take place in the next
simulation second.
Stop( <timer> ) - Stops Timer <timer> without resetting
it.
T_free ( <no> ) Tf Returns the time elapsed since the end
of red of the signal group <no> (green
plus red/amber time).
T_green( <no> ) Tg Returns elapsed green time of signal
group <no> or 0 if signal group is not
green.
T_green_min( <no> ) Tgmin Returns minimum green time of signal
group <no>.
T_red( <no> ) Tr Returns elapsed red time of signal
group <no> or 0 if signal group is not
red.
T_red_min( <no> ) Trmin Returns minimum red time of signal
group <no>.
T_stop( <no> ) Ts Returns the time elapsed since the end
of green of signal group <no> (red time
plus amber time).

5 VAP Functions

Tele_calling_point( <no> ) TeCPt Returns the calling point number from
the telegram number <no>.
Tele_count TeCnt Returns the number of telegrams
received in the current simulation time
step.
Tele_course( <no> ) TeCrs Returns the course number from the
telegram number <no>.
Tele_delay( <no> ) TeDel Returns the delay in seconds from the
Tele_line( <no> ) TeLin Returns the line number from the
Tele_man_direction( <no> ) TeDir Returns the code for manual direction
from the telegram number <no>.
Tele_passengers (<no>) TePas Returns the number of passengers
from public transport telegram number
<no>.
Tele_prio( <no> ) TePri Returns the priority value from the
Tele_route( <no> ) TeRou Returns the route number from the
Tele_tram_length( <no> ) TeLng Returns the tram length from the
Test_intergreen( <no> ) Tig Returns 1 if all intergreen times towards
signal group <no> are completed so
that the signal group may be switched
to green.
Trace( all ) - Writes program commands and values
of all variables to trace file.
Trace( command ) - Writes program commands to trace file.
Trace( variable ) - Writes values of all variables to trace
file.
Trace( variable( <var> )) - Writes value of variable <var> to trace
file.
Trace( variable( <var1>, - Writes values of variables <var1> and
<var2> ))
<var2> to trace file.

Veh_length( <no> ) V_l Returns the length of the last vehicle
that passed detector <no> within the
current controller time step resp. 0 if no
vehicle was detected during the last
controller time step.
Velocity( <no> ) V Returns the speed in m/s of the last
vehicle that was detected by detector
<no> in the current time step or 0 if no
vehicle was detected in this time step.
For further information on VAP functions please refer to the VAP user
manual.

6 Parameters
There are two types of parameters:

► VAP parameters (system defined)
► User-defined parameters and constants.

6 Parameters
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.

User-Defined Parameters and Constants
6.2 User-Defined Parameters and Constants

All parameters that are referenced in the flow chart and in Expressions must
be defined in the Parameters table. By definition, the value of a parameter
cannot be changed during program execution except for different parameter
sets for various signal programs (see below). All parameters are global.
The parameters table consists of 11 columns. The first column contains the
identifier of the parameter. If the corresponding value is defined in the second
column (General) it is used regardless of the currently selected signal
program. If one or more values are entered in the subsequent 8 columns
instead, the value changes according to the signal program which is currently
active. The last column contains an optional comment. The width of columns
can be adjusted individually using VIEW - ADJUST DIMENSIONS.
See the illustration below as an example:
If the signal program is changed during a running simulation a different

parameter set is used for all parameters affected. The signal program can be
changed either within VisVAP by using the VAP function set_prog() or
manually within Vissim by choosing a different program number in the signal
controller. VisVAP offers parameter sets for 8 different signal programs (1..8)
and uses program 1 by default.
Constants can also be defined as a reference to another constant that has a
value defined for General. Example for T_QUEUE_2 (see table above):
Instead of entering ‘8’ as a value, ‘T_QUEUE_1_5’ could be entered instead.
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.

7 Variables, Arrays and Expressions

7 Variables, Arrays and Expressions
7.1 Variables & Arrays

In VisVAP and VAP all variables are global. A variable does not have to be
declared prior to use. It will automatically be initialized with 0.
User-defined initialization of non-array variables can be done using

assignments which are only executed once (during the first program run).
This can be achieved using the following structure:
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.

Expressions
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.
Expression values remain unchanged during a single controller time step.

I.e., if the value of a term that is referenced by an expression does change,
the expression reflects these changes only in the subsequent controller time
step.
See the illustration below as an example:

8 Subroutines
VisVAP supports modular programming using subroutines. In VisVAP the

structure of a subroutine does not differ from a main program. A program
simply becomes a subroutine by declaring it in the Subroutines table. That is,
defining an identifier and assigning a filename to it (optionally including a
path). Within the flow chart a subroutine can be called using a symbol of type
„subroutine“. A subroutine may contain other subroutines.
The use of subroutines is well suitable for extensive programs that consist of
several modules or if a part of a program will be executed more than once
within the same run (also using different parameters).
Since all variables in VisVAP are global, they can be accessed both in a
main program and in all subroutines. On the other, it is the users
responsibility to ensure that all identifiers (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.
Although in VisVAP there is no option to define arguments or parameters for

subroutines, data can be exchanged between the main program and a
subroutine using (global) variables.

9 Check of Flow Chart and Generating a VAP File

9.1 Structural Consistency

After entering a VisVAP program (including definitions of parameters,
expressions and subroutines) the data should be saved to disk. Then using
COMPILE - CHECK FLOW CHART the VisVAP program structure can be checked.
If an error occurs the corresponding cell is highlighted and an error message
is displayed. During a program check all other program files referenced by the
main program are opened to be included in the check.
Checking the VisVAP program will detect:
► Fragmental lines
► Errors in the line-work
► Missing or unnecessary symbols in the flow chart
► Missing symbol text
► Missing subroutines and subroutine definitions
► Duplicate identifiers
If no errors are detected, the message „Flow Chart successfully checked“ is
displayed.

Generating a VAP File
9.2 Generating a VAP File

VisVAP generates a VAP program file for the use with Vissim by USING
COMPILE – GENERATE VAP-FILE. The VAP file then can be accessed directly
from within Vissim as the logic file for a vehicle actuated signal control using
VAP method. Just before a VAP file is generated the VisVAP program is
checked automatically even if it has been checked before. This happens since
there is no way to detect any changes within external (subroutine) program
files.
The following sequence of exporting data is used during the generation of a
VAP file:
1. Program title
2. Parameters (incl. VAP parameters and all parameters of subroutines)
3. Array variables
4. All subroutines that are referenced by the flow chart. Subroutines which
are defined but not used throughout the VisVAP program are not exported.
Within a subroutine at first all expressions are exported and thereafter the
main part of the subroutine.
5. Signal-program-dependent parameters
6. Expressions
7. Logic of main program (flow chart)
The VAP file gets the same name as the VisVAP file but the extension VAP.
It will be saved to the same directory as the VisVAP file. In case there is
already a file existing like the one to be generated, VisVAP prompts to
overwrite this file.

9.3 Syntactic Correctness

As far as all symbols and tables within the VisVAP program contain
syntactically correct expressions (as expected by VAP program language) the
generated VAP file can be executed error-free within Vissim. However it might
be the case that a VisVAP program was exported without error message to a
VAP file but trying to run it from within Vissim results in an error. These errors
are generated by the VAP compiler that checks both the PUA and VAP files
for syntactical correctness. Follow the instructions below to find and eliminate
the error:
1. Check, which file the error message refers to. If it refers to a PUA-file there
is no need to change the VisVAP program. If it refers to the VAP file that
you generated before, continue with step 2.
2. Open the VAP file with a text editor and go to the row shown in the error
message.
3. At the beginning of the row there is a label which looks like D**S**Z*** or
S**Z*** (* stands for a number between 0 and 9). This label refers to the
position of the symbol within the VisVAP program that corresponds to the
line of code in the VAP file. In case the label starts with D** the symbol is
found in a subroutine. The filename of the subroutine can be found as
comment at the beginning of the current program block (within the row that
starts with SUBROUTINE). The number behind ‚S‘ defines the column number,
the one after ‚Z‘ the row. Example: S01Z046 refers to column no.1 and row
no. 46. Please note that the numbering of columns and rows in VisVAP is
zero-based.
4. Open the respective VisVAP file.
5. Correct the contents of the symbol at the position shown in (3.) according
to the error message displayed.
6. Save the VisVAP file and generate a new VAP file. If the message „VAP-
file has NOT been generated“ appears, most likely the VAP error message
window is still open and so the VAP program run has not been terminated
yet. Close the VAP error message and all subsequent messages. Then
generate the VAP file and run the simulation again.

10 Debugging a Signal Control Logic
VisVAP offers a comfortable way of displaying the current state of a VAP

signal control logic (that has been created with VisVAP) during a Vissim
simulation run. This is accomplished by providing several commands to
visualize the control flow and by displaying the current values of all parameters
and expressions.
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 from the fact that
always only one of either application can be in control.

10.1 Starting the Debug Mode

1. In order to start a debug session, the VisVAP application needs to be
running and all VisVAP files (*.VV) need to be included in the same
directory as the Vissim network file (*.INPX).
2. If a simulation is currently running in Vissim, choose Single Step Mode.
3. In Vissim, from the list of Signal Controllers open the Signal Controller
dialog window by double-clicking the row header of the controller you
would like to debug.
4. Select the [Controller configuration] tab.
5. Activate the option  Debug mode (VisVAP).

6. Close the window with OK.
7. Choose SIMULATION - CONTINUOUS in order to start/continue the simulation.
The simulation runs up to the next signal controller time step and then
halts automatically.
8. Activate the VisVAP application. The corresponding VisVAP file should
now have been loaded automatically and the debug cursor (amber color)
points to the first command after the program start.

Starting the Debug Mode
Depending on the number of variables, initialization may take some time

when neither VisVAP nor Vissim reacts on user input.
9. Furthermore, an additional column was created within the Parameters and

Expressions sections containing the current values. Within the
Parameters section only those values are contained that have 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 individual
for each section and are saved to the INI file.

10.2 VisVAP Debug Commands

The following commands are available during a VisVAP debug session. The
behavior of these commands depends on the current state of the Vissim
simulation.
Symb Command / Description
ol Shortcut
Continuous Executes all commands of the logic without
F5 stopping. If Vissim is in Single Step mode,
VisVAP stops at the end of the logic. If Vissim is
in Continuous mode, VisVAP continues until
another mode is selected.
Next Command Executes the command at the debug cursor
F4 position. If this is a subroutine, all commands
within the subroutine will be executed at once
without locating the debug cursor in the
subroutine. The debug cursor will be located at
the next command within the same level.
STEP IN Executes the command at the debug cursor
F3 position. If this is a subroutine, the debug cursor
follows into the subroutine and stops at the next
command within the subroutine. While the
debug cursor is located within a subroutine it
will be displayed in orange (in contrast to
yellow) color.
STEP OUT Available only while the debug cursor is located
SHIFT+F3 within a subroutine: Executes the rest of the
subroutine commands at once and locates the
cursor at the next command after that
subroutine has been called.
DEBUG - MARK COMMANDS: Marks all commands that have been executed so
far during one controller time step with in red color. This option is useful when
Vissim is in Single Step mode and VisVAP in Continuous debug mode as the
debugger then stops after every complete run of the control and shows a trace
of all executed commands.
The editor colors described in this chapter apply only to the main debug
window. For subroutine debug windows different colors apply.
If the debug mode is active, all VisVAP files related to that signal control logic
are locked and cannot be modified except for toggling breakpoints.

VisVAP Debug Commands
If 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.

Leaving the Debug Mode
10.4 Leaving the Debug Mode

If the Vissim application has input focus (i.e. if it responds to user input) the
debug mode may be stopped by choosing SIMULATION - STOP or by switching
off the Debugger (VisVAP) option in the Vissim Signal controller (see chapter
10.1).
If the VisVAP application has input focus, the debug mode may be stopped by
first selecting the continuous debug mode in VisVAP and then switching over
to Vissim and stop the debug mode as outlined above.
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.

11 Structure of a VisVAP File (VV-File)
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)
(e.g. L1|headway( DK5 ) >= 3.0|min Headway#)
► Subroutines block consisting of
- block identifier (UPROG)
(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 are not allowed to be 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 coded information about
the connecting lines and breakpoints.

Manual - VisVAP 216 ENG

Uploaded by

Copyright:

Available Formats

Manual - VisVAP 216 ENG

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Manual - VisVAP 216 ENG

Uploaded by

Copyright:

Available Formats

VISVAP 2.

PTV Planung Transport Verkehr AG, Karlsruhe, Germany

Last update: October 2017

2 Working with VisVAP 7

4 Drawing the Flow Chart 19

7 Variables, Arrays and Expressions 37

9 Check of Flow Chart and Generating a VAP File 43

10 Debugging a Signal Control Logic 47

VisVAP 2.16 © PTV AG 2

11 Structure of a VisVAP File (VV-File) 55

VisVAP 2.16 © PTV AG 3

VisVAP 2.16 © PTV AG 5

VisVAP 2.16 © PTV AG 6

VisVAP 2.16 © PTV AG 7

VisVAP 2.16 © PTV AG 8

VisVAP 2.16 © PTV AG 9

2.2 Keyboard Shortcuts

VisVAP 2.16 © PTV AG 10

VisVAP 2.16 © PTV AG 11

2.3 Screen Layout, Font and Symbol Sizes

2.3.1 Layout Files

VisVAP 2.16 © PTV AG 12

*.INI Menu command Action

2.3.2 Column Widths and Row Heights

VisVAP 2.16 © PTV AG 13

The following options are available:

VisVAP 2.16 © PTV AG 14

2.4 Find and Replace

Restrict the search area:

VisVAP 2.16 © PTV AG 15

Identifiers of parameters, expressions, variables and subroutines

Identifiers of signal groups and detectors

VisVAP 2.16 © PTV AG 17

In order for VisVAP to recognize operators correctly, blanks have to be

VisVAP 2.16 © PTV AG 18

VisVAP 2.16 © PTV AG 19

4.1 Symbol types

Below follows a description of all the symbol types:

CTRL+SHIFT+A Statement Use for commands and assignments.

VisVAP 2.16 © PTV AG 20

Sym Shortcuts Element Description

CTRL+SHIFT+B Condition Use for logical conditions. If the

CTRL+SHIFT+U Call of Calls the corresponding subroutine.

VisVAP 2.16 © PTV AG 21

Sym Shortcuts Element Description

CTRL+SHIFT+S Page Defines a page break on the printout

CTRL+SHIFT+T Text Optional commentary text for

CTRL+SHIFT+L Line Use for drawing lines to connect

VisVAP 2.16 © PTV AG 22

4.2 Connection Lines and Arrows

VisVAP 2.16 © PTV AG 23

VisVAP 2.16 © PTV AG 24

In contrast to standard drawing software products in VisVAP all available VAP

VisVAP 2.16 © PTV AG 25

Long name Short Meaning

VisVAP 2.16 © PTV AG 26

VisVAP 2.16 © PTV AG 27

Long name Short Meaning

VisVAP 2.16 © PTV AG 28

VisVAP 2.16 © PTV AG 29