visvap_216_e

VisVAP 2.16 User Manual

PTV Planung

Transport Verkehr AG

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 and Expressions 35 7.1 Variables 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

3 VisVAP 2.16 © PTV AG 2006

1 Introduction

10 Debugging a Signal Control Logic 45 10.1 Starting the Debug Mode 46 10.2 VisVAP Debug Commands 48 10.3 Breakpoints 50 10.4 Leaving the Debug Mode 51

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

VisVAP 2.16 © PTV AG 2006 4

1 Introduction

VisVAP enhances the use of free-defined 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 taken from RiLSA 1992 (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.

Design and check of flow chartsBegin

Stage_active(1) Ped_Demand

Stage_active(2)

Interstage( 1, 2 )

Interstage( 2, 1 )

Definition of stagescalculation of interstages

VAP (e.g. vap215.dll)

VISSIM

*.puadatabase *.vv*.vap

VisVAPCROSSIG

Texteditor



Stage_active(2)

Interstage( 1, 2 )

Interstage( 2, 1 )



Stage_active(2)

Interstage( 1, 2 )

Interstage( 2, 1 )

Begin


Stage_active(2)

Interstage( 1, 2 )

Interstage( 2, 1 )



VAP (e.g. vap215.dll)VAP (e.g. vap215.dll)

VISSIMVISSIM

*.pua*.pua*.puadatabasedatabasedatabase *.vv*.vv*.vv*.vap*.vap*.vap

VisVAPCROSSIG

TexteditorTexteditor

For the use of a stage oriented signal control the creation of interstages should be done using CROSSIG. CROSSIG exports an ASCII file (*.PUA) which includes all signal group commands for each interstage. VisVAP checks the structure of the program logic 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. However, experienced programmers who like to use text editors may prefer direct programming of VAP code. The flow chart and parameters of a VisVAP document can be saved to an ASCII file with extension *.VV.


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 separate pane. Altogether there are four panes holding information on: ► program logic (flow chart): ► parameters, ► arrays ► expressions and ► assignment of subroutines.

Each pane is shown as a table containing rows and columns. Except for the flow chart and arrays table the number of columns is fixed. The number of rows for each pane is variable. All column widths can be adjusted individually. The row height can be adapted for each pane. The number of the column and row currently active is shown in the status bar. Every VisVAP program compounds of the data of all panes. Each pane can be activated for editing by clicking the left mouse button within the pane. The name of the pane currently active is shown in the title bar of the program window.

Window pane 2: Parameters

Window pane 3: Arrays

Window pane 1: Chart Window pane 4: Expressions

Window pane 5: Subroutines

VisVAP 2.16 © PTV AG 2006 8

Desktop

Example

In the above example within the program PED.VV the parameters pane is active whereas in the program in front the chart pane is active. As with most other Windows applications the layout of program windows can be controlled using the WINDOW menu. Panes can also be hidden there. The size of a pane can be adapted while holding the left mouse button down when the cursor is placed on the edge between two panes and dragging the mouse accordingly. The layout of the windows and panes may be stored to an external layout file (see section 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 (‘_‘).

9 User Manual © PTV AG 2006


2.2 Keyboard Shortcuts VisVAP uses several standard shortcuts. Among these, additional shortcuts provide an effective way to work with VisVAP.

Shortcut Action

ALT + O Sets all columns in all panes to their optimal 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 continuos mode

F7 Insert Column(s)

SHIFT + F7 Delete Column(s)

F8 Insert Row(s)

SHIFT + F8 Delete Row(s)

F9 Toggle parameters pane

SHIFT + F9 Toggle chart pane

CTRL + F9 View chart only

F10 Toggle arrays pane

F11 Toggle expressions pane

F12 Toggle subroutines pane

CTRL + F12 View all panes

PAGE UP Scroll one page up

VisVAP 2.16 © PTV AG 2006 10

Keyboard Shortcuts

Shortcut Action

PAGE DOWN Scroll one page down

INS Toggle switch for overwrite and insert mode. If overwrite mode is active ‘OVR‘ is shown within the status bar.

Inserting clipboard data whilst being 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 pane individually. There are functions for changing the font size, column width, row height and window and zoom size. Furthermore the panes can be split. The page setup parameters contain zoom factors to adapt the size of the chart and tables for the printout.

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 activated, 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 being 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 being 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 - ADJUST DIMENSIONS

Adjusting the column width for each column individually and the general row height (relative to 100% Zoom)

VIEW - ZOOM – ZOOM IN

Zoom in by 20% (of previous size)

VIEW - ZOOM – ZOOM OUT

Zoom out by 20% (of previous size)

VIEW - ZOOM - CUSTOM ZOOM

Adjusting the view size using a custom zoom factor

VIEW – FONT - SELECT FONT

Changing font name and size (relative to 100% Zoom)

VIEW - FONT - LARGER FONT

Increase the font size by ca. 20% (relative to previous size)

VIEW - FONT - SMALLER FONT

Reduce the font size by ca. 20% (relative to previous size)

VisVAP 2.16 © PTV AG 2006 12

Screen Layout, Font and Symbol Sizes

*.INI Menu command Action

VIEW - GRID

Switches grid on or off (default for pane 2, 3 and 4)

VIEW - ARROWS – ARROW STYLE

Adjusting the style of arrows (narrow, wide, 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

WINDOW ... 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 WIDTH) 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 pane separately. ► ALL WIDTHS SAME AS COLUMN 0: Sets all subsequent column widths to the

width of column 0. ► OPTIMAL COLUMN WIDTH: Sets all column widths of the corresponding

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

VisVAP 2.16 © PTV AG 2006 14

3 General Conventions

There are some conditions 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 be either 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 being 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.

15 VisVAP 2.16 © PTV AG 2006

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

VisVAP 2.16 © PTV AG 2006 16

4 Drawing the Flow Chart

The program logic is designed as flow chart within the chart pane. It consists of columns and rows and is internally restricted to 20 columns and 500 rows. Bigger charts can be designed using subroutines.

17 VisVAP 2.16 © PTV AG 2006


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

Symbol

Shortcuts Element Description

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.

VisVAP 2.16 © PTV AG 2006 18

Symbol types

Symbol


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 subroutine

Calls the corresponding subroutine. Within the pane 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 pane. 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 pane the identifier ‘PT_MODUL‘ is assigned to a VisVAP file (here: C:\VISVAP\DOC\PT_MODUL.VV).



Symbol


CTRL+SHIFT+S Page separator

Defines a page break on the 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.

VisVAP 2.16 © PTV AG 2006 20

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 arrows

Toggles the display of all arrows within the 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.

VisVAP 2.16 © PTV AG 2006 22

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

23 VisVAP 2.16 © PTV AG 2006

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>, <display> )

Cst Returns 1 if the current state of signal group <no> is <display>, else 0.

Cycle_second T Returns current cycle second. Cycle_second_between ( <begin>, <end>, <op.type> )

Csb Returns 1 if the current cycle second (t) 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>, <display> )

