script users guide - educating global leadersmsaito/ce662ms/user... · using the script tool script...

Script Tool User's Guide

Version 6.0

Prepared by: ITT Industries, Inc., Systems Division ATMS R&D and Systems Engineering Program Team P O Box 15012 Colorado Springs, CO 80935-5012 Prepared for: FHWA Office of Operations Research, Development and Technology Federal Highway Administration Turner-Fairbank Highway Research Center 6300 Georgetown Pike McLean, Virginia 22101-2296

December 2006

Script Tool User's Guide ii

NOTICE

This document is disseminated under the sponsorship of the Department of Transportation in the interest of information exchange. The United States Government assumes no liability for its contents or use thereof.

This document does not constitute a standard, specification, or regulation.

The Federal Government and McTrans are not responsible for implementation decisions (e.g., construction designs, traffic signal timings) made based on the results of analyses performed using the computer programs described herein.

Copyright (C) 2006 University of Florida. All rights reserved. Portions copyright (C) 1995 - 2005 ITT Industries, Inc., Systems Division.

Microsoft and Windows are registered trademarks of Microsoft Corporation. VBScript and Microsoft Script Control are registered trademarks of Microsoft Corporation.

Foreword

Script Tool User's Guide iii

Foreword

This User's Guide describes how to access and use the TSIS Script Tool. The McTrans Center is maintaining the Script Tool.

Please refer to the TSIS User's Guide for information on obtaining TSIS and the TSIS Script Tool.

Abstract

Script Tool User's Guide v

Abstract

The TSIS Script Tool is distributed as part of, and is designed to operate efficiently in conjunction with, FHWA's Traffic Software Integrated System (TSIS). The Script Tool is used to create, edit, and execute Visual Basic scripts that automate processing tasks involving TSIS tools.

This guide:

• Introduces users to the capabilities and features of the Script Tool.

• Explains in detail how to use the Script Tool.

• Describes the scripts that are provided in the TSIS package.

Table of Contents

Script Tool User's Guide vii

Contents 1 About Script Tool..........................................................................................1-1

1.1 Welcome to the Script Tool .............................................................................................................. 1-1 1.2 Introduction....................................................................................................................................... 1-1

2 Using the Script Tool....................................................................................2-1 2.1 General Features ............................................................................................................................... 2-1

2.1.1 Creating a New Script ............................................................................................................... 2-1 2.1.2 Opening an Existing Script ....................................................................................................... 2-2 2.1.3 Saving a Script .......................................................................................................................... 2-2 2.1.4 Editing Text............................................................................................................................... 2-2 2.1.5 Context Menu............................................................................................................................ 2-4 2.1.6 Status Bar .................................................................................................................................. 2-5

2.2 Configuring the Script Tool .............................................................................................................. 2-5 2.3 Running Scripts................................................................................................................................. 2-6

3 Script Interfaces............................................................................................3-1 3.1 Overview........................................................................................................................................... 3-1 3.2 Output View Control Interface.......................................................................................................... 3-1 3.3 Script Support Interface .................................................................................................................... 3-2 3.4 CORSIM Server Interface................................................................................................................. 3-3 3.5 TRF Manipulator Interface................................................................................................................ 3-3

3.5.1 Change Files.............................................................................................................................. 3-5 3.5.2 Example TRF Manipulator Script ............................................................................................. 3-9

3.6 Global Variables ............................................................................................................................. 3-10 4 Interface Function Reference Guide ...........................................................4-1

4.1 Output View Control Interface Functions ......................................................................................... 4-1 4.1.1 Clear .......................................................................................................................................... 4-1 4.1.2 DisplayColoredText .................................................................................................................. 4-1 4.1.3 DisplayText ............................................................................................................................... 4-2 4.1.4 SelectLineContainingText......................................................................................................... 4-2 4.1.5 StartLogging.............................................................................................................................. 4-2 4.1.6 StopLogging.............................................................................................................................. 4-3

4.2 Script Support Interface Functions.................................................................................................... 4-3 4.2.1 ActivateScriptTab ..................................................................................................................... 4-3 4.2.2 CreateCORSIMServer............................................................................................................... 4-3 4.2.3 IncludeFile ................................................................................................................................ 4-3 4.2.4 LaunchTSISTool ....................................................................................................................... 4-4 4.2.5 ReleaseCORSIMServer............................................................................................................. 4-4 4.2.6 ScriptTerminated....................................................................................................................... 4-4 4.2.7 SelectFile................................................................................................................................... 4-5 4.2.8 SetMainSub............................................................................................................................... 4-5 4.2.9 WaitForCORSIM ...................................................................................................................... 4-5

4.3 CORSIM Server Interface Functions ................................................................................................ 4-6 4.3.1 AddExtension............................................................................................................................ 4-6

Table of Contents

viii Script Tool User's Guide

4.3.2 ClearExtensions .........................................................................................................................4-7 4.3.3 ExtensionCount..........................................................................................................................4-7 4.3.4 GetExtension..............................................................................................................................4-7 4.3.5 Run.............................................................................................................................................4-8 4.3.6 RunMulti....................................................................................................................................4-8 4.3.7 SetCORSIMDLL .......................................................................................................................4-8 4.3.8 SetIOParams ..............................................................................................................................4-8 4.3.9 SetMultiRunParams ...................................................................................................................4-9 4.3.10 SetRunParams......................................................................................................................4-10

4.4 TRF Manipulator Interface Functions .............................................................................................4-10 4.4.1 AddRecord...............................................................................................................................4-10 4.4.2 AddTimePeriod........................................................................................................................4-10 4.4.3 ApplyChangeFile .....................................................................................................................4-11 4.4.4 CopyLinkRecord......................................................................................................................4-11 4.4.5 CopyNetworkRecord ...............................................................................................................4-11 4.4.6 CopyNodeRecord ....................................................................................................................4-12 4.4.7 GetDefaultValue ......................................................................................................................4-12 4.4.8 GetLinkParameter....................................................................................................................4-12 4.4.9 GetMaxValue...........................................................................................................................4-13 4.4.10 GetMinValue .......................................................................................................................4-13 4.4.11 GetNetworkParameter .........................................................................................................4-13 4.4.12 GetNodeParameter...............................................................................................................4-14 4.4.13 GetTimePeriod.....................................................................................................................4-14 4.4.14 OpenTRFFile .......................................................................................................................4-14 4.4.15 SetLinkParameter.................................................................................................................4-15 4.4.16 SetNetworkParameter ..........................................................................................................4-15 4.4.17 SetNodeParameter ...............................................................................................................4-15 4.4.18 SetParameterInAll................................................................................................................4-16 4.4.19 SetTimePeriod .....................................................................................................................4-16 4.4.20 SaveTRFFile ........................................................................................................................4-16

5 Pre-defined Scripts ...................................................................................... 5-1 5.1 Overview ...........................................................................................................................................5-1 5.2 Script Summaries...............................................................................................................................5-1

5.2.1 GetNetworkData.vbs..................................................................................................................5-1 5.2.2 Single-Run Many Cases.vbs ......................................................................................................5-1 5.2.3 Single-Run Many Cases Saving Network Data.vbs...................................................................5-1 5.2.4 Multi-Run Same Case.vbs .........................................................................................................5-2 5.2.5 Multi-Run Same Case Saving Network Data.vbs ......................................................................5-2 5.2.6 Multi-Run Many Cases.vbs .......................................................................................................5-2 5.2.7 Multi-Run Many Cases Saving Network Data.vbs ....................................................................5-2

6 Glossary of Terms........................................................................................ 6-1

7 Index.............................................................................................................. 7-1

About Script Tool

Script Tool User's Guide 1-1

1 About Script Tool

1.1 Welcome to the Script Tool This User's Guide supports traffic engineers using the Traffic Software Integrated System (TSIS) Script Tool. It describes the Script Tool features that enable you to create, edit, and execute Visual Basic scripts within the TSIS environment. The guide describes neither the technical aspects of CORSIM, nor the types of analyses that can be performed using traffic simulations.

1.2 Introduction The TSIS Script Tool uses Microsoft's Script Control and rich edit control to provide an application that enables you to generate and execute scripts within the TSIS environment. The Script Tool also provides access to several interfaces that allow the scripts to interact with the TSIS user interface, TShell, and other tools within the TSIS environment. This document describes the features and use of the Script Tool.

For executing Visual Basic scripts, the Script Tool uses the Microsoft Visual Basic script engine (VBScript). This Microsoft product is generally installed on a platform running a Microsoft operating system. If the script engine is not installed on you computer, the Script Tool will not be able to execute Visual Basic scripts. Installing TSIS does not install the Visual Basic script engine. However, you can download and install the Visual Basic script engine from Microsoft at http://msdn.microsoft.com/scripting.

