Visvap 216 e

VISVAP 2.
16
USER MANUAL
PTV Planung Transport Verkehr AG, Karlsruhe, Germany

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
3 General Conventions 15
4 Drawing the Flow Chart 17

4.1 Symbol types 18
4.2 Connection Lines and Arrows 21
5 VAP Functions 23
6 Parameters 31
6.1 VAP-Parameters 32
6.2 User-Defined Parameters and Constants 33
7 Variables, Arrays and Expressions 35

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

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

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

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

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

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 + 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
PAGE UP Scroll one page up

Keyboard Shortcuts
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.

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.

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

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: This call of subroutine PT_MODUL is included in the flow chart.

Within the subroutines section the identifier PT_MODUL is assigned to a
VisVAP file (here: C:\VISVAP\DOC\PT_MODUL.VV).


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

separator printout 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
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.

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

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 parameters. If the corresponding value is defined in the
second column (General) it is valid regardless of the currently selected
signal program. If one or more values are entered in the subsequent 8
columns instead, the parameter is valid only while the corresponding signal
program is 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 program is 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 to start with by default.
Constants can also be defined as a reference to another constant that has a
value defined for General. Example (see table above): Instead of writing 8
for defining T_QUEUE_1_5 it can be defined by T_QUEUE_2.
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 any term changes that is referenced by an expression, the
expression reflects these changes only during the next 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 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.
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 will
be 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 used in 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 of the fact that
only one of both applications can have control at the same time.

10.1 Starting the Debug Mode

The debug feature requires at least Vissim version 4.10, VAP215.dll and
VisVAP version 2.15.
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 (*.INP).
2. If a simulation is currently running in Vissim, choose Single Step Mode.
3. In Vissim, choose SIGNAL CONTROL - EDIT CONTROLLERS and select the
SC that you would like to debug.
4. Select the [Controller (VAP)] tab.
5. Make sure that at least VAP215.dll is used as PROGRAM FILE. Then

activate the Debug Mode (VisVAP) option.
6. Close the window by pressing OK.
7. Choose SIMULATION - CONTINUOUS in order to start/continue the
simulation.
8. Activate the VisVAP application. The corresponding VisVAP file should
now have been loaded and the debug cursor (amber) pointing to the first
command after the program start.
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 has been created within the

Parameters and Expressions sections containing the current values.
Within the Parameters section only those values are contained that have

Starting the Debug Mode
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.

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

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

Leaving the Debug Mode
10.4 Leaving the Debug Mode

If the Vissim application has input focus (i.e. when 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 Signal control (see 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 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.

Visvap 216 e

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Visvap 216 e

Enviado por

Direitos autorais:

Formatos disponíveis

VISVAP 2.

PTV Planung Transport Verkehr AG, Karlsruhe, Germany

2 Working with VisVAP 7

4 Drawing the Flow Chart 17

7 Variables, Arrays and Expressions 35

9 Check of Flow Chart and Generating a VAP File 41

10 Debugging a Signal Control Logic 45

VisVAP 2.16 PTV AG 2012 2

11 Structure of a VisVAP File (*.VV-File) 53

VisVAP 2.16 PTV AG 2012 3

VisVAP 2.16 PTV AG 2012 5

VisVAP 2.16 PTV AG 2012 7

VisVAP 2.16 PTV AG 2012 8

VisVAP 2.16 PTV AG 2012 9

2.2 Keyboard Shortcuts

VisVAP 2.16 PTV AG 2012 10

VisVAP 2.16 PTV AG 2012 11

2.3 Screen Layout, Font and Symbol Sizes

2.3.1 Layout Files

VisVAP 2.16 PTV AG 2012 12

*.INI Menu command Action

2.3.2 Column Widths and Row Heights

VisVAP 2.16 PTV AG 2012 13

The following options are available:

VisVAP 2.16 PTV AG 2012 14

Identifiers of parameters, expressions, variables and subroutines

Identifiers of signal groups and detectors

In VAP the integer range of signal group and detector identifiers is

VisVAP 2.16 PTV AG 2012 15

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

wrong L1ANDL2vL3, L1AND L2v L3, L1 ANDL2 vL3,

VisVAP 2.16 PTV AG 2012 16

VisVAP 2.16 PTV AG 2012 17

4.1 Symbol types

Below follows a description of all the symbol types:

CTRL+SHIFT+A Statement Use for commands and

VisVAP 2.16 PTV AG 2012 18

Sym Shortcuts Element Description

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

Example: In case the occupancy time of detector T23 (OccT( T23 )) is

CTRL+SHIFT+U Call of Calls the corresponding

Example: This call of subroutine PT_MODUL is included in the flow chart.

VisVAP 2.16 PTV AG 2012 19

Sym Shortcuts Element Description

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

CTRL+SHIFT+T Text Optional commentary text for

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

VisVAP 2.16 PTV AG 2012 20

4.2 Connection Lines and Arrows

VisVAP 2.16 PTV AG 2012 21

VisVAP 2.16 PTV AG 2012 22

In contrast to standard drawing software products in VisVAP all available

VisVAP 2.16 PTV AG 2012 23

Long name Short Meaning

VisVAP 2.16 PTV AG 2012 24

Long name Short Meaning

Interstage_active( <stage1>, IsA Returns 1 if any interstage is active,

VisVAP 2.16 PTV AG 2012 25

Long name Short Meaning

VisVAP 2.16 PTV AG 2012 26

Long name Short Meaning

VisVAP 2.16 PTV AG 2012 27

Long name Short Meaning

VisVAP 2.16 PTV AG 2012 28