Dst Returns 1 if the last desired state (set 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).

VisVAP 2.16 © PTV AG 2006 24



Intergreen(<sg1>, <sg2>) IntG Returns the intergreen time between signal groups <sg1> and <sg2> as defined *.pua file.

Interstage( <stage1>, <stage2> )

Is Runs an interstage

Interstage_active( <stage1>, <stage2> )

IsA Returns 1 if any interstage is active, otherwise 0.

Interstage_duration( <stage1>, <stage2> )

IsT Returns the current second of the interstage or 0 in case the interstage is not active

Interstage_length( <stage1>, <stage2> )

IsL Returns length of interstage.

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>, <vehClassNo>, <desSpDistrNo> )

Sdsp Assigns the desired speed distribution <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>, <routeNo>,<flow> )

Srou Sets the relative flow of the route <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 red_f off off_red

amber amber_f redamber greenamber

green green_f redgreen_f

VisVAP 2.16 © PTV AG 2006 26



Set_sg_direct( <no>, <display> )

Ssgd Sets display of signal group <no> immediately to <display> without any transitions and disregarding minimum display times.

set_stop_time_dist( <stop_no>, <veh_cl_no>, <dist_no> )

Sst Selects the dwell time distribution <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 telegram number <no>.

Tele_line( <no> ) TeLin Returns the line number from the telegram number <no>.

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 telegram number <no>.

Tele_route( <no> ) TeRou Returns the route number from the telegram number <no>.

Tele_tram_length( <no> ) TeLng Returns the tram length from the telegram number <no>.

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>, <var2> ))

- Writes values of variables <var1> and <var2> to trace file.