Scripting enables you to automate frequently performed tasks by writing standard Visual Basic scripts. Although scripting is a very powerful tool, it does require some computer programming experience and knowledge of the VBScript language. This document does not provide a description of the VBScript engine nor the VBScript language. However, a good reference on the syntax of Visual Basic script can be found at http://msdn.microsoft.com/scripting.

As part of the TSIS package, we have provided several scripts. These scripts can be used as is or can be modified to create your own scripts. They are described in Chapter 5.

Using the Script Tool


2 Using the Script Tool

2.1 General Features The TSIS Script Tool is an ActiveX control that operates within the TSIS graphical user interface, known as TShell. As such, TShell supports the Script Tool by supplying menus, toolbars, and a status bar. In this document, we will describe only those elements of the TShell interface that have a unique operation with regard to the Script Tool. For example, the View, Options, Tools, Window, and Help menus operate is a common fashion as they do for all TShell components, and will not be described here. Please refer to the TShell User's Guide for information regarding the operation of these common elements.

2.1.1 Creating a New Script To create a new file using the Script Tool, select the File|New menu and then select the Script Tool File menu command that appears in the sub-menu. This menu is illustrated in the following figure.

You can also press the New File button on TShell's Main toolbar and then select Script Tool from the Choose Tool dialog. Either action will create a new Script Tool window in the TShell workspace. In the delivered TSIS configuration, the default file type for the Script Tool is VBS.

Alternatively, you can start by opening one of the scripts that are delivered with the TSIS package, modify it, and save it to a different file name.


2-2 Script Tool User's Guide

2.1.2 Opening an Existing Script You can open an existing file in the Script Tool by one of several methods. In general, you can open a file using a File Open dialog or open a file from the TShell Project View.

Selecting the File|Open menu item will display a standard Window's open dialog that allows you to choose a file to open. After choosing a file, TShell will display the Choose Tool dialog that allows you to select a tool to use. From this dialog, select the Script Tool item.

To open an existing file from the TShell Project View, select (highlight) a file in the Project View. Then press

the Open Selected File button on TShell's Main toolbar. This action will also display the Choose Tool dialog that allows you to select a tool to use. From this dialog, select the Script Tool item.

Alternatively, after selecting a script file in the Project View, press the Script Tool button on TShell's Tools toolbar.

Clicking on a file in the Project View with the right mouse button displays a pop-up menu that allows you to open the file with the default tool or any tools associated with the file type. Choose the Open With item from the menu to display a sub-menu of tools and then choose the Script Tool item from the sub-menu.

If the Script Tool has been set as the default tool for the file type you are trying to open, you can simply double-click the highlighted file to open it in the Script Tool. In the delivered configuration, the Script Tool is set as the default tool for VBS files.

Scripts that are provided in the TSIS installation are located in the Scripts folder under the directory to which TSIS was installed. You may save scripts you create to that folder as well. Scripts that are stored in that folder are accessible via the Tools|Scripts menu item.

Finally, if a VBS file has been open recently, you can double click the file in the recent file list that appears in the File menu.

2.1.3 Saving a Script To save a script, select the File|Save menu command, File|Save As… menu command, or press Ctrl+S. If the file is new or if you choose the Save As command, you will need to supply a file name and folder location for the file in the Save As dialog that appears.

If you want your script file to appear in the Tools|Scripts sub-menu, save your script file to the Scripts folder under the directory to which TSIS was installed.

2.1.4 Editing Text In the Script Tool, you can edit text using the mouse, keyboard, and the Edit menu and its associated accelerator keys. These text-editing operations are the same as those that are available in the Microsoft Notepad application.

Undo / Redo Last Action To undo the last action completed, select the Edit|Undo menu command or press Ctrl+Z. To redo the last action undone, select the Edit|Redo menu commands or press Ctrl+Y.

Selecting Text There are several ways to select text. You can select text by character, word, or the entire file with the following methods:

• Drag the mouse with its left button depressed over the desired text for selection.



• Press the Shift key and use the arrow keys to select characters.

• Press the Ctrl and Shift keys and use the arrow keys to select words.

• Select the Edit|Select All menu command or the Ctrl+A accelerator to select all of the text in the file.

You can cancel a selection by clicking anywhere in the document.

Cutting Text Cutting text removes the selected text and places it into the Windows clipboard. To cut selected text, select the

Edit|Cut command or press Ctrl+X. You can also press the Cut button on TShell's Main toolbar. Please note that you can cut text only if text has been selected.

Copying Text Copying text places selected text into the Windows clipboard. To copy selected text, select the Edit|Copy

command or press Ctrl+C. You can also press the Copy button on TShell's Main toolbar. Please note that you can copy text only if text has been selected.

Pasting Text Pasting text retrieves text from the Windows clipboard and inserts the text at the location of the caret in the file. If text is already selected in the file, the pasting operation replaces the selected text with the contents of the Windows clipboard. To paste text, position the caret to the desired location (or select the text you want to

replace), then select the Edit|Paste command or press Ctrl+V. You can also press the Paste button on TShell's Main toolbar.

Deleting Text To delete text, first select the text you want to delete. Then select the Edit|Delete menu item or press the keyboard Delete key. If you do not select any text, this action will delete the first character after the caret.

Finding Text To search for text in the file, select the Edit|Find menu command or press Ctrl+F. This will display the Find dialog, illustrated in the following figure.

In the Find dialog, enter the text you want to search for, set the desired search preferences, and then click the Find Next button (or press the Enter key). To find additional instances of the same text, continue to click the Find Next button. Note, if you select the text you want to search for before you invoke the Find dialog, that selected text will appear in the "Find what" field when the dialog is opened.



2.1.5 Context Menu Many of the editing functions, described in the previous section, are available via the Script Tool context menu. You can display the context menu by clicking the right mouse button while the cursor is over the client area of the Script Tool window. You can also display the context menu by pressing the context menu key, if available, or the Shift-F10 key on your keyboard while the mouse cursor is over the client area of the Script Tool window. The context menu is illustrated in the following figure.

In addition to providing access to editing functions, the context menu enables you to modify the display properties of the current Script Tool session. Selecting the Properties… item displays the Script Tool properties page, illustrated in the following figure.

Using the Font controls of this dialog, you can specify the font size and type to be used for the current file. These controls provide access to all of the font types that are currently loaded into your system. Using the Color controls of this dialog, you can select the text and background colors to be used for the current file. The scrollable window at the bottom of this dialog displays sample text using your current font and color selections. After changing selections, press the OK or Apply button to save your settings. Press the Cancel button to reject your changes and exit the dialog.



2.1.6 Status Bar The TShell status bar, illustrated in the following figure, forms the bottom edge of the main TShell window. The status bar consists of multiple display panes, each providing information about the active document.

The status bar displays a brief description of the command performed by a button or menu item when the mouse cursor is over the button or item. The description appears in the left-most part of the status bar. For the Script Tool, the next pane displays the line and column number for the current position of the caret in the script document.

The next three panes indicate the status of the Caps Lock, Num Lock, and Insert keys on the keyboard. If a pane is empty, it indicates the key is not active. Pressing a key toggles the state of its associated indicator in the status bar. The Insert key toggles the state of the overstrike mode in the Script Tool.

The last two panes of the status bar, if visible, indicate the current system date and time. The visibility of the date/time panes is a TShell preference.

2.2 Configuring the Script Tool The delivered TSIS package includes a pre-configured version of the Script Tool. The following figure illustrates the TShell Tools toolbar that contains a button for the Script Tool.

You can activate the Script Tool by clicking on the Script Tool button in this toolbar.

By right clicking on the Script Tool button, you invoke the Tool Configuration dialog for the Script Tool as shown in the following figure.



The settings on the first two tabs of this dialog control the properties of the Script Tool within the TShell framework. The last tab displays version information for the Script Tool. These tabs are described in the TShell User's Guide, and will not be discussed here.

The parameters on the Script Tool Settings tab control the look of the text in the Script Tool window. The top drop-down list contains an entry for each file type (extension) supported by the Script Tool (as specified on the Tool Configuration tab). The text settings on the remainder of this tab apply to the file type specified in the top drop-down list. Thus, you can have different font styles and colors for the different types of files you use with the Script Tool.

In the Font section of this dialog, you can specify the font size and type to be used for the selected file type. This section provides access to all of the font types that are currently loaded into your system.

The Colors section of this dialog enables you to select the text and background colors to be used for the selected file type. The scrollable window at the bottom of this dialog displays sample text using your current font and color selections.

After changing selections, press the OK button to save your settings and exit the dialog. Press the Cancel button to reject your changes and exit the dialog. If you change and save the settings, the new settings will automatically be applied to all open Script Tool document windows. Press the Help button to display on-line instructions for using the Tool Configuration dialog.

2.3 Running Scripts The following figure illustrates an example script as displayed in the Script Tool. The example script is provided to illustrate the interface and does not constitute a meaningful or useful application of the script tool.

When executed, the example script will display a message box with the text "Hello World". After dismissing the message box, the script will open the actctrl.bmp file in the Microsoft Paint application.