Veh_length( <no> ) V_l Returns the length of the last vehicle that passed detector <no> within the current simulation second.

VisVAP 2.16 © PTV AG 2006 28



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.

31 VisVAP 2.16 © PTV AG 2006

6 Parameters

6.1 VAP-Parameters COMPILE - VAP PARAMETERS… opens the window VAP Parameters. Here the Controller frequency of the signal control is set. An integer value within the range 1..10 is to be defined. When generating a VAP file, this parameter is added in the VAP file. The controller frequency defined how often within one simulation second the logic is executed. This value must correspond with 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.

VisVAP 2.16 © PTV AG 2006 32

User-Defined Parameters and Constants

6.2 User-Defined Parameters and Constants All parameters that are referred to in the flow chart and in expressions must be defined in the parameters pane. By definition, the value of a parameter cannot be changed during program execution except for different parameter sets for various signal programs (see below). The parameters pane consists of 11 columns. The first column contains the identifiers of the parameters. If the corresponding value is written 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 for the corresponding signal program. The last column can take an optional comment. The width of columns can be adjusted individually using VIEW - ADJUST DIMENSIONS. See the illustration below as an example:

To change a signal program during a running simulation means to choose a different parameter set. It can be achieved either within VisVAP by using the VAP function set_prog() or manually within VISSIM by choosing a different program number in the signal control. VisVAP offers parameter sets for 8 different signal programs (1..8) and uses program 1 to start with by default.


7 Variables and Expressions

35 VisVAP 2.16 © PTV AG 2006

7 Variables and Expressions

7.1 Variables In VisVAP and VAP all variables are declared as global. Except for arrays 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. Thus condition NOT init is true and so the value 5 is assigned to var1 and 8 to var2. Before continuing with the program execution 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.

Array variables need to be defined in the Arrays table. After entering an identifier name the array can be defined either one- or two-dimensional by entering a dimension value in the appropriate column. The number of columns (‘dim1’) needs to be entered first. Then VisVAP automatically expands the table to allow for entering all initial values. Within the array table only single lines can be entered. Empty fields that do not belong to an array definition cannot be changed. The dimensions of an existing array can be changed simply by typing a new value in the corresponding cell. Copy and paste functions can only be used in cells that contain values or comments. To delete an array simply its identifier needs to be deleted. Consequently VisVAP deletes all cells that are not used any more.

VisVAP 2.16 © PTV AG 2006 36

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 can be defined within the expressions pane 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 window from within the second column (see 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 being evaluated each simulation second 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 the same until the run of the whole program logic for each second has been completed.

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 pane. 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 defined as 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.

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

39 VisVAP 2.16 © PTV AG 2006


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

VisVAP 2.16 © PTV AG 2006 42

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.

VisVAP 2.16 © PTV AG 2006 44

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.

45 VisVAP 2.16 © PTV AG 2006


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 panes containing the current values. Within

VisVAP 2.16 © PTV AG 2006 46

Starting the Debug Mode

the Parameters pane 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 pane (temporarily replacing the initial values). After finishing the debug mode, the original tables are being 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 pane 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.

Symbol

Command / Shortcut

Description

Continuous F5

Executes all commands of the logic without 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 CommandF4

Executes the command at the debug cursor 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 F3

Executes the command at the debug cursor 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 SHIFT+F3

available only while the debug cursor is located 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 simulation second 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 2.16 © PTV AG 2006 48

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 being stored in the VisVAP file.

VisVAP 2.16 © PTV AG 2006 50

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

0|Display unit no#(e.g. DU||8|11|13|15|17|16|14|12|1► p f

) Ex ressions block consisting o- block identifier (AUSDRUECK

one row per table row E)

- Headway#)

► b ng of

-

► isting of

- filename (e.g. )

A,B,L,S,T,U,Z) and encoded information about the connecting lines and breakpoints.

(e.g. L1|headway( DK5 ) >= 3.0|minSu routines block consisti- block identifier (UPROG)

one row per table row (e.g. Calculate_Expressions|ril_sub.vv|# )

Optional layout file block cons- block identifier (INI-DATEI)

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

53 VisVAP 2.16 © PTV AG 2006

visvap_216_e

Documents

visvap file

introduction visvap

visvap document

visvap debug commands

desktop of visvap compounds

check of flow chartsbeginstage

ptv ag

vap functions