The window that contains the script also contains a toolbar with three buttons used to execute the script. The following text describes the function of each of the three buttons:

Start: This button executes the script. It also resumes execution for a currently paused script.

Stop: This button stops a currently executing script.

Pause: This button pauses a currently executing script.

Script Interfaces


3 Script Interfaces

3.1 Overview To provide additonal support to the Visual Basic scripting language, the Script Tool offers three distinct interfaces that provide:

• access the TShell Output View,

• support for executing and controlling scripts,

• control of the CORSIM simulation.

The following sections summarize the capabilities of these interfaces. The next chapter is a reference guide that provides details for understanding and using the interface functions.

3.2 Output View Control Interface The Output View Control interface enables a script to write text to and clear the contents of the TShell Output View tab that is associated with the script (see the TShell User's Guide for a detailed description of the Output View). It also enables a script to log the information sent to the Output View. The Script Tool provides a reference to the Output View Control interface, IOutputControl, used to access the interface functions. To call an interface function from your script, use the following construct:

IOutputControl.function parameters … … …

In this construct, the IOutputControl identifies the interface and function is one of the functions summarized in the following table. A "." character is used to separate the interface reference and the function name. The list of parameters accepted by the function follow the function name, separated by commas. The table summarizes the functions of this interface. The reference guide in the next chapter provides detailed descriptions of these functions.

Function Definition

Clear Clears the Output View tab associated with the Script Tool

DisplayColoredText Displays text in the Output View, using the color associated with the specified index.

DisplayText Displays text in the Output View, using the default color defined by the Output View.

SelectLineContainingText Highlights the line in the Output View that contains the specified text.

Script Interfaces


Function Definition

StartLogging Starts output logging to the specified file. The specified file will receive all text written to the Output View after this function is called.

StopLogging Terminates logging to the log file specified in the call to StartLogging.

3.3 Script Support Interface The Script Support interface provides functions used to control and execute scripts within the Script Tool. It also provides additional support functions not offered by the Microsoft Script engine. The Script Tool provides a reference to the Script Support interface, IScriptSupport, used to access the interface functions. To call an interface function from your script, use the following construct:

IScriptSupport.function parameters … … …

In this construct, the IScriptSupport identifies the interface and function is one of the functions summarized in the following table. A "." character is used to separate the interface reference and the function name. The list of parameters accepted by the function follow the function name, separated by commas. The table summarizes the functions of this interface. The reference guide in the next chapter provides detailed descriptions of these functions.

Function Definition

ActivateScriptTab Enables a script to activate the Output View tab associated with the Script Tool. This brings that tab to the front of the Output View.

CreateCORSIMServer Enables a script to create a CORSIM Server object so that it can run the CORSIM simulation.

IncludeFile Adds the contents of the specified file to the script control. This enables a script user to easily add procedures to multiple scripts without having to duplicate the code.

LaunchTSISTool Enables a script to execute the specified TSIS tool.

ReleaseCORSIMServer Enables a script to release a CORSIM Server object that it created using CreateCORSIMServer.

ScriptTerminated Enables a script to query the script control to determine if the user has terminated the script execution via the "Stop" button.

SelectFile Enables a script to display a file selection dialog for the user to select a file for processing. This method returns a string containing the selected file (if one was selected).

SetMainSub Sets the name of the "main" procedure that the script control will execute after loading the script. If blank, the script control will execute statements in the order they were written (added) to the script control, beginning with the first statement in the script.

WaitForCORSIM This function is used in conjunction with the Run and RunMulti functions of the CORSIM Server and is used to keep the script processor alive until the current CORSIM run has completed. This function must be called immediately following the Run or RunMulti functions. See the reference guide for details.

Script Interfaces


3.4 CORSIM Server Interface The CORSIM Server interface enables a script to control the settings and execution of the CORSIM simulation. You specify the name of the CORSIM Server interface reference using the CreateCORSIMServer function of the IScriptControl interface. For example, you might create the server as follows:

IScriptControl.CreateCORSIMServer( "CORSIMServer" )

Then, to call a CORSIM Server interface function from your script, you would use the following construct:

CORSIMServer.function parameters … … …

In this construct, the CORSIMServer identifies the interface and function is one of the functions summarized in the following table. A "." character is used to separate the interface reference and the function name. The list of parameters accepted by the function follow the function name, separated by commas. The table summarizes the functions of this interface. The reference guide in the next chapter provides detailed descriptions of these functions.

Function Definition

AddExtension Adds the specified run-time extension to the CORSIM Server.

ClearExtensions Removes all current run-time extensions from the CORSIM Server.

ExtensionCount Returns the count of run-time extensions added to the CORSIM Server.

GetExtension Returns the definition of the specified run-time extension.

Run Executes a single run of the CORSIM simulation as specified by the run parameters.

RunMulti Executes a multiple run of the CORSIM simulation as specified by the multi-run parameters.

SetCORSIMDLL Specifies the dynamic-link library that contains the CORSIM simulation which the CORSIM Server will use.

SetIOParams Controls the input and output of the CORSIM simulation.

SetMultiRunParams Sets the simulation control parameters for a multi-run using the RunMulti function.

SetRunParams Sets the simulation control parameters for a single run using the Run function.

3.5 TRF Manipulator Interface The TRF Manipulator tool can be used in a script to repeatedly open a CORSIM (*.TRF) input file, manipulate the contents, and save the file with a new name. Well written scripts can make this tool do much of the previously intensive and error prone task of changing data. It can be used in a nested loop to set a parameter then increment it multiple times. The TRF Manipulator tool uses the TRFFormat.mdb database to know what columns of text on the specified record entries to manipulate. This tool has many functions to change different types of data. The functions are listed below and described in the next chapter.

You can separate the TRF file manipulation and CORSIM execution into different scripts if desired. By storing the generated file names in a list file (*.inp) during the manipulation loop, you can then use a different script to run CORSIM. For example, make all the file changes in one script then run the standard multi-run, multi-case script to run CORSIM on those cases.

When performing output processing during a multi-run script, a configuration (casename.cfg) file unique to the case is necessary to define what data is to be collected and in what format. When the TRF Manipulator is used to change TRF files and save them as different cases, the associated configuration files must be copied also. A configuration file that "uses" another source configuration file only contains the path and name of the source configuration file. All the resulting configuration files point to the same source file. By changing the source

Script Interfaces


configuration file all of the different runs use those changes. The following script sample shows how to copy the associated configuration file.

' Create the object used to access files. Set fileSystem = Createobject( "Scripting.FileSystemObject" ) ' In order to do output processing there must be a configuration file. ' Copy the Config file to the new name. fileSystem.CopyFile infile & ".cfg", modifiedFile & ".cfg"

The Manipulator has the capability of using a named "change file" with a list of changes to apply to the TRF file. It will also do incremental changes by using the '+' or '-' character after the value. You can use the incremental change feature to apply changes repeatedly in a loop. You can create different named change files that change only one parameter (e.g., volume changes.txt). Apply different change files in different loops to create multiple changes in one script.

You specify the name of the TRF Manipulator interface reference using the Visual Basic script CreateObject function. For example, you might create the manipulator as follows:

CreateObject( “TSIS.TRFManipulator” )

Then, to call a TRF Manipulator interface function from your script, you would use the following construct:

TRFManipulator.function parameters … … …

In this construct, the TRFManipulator identifies the interface and function is one of the functions summarized in the following table. A "." (a period also known as “dot”) character is used to separate the interface reference and the function name. The list of parameters accepted by the function follow the function name, separated by commas. The table summarizes the functions of this interface. The reference guide in the next chapter provides detailed descriptions of these functions.

Function Definition

AddRecord Adds a record into the section identified by the subnetwork of the current time period.

AddTimePeriod Adds a new time period to the TRF file with the given duration. It adds the necessary record type 210 to the end of the TRF file, and puts the duration onto record type 3.

ApplyChangeFile Reads the given change file, and applies the modifications listed in it to the in-memory TRF file. Change files are described in a separate section below.

CopyLinkRecord Copies the record identified from the current time period into the section identified by Subnetwork of new time period.

CopyNetworkRecord Copies the record identified from the current time period into the section identified by Subnetwork of new time period.

CopyNodeRecord Copies the record identified from the current time period into the section identified by Subnetwork of new time period.

GetDefaultValue Returns the default value for the given entry on the record. This method does not require a TRF file to be loaded into memory.

GetLinkParameter Returns the value of the given entry on the record for the indicated link. The manipulator assumes the upstream node number is the first entry on the record, and the downstream node number is the second. If there is more than one record of the same type for the given link, the value on the first record will be the one returned.

GetMaxValue Returns the maximum value for the given entry on the record. This method does not require a TRF file to be loaded into memory.

GetMinValue Returns the minimum value for the given entry on the record. This method does not require a TRF file to be loaded into memory.

Script Interfaces


Function Definition

GetNetworkParameter Returns the value of the given entry on the record. If there is more than one record of the same type in the current time period, the value on the first record will be the one returned.

GetNodeParameter Returns the value of the given entry on the record for the indicated node. The manipulator assumes the node number is the first entry on the record. If there is more than one record of the same type for the given node, the value on the first record will be the one returned.

GetTimePeriod Returns the current time period.

OpenTRFFile Reads the given TRF file into memory. The file stays in memory until a new file is loaded.

SaveTRFFile Saves the existing in-memory TRF file to the given path.

SetLinkParameter Sets the entry on the record for the link to the given value. The manipulator assumes the upstream node number is the first entry on the record, and the downstream node number is the second. If there is more than one record of the same type for the given link, the value on the first record will be set – the others will remain unmodified.

SetParameterInAll Sets the entry on all records of the type to the given value.

SetNetworkParameter Sets the entry on the record to the given value. If there is more than one record of the same type in the current time period, the value on the first record will be set – the others will remain unmodified.

SetNodeParameter Sets the entry on the record for the node to the given value. The manipulator assumes the node number is the first entry on the record. If there is more than one record of the same type for the given node, the value on the first record will be set – the others will remain unmodified.

SetTimePeriod Sets the current time period. All modifications made to the in-memory TRF file by SetXxxParameter functions affect only the current time period. The time period stays in effect until the next time it is set.

3.5.1 Change Files Change files are simple text files that can be created with any text editor. They consist of comments, directives, and change lines. Comments and blank lines are ignored, and exist only for readability.

3.5.1.1 Comments Change files can be commented. Comments can appear anywhere in the file, but must appear on a line by themselves. Comment lines begin with a ‘#’ character in the first column. A multi-line comment must have the ‘#’ character at the beginning of each line. There can be no white space before the comment character. # This is a comment line. # This is another comment line. # This is an indented comment line. # This is not a comment line, and will cause an error

3.5.1.2 Directives Change file “Directives” tell the manipulator what type of change lines to expect. Change lines tell the manipulator to make the changes. Multiple change lines apply to the previous directive. Directives are similar to the manipulator functions but they are not a direct copy of the functions. The directives are listed in the following paragraphs.

Time Period

To change the active time period, use the time period directive. The time period directive has the keyword “tp” on one line, and the new time period on the next. Blank lines and comments may come between the two lines.

Script Interfaces


# Change the active time period tp # Make it time period 2 2

Add Global The ‘addglobal’ directive puts the manipulator into adding global records mode. Each non-empty/non-comment line after an ‘addglobal’ directive will be treated as a TRF record to be inserted as global record. The record will be inserted as the last record of its type in the current time period. # add records as global records addglobal

Add Fresim The ‘addfresim’ directive puts the manipulator into adding FRESIM records mode. Each non-empty/non-comment line after an ‘addfresim’ directive will be treated as a TRF record to be inserted in the FRESIM subnetwork. The record will be inserted as the last record of its type in the current time period. # add records to the FRESIM subnetwork addfresim

Add Netsim The ‘addnetsim’ directive puts the manipulator into link change mode. Each non-empty/non-comment line after an ‘addnetsim’ directive will be treated as a TRF record to be inserted in the NETSIM subnetwork. The record will be inserted as the last record of its type in the current time period. # add records to the NETSIM subnetwork addnetsim

Add Time Period The ‘addtimeperiod’ directive puts the manipulator into adding time periods mode. Each non-empty/non-comment line after an ‘addtimeperiod’ directive will be treated as a duration of a time period to be added to the TRF file. The duration will be added to the record type 3 and a new record type 210 will be added to the network. The new time period will be the last time period in the network. Once the new time period has been added, the manipulator or change file may reference and change data in the new time period. # add time periods to the network addtimeperiod # add time periods of the following durations to the network 900 900

Copy The ‘copy’ directive puts the manipulator into record copy mode. Subnetwork codes for all 'copy' operations: global = 0, NETSIM = 1, FRESIM = 2 # copy network records copy # record type, new time period, subnetwork # copy record type 142 to time period 2, insert in global subnetwork

Script Interfaces


142 2 0

Copy Link The ‘copylink’ directive puts the manipulator into link copy mode. Subnetwork codes for all 'copy' operations: global = 0, NETSIM = 1, FRESIM = 2 # copy link records copylink # record type, usn, dsn, new time period, subnetwork # copy record type 25 for link [1, 2] to time period 2, insert in # fresim subnetwork 25 1 2 2 2

Copy Node The ‘copynode’ directive puts the manipulator into node copy mode. Subnetwork codes for all 'copy' operations: global = 0, NETSIM = 1, FRESIM = 2 # copy node records copynode # record type, node, new time period, subnetwork # copy record type 35 for node 150 to time period 2, insert in # netsim subnetwork 35 150 2 1

Link

The link directive puts the manipulator into link change mode. All change lines between the link directive and the next directive must be link change lines. Link change lines have five parameters. The first is the record type, the second the entry number, the third the upstream node number, the fourth the downstream node number, and the fifth is the new value. # Set link mode link # Set entry volume for these two links to 400 50 3 8011 711 400 50 3 8031 31 400

Network

The network directive puts the manipulator into network change mode. All change lines between the network directive and the next directive must be network change lines. Network change lines have three parameters. The first is the record type, the second the entry number, and the third is the new value. # Set network mode network # Change the distance to make a lane change on record type 81 entry 14 to # 1200 feet 81 14 1200

Node

Script Interfaces


The node directive puts the manipulator into node change mode. All change lines between the node directive and the next directive must be node change lines. Node change lines have four parameters. The first is the record type, the second the entry number, the third the node number, and the fourth is the new value. # Set node mode node # Set clock-time meter headway at node 50 to 4.5 seconds 37 4 50 45

3.5.1.3 Relative Changes Network, node, and link change lines can also indicate relative changes. A relative change is indicated by a ‘+’ or ‘-’ symbol at the end of the line. The value parameter is added to or subtracted from the current value instead of being set directly. # Set link mode link # Subtract 50 from link [8015, 115] entry volume 50 3 8015 115 50 – # Add 100 to link [8017, 17] entry volume 50 3 8017 17 100 +

3.5.1.4 Example Change File The following text is a sample change file.

# Comments start with the '#' character. The comment character must # be the first character on the line. There can be no white space # before it. network # Network directive. All lines up to the next directive contain # network changes. 3 1 720 # Each network change line must have three numbers separated by tabs # or spaces. # The first number is the record type, the second is the entry number, # and the third is the parameter. node # Node directive. All lines up to the next directive contain node # changes. 37 4 50 45 # Each node change line must have four numbers separated by tabs # or spaces. # The first number is the record type, the second is the entry number, # the third is the node number, and the fourth is the parameter. link # Link directive. All lines up to the next directive contain link # changes.

Script Interfaces


50 3 8011 711 400 50 3 8031 31 400 50 3 8015 115 50 - 50 3 8017 17 50 + # Each link change line must have five numbers separated by tabs # or spaces. # The first number is the record type, the second is the entry number, # the third is the upstream node number, the fourth is the downstream # node number, and the fifth is the parameter. # Relative Changes: # An optional '+' or '-' symbol at the end of any change line # indicates a relative change. The parameter value will be # added or subtracted from the existing value instead of being # applied absolutely.

3.5.2 Example TRF Manipulator Script The following example script opens a supplied simulation file and loops 10 times increasing the volume on two entry links by 100 in each iteration of the loop. It changes the name of the file to reflect the new volume and saves the name of the new file in a text file that contains a list of all the files. This list can then be used in the multi-run script to run CORSIM on each file.

' Create the Manipulator object Set manipulator = CreateObject("TSIS.TRFManipulator") ' Open the trf file. The TRF file is kept in memory. Any changes ' are applied the in-memory data. Only need to open the file once ' unless the input file changes such as doing a multi-file script. manipulator.OpenTRFFile simulationFile ' Get the input TRF file. infile = simulationFile ' Find where the .trf is in the filename string. Need to back up ' one more so the new name and .trf can be added below. PositionOfTRF = InStrRev( simulationFile, ".trf" ) - 1 infile = Left( simulationFile, PositionOfTRF ) ' Open a file to keep track of the files created. ListFileName = infile & ".inp" Set ListFile = fileSystem.CreateTextFile( ListFileName , 2, True ) ' Create a variable called “Volume” and initialize it to 600. Dim volume volume = 600 ' Start Looping For count = 1 to 10 volume = volume + 100 ' Change some entry volumes manipulator.SetLinkParameter 50, 3, 8001, 13, volume manipulator.SetLinkParameter 50, 3, 8010, 14, volume

Script Interfaces


' Apply a Change File manipulator.ApplyChangeFile “volume changes.txt" ' Set the output TRF file. Add the word ‘volume’ and the value. modifiedFile = infile & " volume " & CStr(volume) & ".trf" ' Save the trf file manipulator.SaveTRFFile modifiedFile ' Write the name of the new file to the list of files. ListFile.WriteLine modifiedFile ' In order to do output processing there must be a configuration file. ' Copy the Config file to the new name. fileSystem.CopyFile infile & ".cfg", modifiedFile & ".cfg" Next ' Close the list of file names. ListFile.Close

3.6 Global Variables The Script Tool provides (defines) the following global variable for use within a script:

Variable Definition

gvInstallDirectory This string specifies the directory into which TSIS was installed. The install directory is where the TSIS executable files reside.

gvProjectDirectory This string specifies your default project directory.

Script Interfaces


4 Interface Function Reference Guide

4.1 Output View Control Interface Functions This section provides detailed descriptions of the functions available in the Output View Control interface. Functions are listed in alphabetical order.

4.1.1 Clear This function removes all text from the Output View tab that is associated with the script that calls the function.

Returns

This function returns no value.

Parameters

This function has no parameters.

Example

IOutputControl.Clear

4.1.2 DisplayColoredText This function displays the specified text in the specified color in the Output View tab that is associated with the script that calls the function.

Returns


Parameters

1. Text - a string variable or text string that specifies the text to be displayed. For a text string, the string must be enclosed in quotation marks.

2. Color Index - color index in the range [0,3], where:

0 = color represented by the Output View's information color property,

1 = color represented by the Output View's warning color property,

Script Interfaces


2 = color represented by the Output View's error color property,

3 = color represented by the Output View's background color property.

Example

IOutputControl.DisplayColoredText "The quick brown fox…", 1

4.1.3 DisplayText This function displays the specified text in the Output View tab that is associated with the script that calls the function.

Returns


Parameters

1. Text - a string variable or text string that specifies the text to be displayed. For a text string, the string must be enclosed in quotation marks.

Example

IOutputControl.DisplayText "The quick brown fox…"

The following statement writes a blank line to the Output View.

IOutputControl.DisplayText Chr(10)

4.1.4 SelectLineContainingText This function highlights the line in the script's Output View tab that contains the specified text.

Returns


Parameters

1. Text - a string variable or text string that specifies the text to search for in the Output View tab. For a text string, the string must be enclosed in quotation marks.

Example

IOutputControl.SelectLineContainingText "error"

4.1.5 StartLogging This function starts output logging to the specified file. The specified file will receive all text written to the Output View after this function is called.

Returns


Parameters

1. File - a string variable or text string that specifies the fully-qualified name of the log file. For a text string, the string must be enclosed in quotation marks.

2. Append - when set to 1, text will be appended to the end of the log file if the log file already exists. If 0, a new log file will be created, overwriting any existing log file of the same name.

Example

IOutputControl.StartLogging "C:\TSIS Projects\CORSIM City\CORSIM City.log", 0

Script Interfaces


4.1.6 StopLogging This function terminates Output View logging to the log file specified in the previous call to StartLogging.

Returns


Parameters


Example

IOutputControl.StopLogging

4.2 Script Support Interface Functions This section provides detailed descriptions of the functions available in the Script Support interface. Functions are listed in alphabetical order.

4.2.1 ActivateScriptTab This function enables a script to activate the Output View tab associated with the Script Tool. This brings that tab to the front of the Output View.

Returns


Parameters


Example

IScriptSupport.ActivateScriptTab

4.2.2 CreateCORSIMServer This function enables a script to create a CORSIM Server object so that it can run the CORSIM simulation. Once this function has been called, the script can then access the CORSIM Server interface functions.

Returns


Parameters

1. ServerName - a string variable or text string that specifies a name you wish to give the CORSIM Server interface. For a text string, the string must be enclosed in quotation marks.

Example

IScriptSupport.CreateCORSIMServer "CORSIMServer"

4.2.3 IncludeFile This function adds the contents of the specified file to the script control. This enables a script user to easily add procedures to multiple scripts without having to duplicate the code.

Returns


Script Interfaces


Parameters

1. File - a string variable or text string that specifies the fully-qualified name of the include file. For a text string, the string must be enclosed in quotation marks.

Example

IScriptSupport.IncludeFile gvInstallDirectory + "\Scripts\GetNetworkData.vbs"

In the preceding example, note the use of the gvInstallDirectory global variable, provided by the Script Tool.

4.2.4 LaunchTSISTool This function enables a script to execute the specified TSIS tool.

Returns


Parameters

1. Tool - a string variable or text string that specifies the unique name of the TSIS tool.

2. File - a string variable or text string that specifies the fully-qualified name of the input file. For a text string, the string must be enclosed in quotation marks.

Example

IScriptSupport.LaunchTSISTool "TRAFVU", "C:\TSIS Projects\CORSIM City\CORSIM City.trf"

4.2.5 ReleaseCORSIMServer This function enables a script to release a CORSIM Server object that it created using CreateCORSIMServer.

Returns


Parameters


Example

IScriptSupport.ReleaseCORSIMServer

4.2.6 ScriptTerminated This function enables a script to query the script control to determine if the user has terminated the script execution via the "Stop" button on the toolbar of the Script Tool.

Returns

This function returns a non-zero value if the script has been terminated and zero if the script has not been terminated via the "Stop" button.

Parameters


Example

if IScriptSupport.ScriptTerminated then

MsgBox "Script was terminated."

end if

Script Interfaces


4.2.7 SelectFile This function enables a script to display a file selection dialog so that the user can select a file for processing. This method returns a string containing the selected file (if one was selected).

Returns

This method returns a string containing the name of the selected file. If no file was selected (e.g., the user canceled the dialog) a blank string is returned.

Parameters

1. Title - a string variable or text string that specifies the name placed in the dialog's title bar. For a text string, the string must be enclosed in quotation marks.

2. Filter - a string variable or text string that specifies a file filter for the dialog. If blank, the filter defaults to "All Files (*.*)|*.*||".

3. InitialDir - a string variable or text string that specifies the name of an initial directory displayed by the dialog. If blank, the dialog will initially display a directory in accordance with the rules of the operating system on which the script is running.

Example

rnsFile = IScriptSupport.SelectFile "Select Random Number Seed File", "RNS Files (*.rns)|*.rns|All Files (*.*)|*.*||", gvInstallDirectory

4.2.8 SetMainSub This function sets the name of the "main" procedure that the script control will execute after loading the script. If blank, the script control will execute statements in the order they were written (added) to the script control, beginning with the first statement in the script.

Choosing to place code within a procedure (i.e., Sub) prevents the script from immediately executing the statements at the start of the script. That is, when the "Start" button is pressed, the statements in the "main" procedure are called first. Furthermore, the script control will only execute the statements in the "main" procedure.

Creating a main procedure is not necessary and either mode of operation is acceptable.

Returns


Parameters

1. MainProc - a string variable or text string that specifies the name of the "main" procedure. For a text string, the string must be enclosed in quotation marks.

Example

IScriptSupport.SetMainSub "mymainproc"

4.2.9 WaitForCORSIM This function is used in conjunction with the Run and RunMulti functions of the CORSIM Server and is used to keep the script processor alive until the current CORSIM run has completed.

This operation is necessary when running CORSIM via the server interface Run (or RunMulti) function because that function returns immediately after it is invoked, even though CORSIM is still executing. While CORSIM is running, the script processor MUST stay active. When CORSIM completes, the CORSIM Server signals the script processor so that it can execute the next statement.

This function must be called immediately following the CORSIM Server interface Run or RunMulti functions.

Script Interfaces


Returns


Parameters


Example

' Create the CORSIM Server Object.


' Set the CORSIM.Dll to execute.

CORSIMServer.SetCORSIMDLL gvInstallDirectory + "corsim.dll"

' Set the run parameters for the CORSIM simulation.

aCaseFileName = "C:\TSIS Projects\CORSIM City\CORSIM City.trf"

CORSIMServer.SetIOParams aCaseFileName, 0, 0, 1, 1, "out"

' Run the simulation for the case.

CORSIMServer.Run

IScriptSupport.WaitForCORSIM

4.3 CORSIM Server Interface Functions This section provides detailed descriptions of the functions available in the CORSIM Server interface. Functions are listed in alphabetical order. In the examples, assume that you have created a CORSIM Server of the name "CORSIMServer" by calling the Script Support interface function as follows:


4.3.1 AddExtension This function adds the specified run-time extension (RTE) to the CORSIM Server.

Returns


Parameters

1. Path - a string variable or text string that specifies the fully-qualified name of the RTE DLL. For a text string, the string must be enclosed in quotation marks.

2. InitFunc - a string variable or text string that specifies the name of the "Init" function in the RTE DLL. For a text string, the string must be enclosed in quotation marks.

3. MainFunc - a string variable or text string that specifies the name of the "Main" function in the RTE DLL. For a text string, the string must be enclosed in quotation marks.

4. ExitFunc - a string variable or text string that specifies the name of the "Exit" function in the RTE DLL. For a text string, the string must be enclosed in quotation marks.

5. LoadFlag - set to 1 to call the RTE "Init" function when the RTE DLL is loaded. Set to 0 otherwise.

Script Interfaces


6. UnloadFlag - set to 1 to call the RTE "Exit" function when the RTE DLL is unloaded. Set to 0 otherwise.

Example

CORSIMServer.AddExtension "c:\Program Files\FHWA\TSIS\rte.dll", "MyInit", "MyMain", "MyExit", 0, 1

4.3.2 ClearExtensions This function removes all current run-time extensions (RTE) from the CORSIM Server.

Returns


Parameters


Example

CORSIMServer.ClearExtensions

4.3.3 ExtensionCount This function returns the count of run-time extensions (RTE) added to the CORSIM Server.

Returns

This function returns the number of run-time extensions that have been added to the CORSIM Server

Parameters


Example

nExtensions = CORSIMServer.ExtensionCount

4.3.4 GetExtension This function returns the definition of the specified run-time extension (RTE).

Returns


Parameters

1. Index - index (zero-based) of the RTE for which information will be returned.

2. Path - a string variable that contains the fully-qualified name of the specified RTE DLL.

3. InitFunc - a string variable that contains the name of the "Init" function in the specified RTE DLL.

4. MainFunc - a string variable that contains the name of the "Main" function in the specified RTE DLL.

5. ExitFunc - a string variable that contains the name of the "Exit" function in the specified RTE DLL.

6. LoadFlag - returned as 1 if the server is set to call the RTE "Init" function when the RTE DLL is loaded. Returned as 0 otherwise.

7. UnloadFlag - returned as 1 if the server is set to call the RTE "Exit" function when the RTE DLL is unloaded. Returned as 0 otherwise.

Example

CORSIMServer.GetExtension 0, RTEPath, RTEInit, RTEMain, RTEExit, bLoad, bUnload

Script Interfaces


4.3.5 Run This function executes a single run of the CORSIM simulation as specified by the run parameters.

Returns


Parameters


Example

CORSIMServer.Run

4.3.6 RunMulti This function executes a multiple run of the CORSIM simulation as specified by the multi-run parameters.

Returns


Parameters


Example

CORSIMServer.RunMulti

4.3.7 SetCORSIMDLL This function specifies the dynamic-link library that contains the CORSIM simulation which the CORSIM Server will use. This enables the script to use different versions of the CORSIM simulation.

Returns


Parameters

1. Path - a string variable or text string that specifies the fully-qualified name of the CORSIM DLL. For a text string, the string must be enclosed in quotation marks.

Example

CORSIMServer.SetCORSIMDLL gvInstallDirectory + "corsim.dll"

4.3.8 SetIOParams This function controls the input and output of the CORSIM simulation run.

Returns


Script Interfaces


Parameters

1. InputFile - a string variable or text string that specifies the fully-qualified name of the simulation input file. For a text string, the string must be enclosed in quotation marks.

2. TSDFlag - set to 1 to have the server create a time-step data file. Set to 0 otherwise.

3. TIDFlag - set to 1 to have the server create a time-interval data file. Set to 0 otherwise.

4. SyncFlag - set to 0 to have the operating system determine when data should be written to disk. Set to 1 to have the server write data at the end of every time step.

5. OutFlag - set to 1 to have the simulation create a CORSIM output data file. Set to 0 otherwise.

6. OutExt - a string variable or text string that specifies the name of the output file extension (does not include the "." delimiter). For a text string, the string must be enclosed in quotation marks.

7. CSVFlag - set to 1 to have the simulation create a CSV output file. Set to 0 otherwise.

Example

simulationFile = "C:\TSIS Projects\CORSIM City\CORSIM City.trf"

CORSIMServer.SetIOParams simulationFile, 1, 1, 0, 1, "out", 1

4.3.9 SetMultiRunParams This sets the simulation control parameters for a multi-run using the RunMulti function.

Returns


Parameters

1. NumberRuns - specifies the number of simulation runs.

2. Animate - set to 1 to generate animation data files for each run. Set to 0 otherwise.

3. GenOut - set to 1 to generate the simulation output file for each run. Set to 0 otherwise.

4. GenCSV - set to 1 to generate the simulation output CSV file for each run. Set to 0 otherwise.

5. KeepTRF - set to 1 to keep the TRF files for each individual run. Set to 0 otherwise.

6. RNSFile - a string variable or text string that specifies the fully-qualified name of the random number seed file. For a text string, the string must be enclosed in quotation marks.

7. Headway - random number code for the Headway random number seed:

0 = constant ,

1 = read from file,

2 = generate randomly.

8. Vehicle - random number code for the Vehicle random number seed (see parameter 5 for codes).

9. Traffic - random number code for the Traffic random number seed (see parameter 5 for codes).

10. LogRNS - set to 1 to generate a log file of the random number seeds that are used. Set to 0 otherwise.

Example

rnsFile = gvInstallDirectory + "random.rns"

CORSIMServer.SetMultiRunParams 10, 0, 1, 1, 0, rnsFile, 1, 1, 1, 1

Script Interfaces


4.3.10 SetRunParams This function sets the simulation control parameters for a single run using the Run function. In general, these parameters are used for synchronizing the simulation with other tools.

Returns


Parameters

1. PauseInitially - set to 1 to have the server pause the simulation after it reaches equilibrium but before it executes the first time step.

2. StepDelay - specifies the amount of delay (in milliseconds) between successive time-step executions.

Example

CORSIMServer.SetRunParams 0, 0

4.4 TRF Manipulator Interface Functions The TRF Manipulator is a COM component. It must be registered on the computer where it will be used. After it is used it can be created using its Programmatic ID. Programmatic ID: “TSIS.TRFManipulator” VBScript Creation: Set manipulator = CreateObject(“TSIS.TRFManipulator”) VB Creation: Dim manipulator As TRFManipulator Set manipulator = New “TSIS.TRFManipulator” The following methods can be called in the TRF Manipulator:

4.4.1 AddRecord Adds a record into the section identified by the subnetwork of the current time period.

Returns


Parameters

1. Record As String – This is the full 80 character record to add.

2. Subnetwork As Integer – This is the subnetwork of the file where the record will be added where subnetwork identifiers are GLOBAL = 0, NETSIM = 1, FRESIM = 2.

Example VB Declaration: AddRecord(Record As String, Subnetwork As Integer)

4.4.2 AddTimePeriod Adds a new time period to the TRF file with the given duration. It adds the necessary record type 210 to the end of the TRF file, and puts the duration onto record type 3. Once the new time period has been added, the manipulator or change file may reference and change data in the new time period.

Script Interfaces


Returns


Parameters

1. Duration As Integer – This is the duration of the new time period. The duration will be added to the record type 3.

Example VB Declaration: AddTimePeriod(Duration As Integer)

4.4.3 ApplyChangeFile Reads the given change file, and applies the modifications listed in it to the in-memory TRF file. Change files are described in a separate section in the previous chapter.

Returns


Parameters

1. PathName As String – This is the path to the change file.

Example VB Declaration: ApplyChangeFile(PathName As String)

4.4.4 CopyLinkRecord Copies the record identified from the current time period into the section identified by Subnetwork of time period NewPeriod.

Returns


Parameters

1. Record As Integer – This is the record number.

2. USN As Integer – This is the upstream node of the link in question.

3. DSN As Integer – This is the downstream node of the link in question.

4. Period As Integer – This is the time period where the record will be copied to.


Example VB Declaration: CopyLinkRecord(RecordType As Integer, UpNode As Integer, DnNode As Integer, NewPeriod As Integer, Subnetwork As Integer)

4.4.5 CopyNetworkRecord Copies the record identified from the current time period into the section identified by Subnetwork of time period NewPeriod.

Returns


Script Interfaces


Parameters




Example VB Declaration: CopyNetworkRecord(RecordType As Integer, NewPeriod As Integer, Subnetwork As Integer)

4.4.6 CopyNodeRecord Copies the record identified from the current time period into the section identified by Subnetwork of time period NewPeriod.

Returns


Parameters


2. Node As Integer – This is the node number for the data requested.



Example VB Declaration: CopyNodeRecord(RecordType As Integer, Node As Integer, NewPeriod As Integer, Subnetwork As Integer)

4.4.7 GetDefaultValue Returns the default value for the given entry on the record. This method does not require a TRF file to be loaded into memory.

Returns

This function returns an integer value of the default value for the given entry on the record.

Parameters


6. Entry As Integer – This is the entry number on the specified record.

Example VB Declaration: GetDefaultValue(Record As Integer, Entry As Integer) As Integer

4.4.8 GetLinkParameter Returns the value of the given entry on the record for the indicated link. The manipulator assumes the upstream node number is the first entry on the record, and the downstream node number is the second. If there is more than one record of the same type for the given link, the value on the first record will be the one returned.

Script Interfaces


Returns

This function returns an integer value of the entry for the given link on the record requested.

Parameters





Example VB Declaration: GetLinkParameter(Record As Integer, Entry As Integer, USN As Integer, DSN

As Integer) As Integer

4.4.9 GetMaxValue Returns the maximum value for the given entry on the record. This method does not require a TRF file to be loaded into memory.

Returns

This function returns an integer value of the maximum value for the given entry on the record.

Parameters



Example VB Declaration: GetMaxValue(Record As Integer, Entry As Integer) As Integer

4.4.10 GetMinValue Returns the minimum value for the given entry on the record. This method does not require a TRF file to be loaded into memory.

Returns

This function returns an integer value of the minimum value for the given entry on the record.

Parameters



Example VB Declaration: GetMinValue(Record As Integer, Entry As Integer) As Integer

4.4.11 GetNetworkParameter Returns the value of the given entry on the record. If there is more than one record of the same type in the current time period, the value on the first record will be the one returned.

Returns

This function returns an integer value of the network-wide value for the given entry on the record.

Script Interfaces


Parameters



Example VB Declaration: GetNetworkParameter(Record As Integer, Entry As Integer) As Integer

4.4.12 GetNodeParameter Returns the value of the given entry on the record for the indicated node. The manipulator assumes the node number is the first entry on the record. If there is more than one record of the same type for the given node, the value on the first record will be the one returned.

Returns

This function returns an integer value of the value for the given entry on the record for the given node.

Parameters




Example VB Declaration: GetNodeParameter(Record As Integer, Entry As Integer, Node As Integer) As

Integer

4.4.13 GetTimePeriod Returns the current time period.

Returns

This function returns the current time period in use by the TRF Manipulator.

Parameters

This function requires no parameters.

Example VB Declaration: GetTimePeriod() As Integer

4.4.14 OpenTRFFile Reads the given TRF file into memory. The file stays in memory (with any modifications made by SetXxxxParameter functions and/or change files) until a new file is loaded.

Returns


Parameters

1. PathName As String – This is the path to the TRF file to open.

Example VB Declaration: OpenTRFFile(PathName As String)

Script Interfaces


4.4.15 SetLinkParameter Sets the entry on the record for the link to the given value. The manipulator assumes the upstream node number is the first entry on the record, and the downstream node number is the second. If there is more than one record of the same type for the given link, the value on the first record will be set – the others will remain unmodified.

Returns


Parameters





5. Parameter As Integer – This is the value of the parameter.

Example VB Declaration: SetLinkParameter(Record As Integer, Entry As Integer, USN As Integer, DSN

As Integer, Parameter As Integer)

4.4.16 SetNetworkParameter Sets the entry on the record to the given value. If there is more than one record of the same type in the current time period, the value on the first record will be set – the others will remain unmodified.

Returns


Parameters




Example VB Declaration: SetNetworkParameter(Record As Integer, Entry As Integer, Parameter As

Integer)

4.4.17 SetNodeParameter Sets the entry on the record for the node to the given value. The manipulator assumes the node number is the first entry on the record. If there is more than one record of the same type for the given node, the value on the first record will be set – the others will remain unmodified.

Returns


Script Interfaces


Parameters





Example VB Declaration: SetNodeParameter(Record As Integer, Entry As Integer, Node As Integer,

Parameter As Integer)

4.4.18 SetParameterInAll Sets the entry on all records of the type to the given value.

Returns


Parameters




Example VB Declaration: SetParameterInAll(Record As Integer, Entry As Integer, Parameter As

Integer)

4.4.19 SetTimePeriod Sets the current time period. All modifications made to the in-memory TRF file by SetXxxParameter methods affect only the current time period. The time period stays in effect until the next time it is set. Note: the ApplyChangeFile method will leave the time period set to the last value used in the change file – not the last value set before calling ApplyChangeFile.

Returns


Parameters

1. Period As Integer – This is the time period value that will be used by the TRF Manipulator.

Example VB Declaration: SetTimePeriod(Period As Integer)

4.4.20 SaveTRFFile Saves the existing in-memory TRF file to the given path.

Returns


Script Interfaces


Parameters

1. PathName As String – This is the path to the TRF file to open.

Example VB Declaration: SaveTRFFile(PathName As String)

Pre-defined Scripts


5 Pre-defined Scripts

5.1 Overview Included with the TSIS installation are several pre-defined scripts that simplify repetitive execution of the CORSIM simulation. These sample scripts also serve as examples for writing scripts in the TSIS environment. You can use these scripts as is or tailor them to meet your needs. Script files reside in the Scripts folder under the directory to which TSIS was installed. Also, you can open the example scripts from the sub-menu that appears when you select the Tools|Scripts menu item.

5.2 Script Summaries

5.2.1 GetNetworkData.vbs This script contains a single Sub procedure that extracts simulation-generated output data from the CORSIM output data file. This script can be included in other scripts using the IncludeFile function of the Script Support interface.

The primary intent of providing this script is to demonstrate how you can use a script to extract output data from a file. It extracts only network-wide statistics from the CORSIM output data file. It is included in several of the other pre-defined scripts that are provided with the TSIS package.

5.2.2 Single-Run Many Cases.vbs This script executes CORSIM once for each case file on the list contained in a user-specified input file. This is useful when "batch" processing a large number of CORSIM cases.

The input file simply contains a list of CORSIM input files (cases) to process. Each line in the input file specifies the full path and name of a single CORSIM input file. You can use any text editor to create this file. Although you can name this file anything you want, the script defaults to looking for files with an INP extension.

5.2.3 Single-Run Many Cases Saving Network Data.vbs This script executes CORSIM once for each case file on the list contained in a user-specified input file. This is useful when "batch" processing a large number of CORSIM cases. This script also extracts network-wide statistics from the output file generated during each run and places those statistics in a comma-separated value file.

Script Interfaces



5.2.4 Multi-Run Same Case.vbs This script executes CORSIM multiple times for a single case (input) file, applying different random number seeds in each run of the simulation. Because CORSIM is a Monte Carlo type simulation, multiple runs with different random number seeds is required to achieve valid average values for the measures of effectiveness produced by the simulation model.

5.2.5 Multi-Run Same Case Saving Network Data.vbs This script executes CORSIM multiple times for a single case (input) file, applying different random number seeds in each run of the simulation. Because CORSIM is a Monte Carlo type simulation, multiple runs with different random number seeds is required to achieve valid average values for the measures of effectiveness produced by the simulation model.

This script also extracts network-wide statistics from the output files generated during each run and places those statistics in a comma-separated value file.

5.2.6 Multi-Run Many Cases.vbs This script executes CORSIM multiple times for each case file on the list contained in a user-specified input file. This is useful when "batch" processing a large number of CORSIM cases. For each run of each case, the script applies different random number seeds. Because CORSIM is a Monte Carlo type simulation, multiple runs with different random number seeds is required to achieve valid average values for the measures of effectiveness produced by the simulation model.


5.2.7 Multi-Run Many Cases Saving Network Data.vbs This script is a combination of all the other scripts. It executes CORSIM multiple times for each case file on the list contained in a user-specified input file. This is useful when "batch" processing a large number of CORSIM cases. For each run of each case, the script apples different random number seeds. Because CORSIM is a Monte Carlo type simulation, multiple runs with different random number seeds is required to achieve valid average values for the measures of effectiveness produced by the simulation model.


This script also extracts network-wide statistics from the output files generated during each run and places those statistics in a comma-separated value file.

Glossary of Terms


6 Glossary of Terms

Accelerator Key Accelerator keys (also known as shortcut keys) are used as keyboard shortcuts for program commands that are also available on a menu or toolbar.

ATMS Advanced Traffic Management Systems

Case A single simulation for a specified traffic network as defined by its simulation input file. A case includes the simulation input file and all data files generated by the simulation during a run. Note, multiple runs of the simulation for gathering statistics is still considered part of a single case if the input has not changed.

Copy This operation copies the selected text or object from the active document and places the copied selection into the Windows clipboard. The Ctrl+X key is an accelerator key for this command.

CORSIM CORridor SIMulation. This is a microscopic traffic simulation used to generate the vehicle information used by TRAFVU.

CORSIM Server An application software component used by the Script Tool and other TSIS tools to execute the CORSIM simulation.

CORSIM Server Interface An interface, implemented by the CORSIM Server, that enables a script to control the settings and execution of the CORSIM simulation.

Glossary of Terms


Cut This operation removes the selected text or object from the active document and places the selection into the Windows clipboard. The Ctrl+X key is an accelerator key for this command.

DOT Department of Transportation

FHWA Federal Highway Administration. Sponsor for the development of the TSIS suite of traffic analysis tools.

Global Variable A variable, provided by the Script Tool, containing information about TSIS that is available for use in scripts designed to be executed by the TSIS Script Tool.

Graphical User Interface An interface between a user and a software tool, consisting of graphical elements and controls, e.g., windows, dialogs, buttons.

GUI Graphical User Interface

HTML Hypertext Markup Language is a system of marking up or tagging a document so that it can be published on the World Wide Web. It is used to display Script Tool on-line help.

INP A file that contains a list of cases to be executed in the TSIS-provided Multi-Run Many Cases script.

Output View The Output View is a dockable control window in the TShell interface that displays the output generated by the traffic tools as they operate on files.

Output View Control Interface An interface, implemented by the Script Tool, that provides a script access to functions that control the TShell Output View.

Overstrike Mode When this mode is active, text is replaced as you type in the text document. When inactive, the text you type is inserted at the location of the caret.

Glossary of Terms


Paste This operation inserts the contents from the Windows clipboard into the active document at the location of the caret. If there is a current selection in the document, this command replaces the selection with the contents of clipboard. The Ctrl+V key is an accelerator key for this command.

Project View The Project View is a dockable control window in the TShell interface that displays a hierarchical tree structure of projects, cases, and case files. Using this tree structure, you can efficiently manage your traffic analysis projects and execute tools on project files.

Script Support Interface An interface, implemented by the Script Tool, that provides functions used to control and execute scripts within the Script Tool. It also provides additional support functions not offered by the Microsoft Script engine.

Tool A program or component that is installed into the TSIS environment for use in conducting traffic operations analysis. A tool can be an application (EXE), Dynamic Link Library (DLL), COM object or ActiveX Control (OCX), or a batch program (BAT).

Tool Tip A small rectangular pop-up window that displays a brief description of a command bar (toolbar) button's purpose.

TRF A file that contains the input data, in record format, used to define a CORSIM network and to drive the CORSIM simulation for a single simulation case.

TShell The graphical user interface for the TSIS integrated development environment. It provides a Project View that enables you to manage your TSIS projects. It is also the container for the pre-configured tools and any tools that you add to the suite.

TSIS Traffic Software Integrated System. TSIS is the integrated development environment that hosts the CORSIM simulation and its support tools.

TSIS Web Site This web site, http://mctrans.ce.ufl.edu/featured/tsis, contains the latest information about new tools, product updates, known problems, example projects, and usage tips.

VBS A file that contains a Visual Basic script. The extension of script files is VBS.

Glossary of Terms


VBScript The Microsoft Visual Basic script engine used to execute Visual Basic scripts. VBScript is a lightweight and extremely fast language engine designed specifically for environments like the Internet, intranets, or the World Wide Web.

Visual Basic script A file that contains Visual Basic scripting language to be executed using the VBScript engine.

Index


7 Index

A accelerator keys 2-2, 2-3, 6-1, 6-2, 6-3

C caret 2-3, 6-2, 6-3 caret position 2-5 copying text 2-3, 3-4, 3-6, 3-7, 3-10, 6-1 CORSIM 1-1, 3-1, 3-2, 3-3, 3-9, 4-2, 4-3, 4-4, 4-5,

4-6, 4-7, 4-8, 4-9, 5-1, 5-2, 6-1, 6-3 CORSIM Server 3-2, 3-3, 4-3, 4-4, 4-5, 4-6, 4-7,

4-8, 6-1 CORSIM Server Interface 3-3, 4-6, 6-1 creating a new script 2-1, 3-5, 3-9, 3-10, 4-14 cutting text 2-3, 6-2

D deleting text 2-3

E Edit menu 2-2 editing operations

copying text 2-3 cutting text 2-3 deleting text 2-3 finding text 2-3 pasting text 2-3 redo last operation 2-2 selecting text 2-2 undo last operation 2-2

example scripts 2-6, 3-9, 5-1 extension 2-6, 3-3, 4-6, 4-7, 4-9, 5-1, 5-2, 6-3

F Federal Highway Administration i, v, 4-7, 6-2 File menu 2-1, 2-2 file type 2-1, 2-2, 2-6

files creating a new script 2-1 opening an existing script 2-2 saving a script file 2-2, 5-1, 5-2 types 2-1, 2-2, 2-6, 3-3, 4-6, 4-7, 4-9, 5-1, 5-2, 6-

3 finding text 2-3, 3-9

G global variables 3-10, 4-4, 6-2

I INP file 5-1, 5-2, 6-2 interface functions

CORSIM Server AddExtension 3-3, 4-6, 4-7 ClearExtensions 3-3, 4-7 ExtensionCount 3-3, 4-7 GetExtension 3-3, 4-7 Run 3-2, 3-3, 4-5, 4-6, 4-8, 4-10, 5-1, 5-2, 6-2 RunMulti 3-2, 3-3, 4-5, 4-8, 4-9 SetCORSIMDLL 3-3, 4-6, 4-8 SetIOParams 3-3, 4-6, 4-8, 4-9 SetMultiRunParams 3-3, 4-9 SetRunParams 3-3, 4-10

Output View Clear 3-1, 4-1 DisplayColoredText 3-1, 4-1, 4-2 DisplayText 3-1, 4-2 SelectLineContainingText 3-1, 4-2 StartLogging 3-2, 4-2, 4-3 StopLogging 3-2, 4-3

Script Support ActivateScriptTab 3-2, 4-3 CreateCORSIMServer 3-2, 3-3, 4-3, 4-4, 4-6 IncludeFile 3-2, 4-3, 4-4, 5-1 LaunchTSISTool 3-2, 4-4 ReleaseCORSIMServer 3-2, 4-4 ScriptTerminated 3-2, 4-4 SelectFile 3-2, 4-5 SetMainSub 3-2, 4-5 WaitForCORSIM 3-2, 4-5, 4-6

TRF Manipulator AddRecord 3-4, 4-10, 4-11 ApplyChangeFile 3-4, 4-11, 4-16 CopyLinkRecord 3-4, 4-11 CopyNetworkRecord 3-4, 4-11, 4-12 CopyNodeRecord 3-4, 4-12 GetDefaultValue 3-4, 4-12 GetLinkParameter 3-4, 4-12, 4-13 GetMaxValue 3-4, 4-13 GetMinValue 3-4, 4-13 GetNetworkParameter 3-5, 4-13, 4-14 GetNodeParameter 3-5, 4-14

Index


GetTimePeriod 3-5, 4-14 OpenTRFFile 3-5, 3-9, 4-14 SaveTRFFile 3-5, 3-10, 4-16, 4-17 SetLinkParameter 3-5, 3-9, 3-10, 4-15 SetNetworkParameter 3-5, 4-15 SetNodeParameter 3-5, 4-15, 4-16 SetParameterInAll 3-5, 4-16 SetTimePeriod 3-5, 4-16

interfaces CORSIM Server 3-3, 4-6, 6-1 Output View Control 3-1, 4-1, 6-2 Script Support 3-2, 4-3, 6-3 TRF Manipulator 3-3, 4-10

IOutputControl 3-1, 4-1, 4-2, 4-3 IScriptSupport 3-2, 4-3, 4-4, 4-5, 4-6 ITT Industries, Inc., Systems Division i

M menus 2-1, 2-2, 2-3, 2-4, 2-5, 5-1, 6-1

Edit 2-2 File 2-1, 2-2

Microsoft ii, 1-1, 2-2, 2-6, 3-2, 6-3, 6-4

N Notepad 2-2

O opening an existing script 2-2, 2-6, 3-3, 3-9, 4-14,

4-17, 5-1 Output View 3-1, 3-2, 4-1, 4-2, 4-3, 6-2 Output View Control Interface 3-1, 4-1, 6-2 overstrike mode 2-5, 6-2

P pasting text 2-3, 6-3 Project View 2-2, 6-3

R random number seeds 4-9, 5-2 redo last edit operation 2-2

S Save As 2-2 saving a script file 2-1, 2-2, 2-4, 2-6, 3-3, 3-10, 5-

1, 5-2 Script Support Interface 3-2, 4-3, 6-3 selecting text 2-2 status bar 2-1, 2-5

T toolbars 2-1, 2-2, 2-3, 2-5, 2-6, 4-4, 6-1, 6-3 tools i, iii, v, 1-1, 2-1, 2-2, 2-4, 2-5, 2-6, 3-1, 3-2,

3-3, 3-10, 4-3, 4-4, 4-10, 6-1, 6-2, 6-3 TRF file 3-3, 3-4, 3-5, 3-6, 3-9, 3-10, 4-10, 4-11,

4-12, 4-13, 4-14, 4-16, 4-17, 6-3 TRF Manipulator Interface 3-3, 4-10 TRFManipulator 3-4, 3-9, 4-10

U Undo / Redo Last Action 2-2 undo last edit operation 2-2

V VBS file 2-1, 2-2, 6-3 VBScript ii, 1-1, 4-10, 6-4 Visual Basic scripts 1-1, 3-1, 3-4, 6-3, 6-4

W Windows ii, 2-3, 6-1, 6-2, 6-3

script users guide - educating global leadersmsaito/ce662ms/user... · using the script tool script...

Documents