1 Welcome to GISDK Help

1 Preface

TransCAD®, out of the box, is a very powerful and versatile computer program. But, if you are an advanced user or a programmer, you may want to do more or different things that are offered by the standard user interface. The Geographic Information System Developer’s Kit (GISDK) provides you with a tool kit that you can use to get outside the box and customize TransCAD in any way you desire. GISDK(tm) is a collection of software tools and documentation that come with TransCAD and make it possible to automate repetitive TransCAD tasks, create user designed add-ins, integrate other programs, or build custom applications. GISDK also makes it possible to call the TransCAD functionality from other software applications. The primary component of the GISDK is a programming language called Caliper Script(tm). This is an easyto-learn, BASIC-like programming language that provides a way to interact with the TransCAD program and data. Caliper Script is a programming language that is powerful, but easy to use. It is more flexible and powerful that the languages provided with other transportation software. Also code written in other languages such as C or FORTRAN can be intermixed with GISDK programs written in Caliper Script, facilitating compatibility with existing software. The primary use of the Caliper Script is to interact with TransCAD. There are over one thousand GISDK functions in TransCAD, all of which can be called from Caliper Script. These functions give users a wide variety of tools that range from managing maps and display characteristics to creating, accessing, updating and analyzing data and data structures, including matrices and networks. In addition, the GISDK functions can be called using Windows Automation, since TransCAD can act as both an Automation Server and Client. TransCAD for the Web uses this way to write code that can be run by a web browser and call TransCAD to provide maps, driving directions and other services. Caliper Script also provides the capability to program complete, custom Windows interfaces for TransCAD applications. Caliper Script, in turn, is supported by three components: a compiler, a debugger and a toolbox for interacting with the compiler and debugger. The GISDK Compiler takes the Caliper Script code and creates a UI Database that can be run with the TransCAD platform. Any errors in the code will be reported by the compiler, with details about the type and location of the error. The GISDK Debugger runs the Caliper Script code in testing mode to make sure that there are no errors, such as errors in logic or variable handling. If the code does not behave as expected, the debugger allows the user to set breakpoints or to step through the code one line at a time, to make sure that the code is executing as expected. The GISDK Toolbox not only has buttons to run the compiler and the debugger but also has tools to make interacting with the program faster and easier. The GISDK for Standard TransCAD has two additional components. The first is Batch Mode, which is a

simpler way of automating transportation analysis. The second is the ability to access TransCAD Matrix DLLs directly from C and FORTRAN. The Matrix DLLs are provided for Visual C and Compaq Visual FORTRAN. For running travel demand applications and for some routing and logistics procedures, TransCAD has a Batch Mode capability that makes it easy to create automated model runs. Caliper provides the source code for the batch model scripts and TransCAD has a tool for generating the scripts interactively. This greatly reduces the possibility of error entering the model application scripts. The scripts can be easily modified by users and consultants. Also, it is easy to augment the scripts with additional functions such as producing specific maps or reports. For more information, see: About You About the Book and this On-Line Help Other GISDK Resources Licensing of GISDK Add-Ins and Applications GISDK Versions If You Need More Help

About You

We made several assumptions about you when we put the GISDK Programmer’s Guide and On-Line Help together: •

•

•

•

You are a frequent user of TransCAD and are familiar with the terms and concepts covered in the User ’s Guide. If you wish to use Batch Mode, which is part of Standard TransCAD, you should also be familiar with the terms and concepts covered in the Travel Demand Modeling User’s Guide. You have some basic knowledge and experience in programming, either in Basic, Visual Basic, C, or some other language. You want to automate or customize TransCAD to help you accomplish your work more efficiently, or to provide assistance to other users. You want to get started quickly, without weeks of training or hard work.

About the Book and this On-Line Help

The GISDK Programmer’s Guide gives you the essential background information that you need to start using GISDK. The full GISDK documentation is provided electronically as part of this On-Line Help system. This comprehensive On-Line Help system gives you detailed background, instructions, a complete listing of the

GISDK functions, and samples in a clear and concise layout. Together, the GISDK Programmer’s Guide and this On-Line Help system describe everything you need to know to start using GISDK. In the GISDK Programmer’s Guide: Chapter 1, Introduction, provides an introduction to GISDK and an overview of its capabilities, along with instructions for starting the GISDK Toolbox and the GISDK Debugger. Chapter 2, Quick Start, provides a concise overview of how you use GISDK to build applications to automate repetative tasks. If you are an experienced developer, this chapter provides most of the information you need to get started. If you are less experienced at software and application development, it will give you a good overview of the process and a feel for how the language works. Chapter 3, GISDK Mechanics, describes the tools that come with GISDK, including the GISDK Toolbox and the GISDK Debugger, and how you use these tools to write and develop add-ins and custom applications, and access TransCAD as an application server. In addition, this On-Line Help system contains comprehensive information on calling GISDK functions, on creating GISDK macros, and on other GISDK applications. This On-Line Help system includes a complete listing of the GISDK functions. The additional sections in this On-Line Help for GISDK include: Common Calling Conventions: standards that are used for arguments in GISDK functions • Using GISDK Functions: overviews of GISDK functions by topic, including windows, maps, layers, editors, tables, and views • Using Projections and Coordinate Systems: details on setting a map's projection or coordinate system, including units, ellipsoids, datums, and transformations • Listing of GISDK Functions: individual descriptions of the GISDK functions, including syntax, return values, and examples • GISDK Mechanics: the compilation tools that come with GISDK and how you use them to write and develop add-ins and custom applications, how to use the debugger to help you find and fix runtime problems in your GISDK macros, and how to access TransCAD as an Automation Server • Language Elements: the syntax, organization, and elements of the Caliper Script language • Resources: introduction to and explanation of the format and structure of the resource files that contain your add-in or custom application • Standard Interface Macros: a listing of macros in the standard interface useful in custom applications for closing files, setting styles, and other tasks, plus geocoding and other macros •

Batch Mode, which comes with Standard TransCAD, is an easy way to create and run planning models as a set of Caliper Script macros, as well as to run some of the routing and logistics procedures. Batch Mode for transportation planning is described in the Travel Demand Modeling with TransCAD User's Guide and in the on-line Help for Planning. Batch Mode for routing and logisitics procedures is described in the Routing and Logistics with TransCAD User's Guide and in the on-line Help for Routing. If you have purchased TransCAD for the Web, the TransCAD for the Web User's Guide and the on-line Help for TransCAD for the Web explain how to use GISDK functions and GISDK macros in web mapping

applications.

Other GISDK Resources

The GISDK Programmer’s Guide and On-Line Help give some examples of how you can use GISDK. More examples are available on the Caliper Corporation web site ( WWW.CALIPER.COM/ADDINS.HTM). You are free to adopt and adapt these Caliper Script and Automation Server examples to meet your own needs. You are also encouraged to contribute to the growing list of examples, so that others can benefit.

Licensing of GISDK Add-Ins and Applications

GISDK enables you to create add-ins, custom applications, or Automation Servers. GISDK also makes it possible for third parties to create and distribute add-ins and custom applications. We expect that many GISDK users will fall into one of three classes: Individual users who want to automate or simplify tasks they routinely perform with TransCAD Internal systems staff who develop add-ins and applications to be used by others within their organization • Developers, resellers, and consultants who use TransCAD along with GISDK to provide custom enduser solutions • •

Caliper Corporation offers additional technology for the creation and distribution of run-time versions of custom applications. This technology enables us to create for you a complete stand-alone program (one that does not need the TransCAD program files) that incorporates all the required GIS functionality for your application. Run-time licensing involves the payment of a processing fee plus technology license fees that are negotiated on a case-by-case basis. When you develop an add-in or custom application using GISDK, the product is a user interface database (UI Database) containing the add-in or custom application. Provided that you comply with the TransCAD license agreement, you may distribute, sell, or give away completed UI Databases containing your add-ins or custom applications. You may also distribute, sell, or give away Caliper Script source code that you create for your GISDK programs. At the same time, the TransCAD license agreement imposes certain restrictions upon you. For example,

you are not permitted to copy or distribute:

• • • •

The TransCAD program file (TCW.EXE) The supporting dynamic link libraries (DLLs) Geographic and tabular data files that are provided with Caliper GIS products Any files that are part of the TransCAD product package

The license agreement for TransCAD for the Web gives you rights to create, test, and publish web mapping applications that access TransCAD as an Automation Server. Other licensing arrangements (such as runtime licenses) are available for other forms of access to TransCAD as an Automation Server. If you have any questions about the above licensing information, please discuss them with us.

GISDK Versions

There are different versions of GISDK for each Caliper Corporation GIS package. All of the versions of GISDK share a common language structure and syntax, and many common functions. However, products developed with one version of GISDK (such as TransCAD) cannot be delivered to users of a different product (such as Maptitude). The TransCAD version of GISDK includes a substantial number of additional functions that support the map display and transportation analysis capabilities of TransCAD, including functions for creating and maintaining networks, route systems, surfaces, matrices, and transit schedules. If you have Standard TransCAD you also have access to Batch Mode and the Matrix DLLs.

If You Need More Help

If you find yourself stuck or in need of additional assistance, please contact our Technical Support department. NOTE: You must be a registered user to receive Caliper Technical Support Services. Register your software by faxing or mailing in the registration card that came with your software package, or by filling out the Caliper Corporation Internet registration form at HTTP://WWW.CALIPER.COM/REGISTER.HTM. Caliper Corporation software support services are subject

to support fees and terms in place at the time the services are used. You can get technical support from Caliper Corporation in four ways: 1. FAX your requests for help to (617) 527-5113.

2. Check the technical support notes at Caliper Corporation’s World Wide Web site (WWW.CALIPER.COM). 3. Send e-mail via the Internet to [email protected]. 4. Call Caliper Technical Support at (617) 527-8617. You can reach TransCAD Technical Support by telephone between 8:30 a.m. and 5:30 p.m., Eastern Time, Monday through Friday. When you call, please be at your computer, have your documentation available, and be prepared to provide the following information: •

The product registration number

•

Your name and organization

• •

The version of the product you are using – choose Help-About to check your version number The exact wording of any messages that appear on your screen

Introduction

As an experienced TransCAD user, you may have thought about how nice it would be to automate some task that you perform on a regular basis, so you could accomplish it by clicking a single button or choosing a single menu item. Perhaps you have thought about creating a custom application, one that has a subset of the capabilities of TransCAD, but organized and structured differently to appeal to a particular audience. You may also have thought about calling TransCAD from another programming environment, such as Visual Basic, to provide transportation analysis or mapping services to an application, such as finding a route or displaying a map around a location. If you have had these thoughts, the GIS Developer’s Kit is for you. GISDK lets you customize and extend the capabilities of TransCAD in almost any way you like. There are three types of things you can do with GISDK: Create add-ins that extend the capabilities of TransCAD or that automate repeated operations • Build custom applications that extend or replace the standard interface to provide customized program operation • Access TransCAD as an Automation Server to add maps or transportation analysis functions to your own programs •

In addition, the planning and the routing and logistics procedures in standard TransCAD offer Batch Mode as a way to build code for applications that you can then run repeatedly without the need for user intervention.

For more information, see: About Add-Ins About Custom Applications About Batch Mode About Accessing TransCAD as an Automation Server GISDK System Requirements Starting GISDK Starting the GISDK Debugger

About Add-Ins

An add-in is a program that you can add to TransCAD that accesses TransCAD databases and functions to carry out the capabilities that you require. You create add-ins by writing the macros or dialog boxes you want to use, compiling these macros or dialog boxes, and installing them as add-ins. Once installed, you or other TransCAD users can run the add-in by choosing the Tools-Add Ins command and then picking the add-in you want. Add-ins can be very simple, or very complex. The simplest add-ins are macros that run when you choose them, without any user interaction. More complicated add-ins display dialog boxes that let users choose the settings or options that they want to use when the macro is run. The most complex add-ins are custom toolboxes that provide users with access to tools, buttons, and other controls that you have programmed. These toolboxes look just like the toolboxes you are used to seeing in TransCAD.

About Custom Applications

GISDK lets you create a mapping application program with your own user interface. You design the menus, toolbars, toolboxes, and dialog boxes, and you program the application to respond to user actions in any way you want. Your user interface can be added to the standard interface, typically as one or more additional menus, or can be a completely customized user interface. You create a custom application by writing the menus, toolbars, macros, and dialog boxes you need, compiling all of these different types of resources, and installing the custom interface as an add-in. Once installed, you can create your own program icon in any Windows program group to run the custom

application, or start the program in the usual way and then choose between the standard interface and your custom interface. Like add-ins, custom applications can be very simple (with only a single window and a limited set of menu items) or very complex. The standard interface of TransCAD itself is an example of a very complex custom application, written entirely using GISDK. The on-line help provides descriptions of how to call many of the standard interface macros, for opening files, setting styles, and other tasks.

About Batch Mode

Standard TransCAD offers Batch Mode as a way of recording and running planning procedures and routing and logistics procedures. For the planning procedures, Batch Mode provides facilities for building integrated model applications, creating custom user interfaces for planning models, and running models without user intervention (i.e., in Batch Mode). In addition to running models interactively, TransCAD provides great flexibility in building complete model applications, with attractive user interfaces that are easy to learn and use. There are several advantages to creating a GISDK program that runs some or all of your various planning procedures: • • •

The model will be faster since it does not require the additional time necessary for interactive use Error may be reduced Model and file management will be easier

One easy way to create the GISDK script necessary to run planning procedures is to use the Batch Mode tools. The tools are like a background recorder that allows you to "capture" all the input and output files, parameters and settings associated with a planning procedure. You first turn on the Batch Recorder and make it active. Then, you set up and run planning procedures like you normally would interactively. In this mode, in addition to running the procedure, you would create GISDK script. Another way is to modify one of the scripts that Caliper provides. Then, if you compile and run the script file, the same procedure would be run in Batch Mode. The GISDK script that is created using the Batch Mode tools is fully compatible with the full functionality of GISDK. Thus, you can add all of the GISDK capabilities to your batch-created GISDK script to produce an unlimited amount of applications. Batch Mode for planning procedures is described in the Travel Demand Modeling with TransCAD User's Guide and in the on-line Help for Planning. There you will also find information on building custom applications that utilize travel demand model procedures.

For the routing and logistics, Batch Mode can be used with procedures such as creating a routing matrix, solving the routing problem, and displaying vehicle routes. Batch Mode for routing and logisitics procedures is described in the Routing and Logistics with TransCAD User’s Guide and in the on-line Help for Routing.

About Accessing TransCAD as an Automation Server

GISDK provides an environment for accessing GISDK functions in a variety of ways. Using Caliper Script, you can write add-ins or custom applications composed of GISDK macros that call GISDK functions. These add-ins or custom applications are run from within TransCAD. GISDK also allows you to call GISDK functions and macros from another application, written in another programming language such as Visual Basic. You do this using OLE Automation. TransCAD is accessed as an Automation Server, which can provide map, data, and transportation analysis services. You write your application in a programming language that can make OLE Automation calls, and when you need map services you call the TransCAD object to supply those services. You can call GISDK functions directly, or you can call GISDK macros, compiled in a UI Database, that call GISDK functions. Calling GISDK functions directly is good for simple operations, while using GISDK macros is helpful when doing more complex or frequently needed operations. The OLE Automation model is designed so that clients have access to the full range of Caliper Script functions through the main TransCAD object. This object includes the methods for calling GISDK functions and macros with the necessary arguments. The subsidiary MacroVal object provides a wrapper for the custom compound types that are used by many of the GISDK functions. For more information, see Accessing TransCAD as an Automation Server.

GISDK System Requirements

To use GISDK, you must have TransCAD installed on your computer. The hardware requirements for GISDK are minimal; if you can run TransCAD, you can run GISDK. GISDK does not include its own editor. Instead, you can create, edit, and display GISDK source code using any text editor you like. We strongly recommend that you use an editor that is Windows-based, designed for

programmers, and supports editing of multiple files at one time. A good example is Codewright ® (by Starbase Corp., www.starbase.com). A Windows-based editor allows you to switch back and forth between programs as often as you like. This makes you more efficient in developing and testing GISDK programs.

Starting GISDK

GISDK is installed when you install TransCAD. From within TransCAD, you can use GISDK through a toolbox to test and debug add-ins and custom applications written in Caliper Script. When you are accessing TransCAD as an Automation Server, you create a TransCAD Automation Server object through which you can call GISDK functions and macros.

 To Start GISDK 1. If you have not already done so, start your text editor. 2. If you have not already done so, start TransCAD.

3. Choose Tools-Add Ins to display the Add-Ins dialog box. 4. Highlight GIS Developer’s Kit in the Add-Ins list. 5. Click OK. TransCAD displays the GISDK Toolbox. You are now ready to use GISDK. For more information on the GISDK Toolbox , see Compiling with the GISDK Toolbox.

Starting the GISDK Debugger

GISDK includes a debugger that helps you find and fix runtime problems in GISDK macros. The GISDK Debugger runs along side TransCAD, in a separate window. You start the GISDK Debugger from the GISDK Toolbox.

To Start the GISDK Debugger

1. Choose Tools-Add-Ins, highlight GIS Developer’s Kit, and click OK to display the GISDK Toolbox. 2. Click to start the GISDK Debugger, and click GISDK Debugger on the Windows Taskbar to display

the GISDK Debugger program window.

For more information on the GISDK Debugger, see Working with the GISDK Debugger.

Quick Start

This section is designed to give you quick, practical experience using GISDK to develop add-ins and custom applications for TransCAD. If you are an experienced developer, and have used or built applications in other programming and/or macro languages, this section will give you a good overview of the Caliper Script language, and tell you almost everything you need to know about the mechanics of using GISDK. If you are not an experienced developer, this section will provide you with some hands-on experience with the tools that are provided in the platform, and a good overview of the process of developing, compiling, and running GISDK applications. You may want to spend some extra time studying the code samples to make sure you understand them, and you may even want to look up some of the functions that are used here in the on-line help. In a series of lessons, this quick start will build a simple but useful add-in that you can adapt to your own needs. You will use sample programs whose source code is included in the GISDK\SAMPLES folder within your TransCAD program folder. First, you will load and run these programs as is; later on, you can modify them and experiment on your own. When developing any software application, it is best to do some planning and designing before starting to do the coding. At a minimum you should specify the basic things you want your user to be able to do, and sketch on paper the way the user interface should look. The more detail you include in your "spec" the easier it will be to write the program. It will have fewer errors and require less revision. So, let's write the spec first, and then begin programming. You want to create an add-in to make it easy to find a best route over a network from a point to one of the nearby points. It will allow the user to click on the map, see a list of point locations within a specified search distance, choose one of them, and zoom the map to show the route to the chosen point from the original clicked point. Your detailed specification looks like this: 1. Assume that a map is already open and that it contains a layer of point locations and a layer with lines. You will use the populated places layer called Places and the line layer called Highways in the map LESSONS.MAP in the GISDK\SAMPLES folder. 2. The user chooses a command from a new item on the menu bar that opens a Get Best Route toolbox. The toolbox contains a Click on Map tool and an edit box for typing a search distance, and

will look like this: 3. The user sets an appropriate search distance, chooses the Click on Map tool , and clicks somewhere on the map. 4. If no points are within the search distance then display a message and return, otherwise display a dialog box with a scroll list containing the points within the search distance, plus OK and Cancel buttons. Show the network distance, the crow flight distance, city, and state in the scroll list, with the cities ordered by crow flight distance. The dialog box will look like this: 5. If the user clicks Cancel then close the dialog box. Once the user has chosen a place enable the OK button. When the user clicks OK zoom the map to include the clicked point and the chosen place, display the route, then close the dialog box. 6. Set up the add-in as a custom application so that, when the user runs TransCAD from a new program icon on the desktop, the add-in is automatically run and its menu is added to the menu bar.

With your spec in hand, you are ready to set up the work environment and get started.

 To Prepare for Writing an Add-In

1. If you haven’t already done so, start TransCAD and start your text editor. 2. Make TransCAD the current application. 3. If you have not already done so, start GISDK by choosing Tools-Add Ins, highlighting GIS Developer’s Kit, and clicking OK. 4. Choose Help-GISDK Help to open the GISDK help file so that you can look up the full documentation of the GISDK functions you will be using. It is very helpful to keep the on-line help window open when reading and writing GISDK code. When you know the name of the function you are looking for, click the Index tab and type in the first few characters of the function, then click the appropriate item in the list. If you are trying to decide which function to use, click the Contents tab and choose the Outline of Topics page in the Welcome to GISDK Help! book.

For more information, see: Lesson 1: A Search Macro and a Test Program Lesson 2: Adding a Toolbox Lesson 3: Adding a Dialog Box Lesson 4: Calling the Toolbox from the Menus Lesson 5: Installing the Add-in Lesson 6: Running the Add-in from the Desktop

Lesson 1: A Search Macro and a Test Program

You will start with a macro that does the searching for the nearest points and calculating of the network distances. As your user interface develops, it can continue to call this same macro. By making it a separate macro, you are beginning to build a library of reusable macros. It is also easier to develop and maintain your program this way because you can test the search macro independently from the calling environment. Later your search macro will be called from a toolbox but, for now, you will see how to create a small test program by calling the search macro from a test macro. In the final add-in the test macro will be replaced with a command on a menu, but it can remain in the code in case you want to use it for maintenance or further development. These macros are stored in the file named LESSON1.RSC, which was installed in your GISDK\SAMPLES folder. The test macro name is the same as the file name ("lesson1") to make it easy to remember, but the macro name could be different. Read through the macros carefully to get an idea of what is going on: // This code is in lesson1.rsc. Macro 'lesson1' // Save the name of the current layer. curr_layer = GetLayer() // Set the line and node layer variables. line_layer = "Highway" node_layer = "CDF Node Layer" // Set the current layer to the line layer. SetLayer(line_layer) // Define the fields in the network as length and travel time. The first element in the array is the // field name you assign in the network. The second and third elements are the field names in // the highway database in the forward and reverse directions. linkflds = {{"Length", line_layer+".Length", line_layer+".Length"}, {"[Travel Time]", line_layer+".[Travel Time]", line_layer+".[Travel Time]"}} // Share the network as you will need it in other macros in this file. shared net // Create the network and assign a temporary name to the network. net = createNetwork(,GetTempFileName("*.net"),"Network",linkflds,,)

// Restore the current layer. SetLayer(curr_layer) // Set up the arguments for the nearest points macro; by setting these in variables it is easier // to read the actual RunMacro() call and know what is being passed. // Specify a layer name in the current map; layer names are case sensitive. layer = 'Place' // Use an arbitrary coordinate near Boston for now. Coordinates are given as integer millionths // of degrees, longitude first, then latitude. This coordinate is at -71.123456 degrees longitude // and 42.456321 degrees latitude. clicked_point = Coord(-71123456, 42456321) // Set a search distance of 5 miles, based on the current map units. current_units = GetMapUnits("Plural") distance = 5 * GetUnitSize("Miles", current_units) // Call the nearest points macro. result = RunMacro("get nearest points", layer, highway_layer, node_layer, clicked_point, distance) // Show the list of nearest points. ShowArray(result) endMacro // A macro to get the nearest points on the search layer and the highway distances // between the source and target points Macro "get nearest points" (search_layer, node_layer, subject_point, search_distance) // Each macro should have a description at the beginning: // Finds points within search_distance units of subject_point on search_layer and returns an array // containing a data array for each point, with network distance, crow flight distance, city and state; // the data arrays are in order by network distance. This macro is designed to work with the Place // and Highway layers in Lessons.map. // Store the current layer, then make the specified layer the working layer. curr_layer = GetLayer() SetLayer(search_layer) // Find the nearest points in the working layer and return, in array rhs, the record handles (the string

// form of the record ID) for the closest records. The last argument, an options array, can be null. rhs = LocateNearestRecords(subject_point, search_distance, null) // If no points were found then display message and return. if rhs = null then do ShowMessage('Sorry, no points were within your search distance.') // Reset the layer to the stored layer; this is very important when an // add-in is working with the standard interface SetLayer(curr_layer) return() end // Dimension an array to the length of the record handles (rhs) array. Dim data[rhs.length] // share the network variable shared net // Look through the record handles array. for i = 1 to rhs.length do // Use the record handle to set the current record position on the // current view (which in this case is the Place layer). SetRecord(, rhs[i]) // Get the point coordinate for the current record on the current layer, // converting the record handle to its numeric equivalent (an ID). target_point = GetPoint(rh2id(rhs[i])) // Get the distance between the clicked point and the current point. distance = GetDistance(subject_point, target_point) // Set the current layer to the node layer and get the node IDs of the nodes closest to the // subject_point and the target_point, converting the record handle to its numeric equivalent SetLayer(node_layer) rh1 = LocateNearestRecord(subject_point, search_distance) rh2 = LocateNearestRecord(target_point, search_distance) node1 = rh2id(rh1) node2 = rh2id(rh2) // Calculate the shortest path between the subject and target point using the first network // field (distance). Only do this if the two nodes are not the same, otherwise, network_distance = 0.

// Also, gather the list of link IDs and directions that form the best network path. if node1 node2 then do sp = ShortestPath(net, {node1, node2}, 1, ) network_distance = sp[1] links = sp[2] directions = sp[3] end else network_distance = 0 // Add data to the output array. To add data from a current record for a layer use a "field specification", // which is the layer name in a variable + "." + field name, e.g. layer.city, not Place.city. data[i]={network_distance, distance, search_layer.city, search_layer.state, target_point, links, directions} SetLayer(search_layer) end // end of record handles loop // Reset the layer and return the data array to the calling program SetLayer(curr_layer) return(data) EndMacro If you have done any programming before, the syntax of this language should look familiar. Macros are called like subroutines, with arguments. A For loop is used to loop through a list. Arrays can be dimensioned and referenced with subscripts. The macro calls several functions (LocateNearestRecords(), GetDistance(), etc.) that find records and compute distances.

 To Compile the Sample Add-In

1. Make your text editor the current application.

2. Using your text editor, open and examine the contents of the LESSON1.RSC file in the GISDK\SAMPLES folder. 3. Make TransCAD the current application. 4. Click in the GISDK Toolbox to display the Compile File dialog box. 5. From the GISDK\SAMPLES folder, choose the file named LESSON1.RSC and click Open. GISDK compiles the file. The compiler checks the syntax of the statements in the file. If there are any errors, they are displayed, and also written to a file of the same name, but with the extension .ERR. In this case, there are no errors.

 To Run the Sample Add-In

1. Choose File-Open or click on the toolbar, choose Map as the file type, browse to the GISDK\SAMPLES folder in your TransCAD program folder, choose LESSONS.MAP, and click Open to display a map of the Massachusetts, Connecticut and Rhode Island with the Place layer showing city and town points. 2. Click in the GISDK Toolbox to display the Test an Add-In dialog box. 3. Click Macro in the Type of Add-In radio list. 4. Type "lesson1" in the Name text box. 5. Click OK. TransCAD finds the places within 5 miles of the supplied point and displays a dialog box with an array containing the display data. The distances will be in the current map units. 6. Click OK.

TransCAD closes the dialog box. That’s all there is to it! You have compiled and tested your first GISDK program. You can leave the Lessons map open, because you will be using it again in a few minutes.

Lesson 2: Adding a Toolbox

Now, instead of having the test program supply a coordinate, you want to get it from the users when they click on the map. A toolbox is a dialog box that stays on the screen all the time. It can contain a "tool" that captures the user’s interaction with the map. The test program (now called macro "lesson2") calls the toolbox which will, in turn, call the "get nearest points" macro developed in Lesson 1. The source code for Lesson 2 is stored in the LESSON2.RSC file in the GISDK\SAMPLES folder. Below is the source code, excluding the "get nearest points" macro that remains unchanged. // This code is in lesson2.rsc. Macro "lesson2" // Save the name of the current layer. curr_layer = GetLayer() // Set the current layer to the line layer. line_layer = "Highway" SetLayer(line_layer) // Define the fields in the network as length and travel time. The first element in the array

// is the field name you assign in the network. The second and third elements are the field // names in the highway database in the forward and reverse directions. linkflds = {{"Length", line_layer+".Length", line_layer+".Length"}, {"[Travel Time]", line_layer+".[Travel Time]", line_layer+".[Travel Time]"}} // Share the network as you will need it in other macros in this file. shared net // Create the network and assign a temporary name to the network. net = createNetwork(,GetTempFileName("*.net"),"Network",linkflds,,) // Restore the current layer. SetLayer(curr_layer) // Call the toolbox. result=RunDbox("get best route toolbox")) endMacro // Create a toolbox, which is a type of dialog box (dbox). // The keyword "ToolBox" makes the dialog box display until closed by the user. // The keyword NoKeyboard moves the focus to the toolbox immediately when user clicks in it. Dbox "get best route toolbox" center,center Title: "Get Best Route" ToolBox NoKeyboard // A description of the dialog box: // Displays Click on Map tool and Edit Text item to input search distance. Defaults search distance to // 5 miles; when user clicks on the map, call the macro to find nearest places and then display the array. // This section is automatically run when the dbox is first opened. Init do // Set the point layer variable for use below; always put a layer name into a variable, so // that if you change the name you only have to change it in one place in your program. point_layer="Place" // set the highway and node layer variable for use below; highway_layer = "Highway" node_layer = "CDF Node Layer" // Initialize the search_distance to 5 miles, based on the current map units. // R2I() changes a real number to an integer. current_units = GetMapUnits("Plural")

search_distance = R2I(5 * GetUnitSize("Miles", current_units)) endItem // This is needed to allow the user to close the toolbox by clicking on the X in the upper-right // corner. This also clears any path annotations that were drawn previously. Close do if aid null then DropAnnotation(, aid) return() endItem // Create a tool that, when chosen, waits for the user to click on the map. You will use the find // icon from the standard TransCAD bitmap file (buttons.bmp), with bitmaps for not chosen, // chosen and disabled. Tool "click_tool" 0,1 Icons:"bmp\\buttons|33", "bmp\\buttons|67", "bmp\\buttons|101" help: "Click on Map" do // Wait for user to click on map. clicked_point = ClickCoord() // Run the nearest places macro from lesson 1. // A program line can be continued on to the next line at any point // except in the middle of a string. points_list = RunMacro("get nearest points", point_layer, highway_layer, node_layer, clicked_point, search_distance) // If the macro found points then display the data; if no points are found, the macro // has already displayed a message, so just drop through to end of item. if points_listnull then do // You will copy the data into a formatting array for use in a scroll list in lesson 3. // To demonstrate another way to create an array, you will build it by // concatenation rather than dimensioning it. // First set the formatting array to null. formatting_array = null // Now loop through the list of points and their data for i = 1 to points_list.length do // Concatenate the array with an array containing your data. // First, create arrays for the formatting of each field. // Net distance and Crow distance will be right justified, // 1 decimal, ending in columns 5 and 18. f_netdistance = {5, "R*0.0", points_list[i][1]}

f_distance = {18, "R*0.0", points_list[i][2]} // City will be left justified, starting in column 25. f_city = {25, "L", points_list[i][3]} // State will be left justified, starting in column 46. f_state = {46, "L", points_list[i][4]} // Second, put them together in an array. f_array = { f_netdistance, f_distance, f_city, f_state } // Third, concatenate the formatting array with that array. formatting_array = formatting_array + { f_array } end // For checking purposes look at the original array and the formatting array. To // show more than one variable with ShowArray(), combine them both into an array. ShowArray({"points_list=", points_list, "formatting_array=", formatting_array}) end endItem // Display the current integer value of search_distance and allow user to change it. // Place the title at column 6, .5 rows down, and 16 characters wide. Text "Search Distance" 6, .5, 16 // Place the integer edit box below the "Search Distance" title and make it 4 characters wide. Edit Integer 8, 2.0, 4 Variable: search_distance // Place the text for the current map units right after and on the same line as the integer edit box. Text after, same Variable: current_units EndDBox NOTE: This updated macro includes an intentional typo on line 29 (an extra close parenthesis in the RunDbox() command), to show you what happens when GISDK encounters a syntax error during compilation. Let’s go ahead and compile the new version.

 To Compile the Enhanced Version

1. From your text editor, open and examine the contents of the LESSON2.RSC file in the GISDK\SAMPLES folder. 2. From TransCAD, click in the GISDK Toolbox to display the Compile File dialog box.

3. From the GISDK\SAMPLES folder, choose the file named LESSON2.RSC and click Open. GISDK compiles the file. When the GISDK compiler encounters a syntax error, it creates an error file listing each error that was encountered. The error file has the same name as the resource file and an extension of .ERR, and is always placed in the same folder as the resource file itself. GISDK also displays the contents of the error file as shown below. (If you don’t see the error message, it is possible that someone else may already have run this tutorial and fixed the typo.)

For those of you who use a programmers’ editor, the error file is in the standard format that is created by most compilers, so you can hot-key through the error and resource files.

 To Correct the Resource Error

1. Switch back to the text editor. 2. Remove the extra close parenthesis in line 29. 3. Save the modified file. 4. Switch back to TransCAD. 5. Click in the GISDK Toolbox to display the Compile File dialog box.

6. Choose the LESSON2.RSC file and click Open. This time, GISDK compiles the file successfully. Note that GISDK compiles programs that are stored in files. This means that you must save your file using your text editor program before you can compile and run it with GISDK. Note also that you do not actually need to be running your text editor to compile or run a GISDK program. However, if you get into the habit of running GISDK and your text editor at the same time, you’ll find you can modify your files and compile them very efficiently.

 To Run the Enhanced Add-In

1. Click on the Lessons map to make it the active window. 2. Click in the GISDK Toolbox to display the Test an Add-In dialog box. 3. Click Macro in the Type of Add-In radio list. 4. Type "lesson2" in the Name text box. 5. Click OK. The add-in starts running and displays the "Get Best Route" toolbox in the center of the screen.

6. Click the Click on Map tool , then click on the map within 5 miles of a place. The add-in displays the arrays of data for the nearest points. 7. Change the search distance to 1 mile and click over a mile away from any places. The add-in displays the "no points" message. 8. Click the X in the upper right hand corner to close the toolbox.

You have proven that the toolbox is working. Again, leave the map open. You’ll be using it again in a few minutes.

Lesson 3: Adding a Dialog Box

Now you can add a dialog box ("get choice") to display the formatted list of network and crow flight distance, city, and state, and allow the user to pick one or to cancel. You will revise the "get best route toolbox" dialog box code to call the "get choice" dialog box and, if the user picks a place, create a new scope for the map to show the clicked point and the chosen place, and then redraw the map. The test macro (now "lesson3") and the "get nearest points" macro remain the same and are not shown below. All of the Lesson 3 source code is stored in the LESSON3.RSC file in the GISDK\SAMPLES folder. Here is the the "get choice" dialog box: // Create a dialog box to display the choices DBox "get choice" (points_list) Title: "Choose a Place" // Displays the points_list formatted array of data; requires the user to choose one and // click OK. Returns an array index for OK or null if Cancel is clicked. Init do // disable the OK button to start; enable it when a line in the scroll list is chosen. DisableItem("OK") endItem // Add some titles for the scroll list. Text "Net Distance" 1, 0 Text "Crow Distance" 13, 0 Text "City" 26.5, same Text "State" 47.5, same // Display the formatted array; the keyword "multiple" is not used, so only one choice // will be possible. The points_idx variable will contain the index (subscript) of the // selected array element. Scroll List 1, 1, 55, 15 List: points_list Variable: points_idx

Do // When user makes a choice, enable the OK button. EnableItem("OK") endItem // Add an OK button. Default keyword allows the user to press Enter. Button "OK" 35, 17, 9, 1 Default Do // Return the index (subscript) of the chosen element return(points_idx) endItem // Add a Cancel button. Cancel keyword allows the user to press Esc. Button "Cancel" 46, same, 9, 1 Cancel Do // Return null if user cancels return() endItem EndDBox Most of the code for the "get best route toolbox" dialog box is the same as in Lesson 2. Only the new call to the dialog box and the code that follows are shown below: // Call the dialog box to display the list and return the choice. choice = RunDbox("get choice", formatting_array) // If the user didn't press Cancel then create a scope and zoom if choicenull then do // Get the conversion between miles and the current map units mi_cmu = GetUnitSize("Miles", GetMapUnits("Plural")) // Compute .1 and 5 miles in current units tenth = .1 * mi_cmu five = 5 * mi_cmu // Create a tiny scope for the clicked point. A scope is a center point, and a width // and height in the current map units. The last argument to Scope() must be zero. clicked_pt_scp = Scope(clicked_point, tenth, tenth, 0) // Create a tiny scope for chosen point; the coordinate is in array element 5. chosen_pt_scp = Scope(points_list[choice][5], tenth, tenth, 0)

// Now combine the two scopes new_scope = ScopeUnion(clicked_pt_scp, chosen_pt_scp) // If the two points were less than five miles apart then set the scope width and // height to 5 miles; otherwise expand the scope by 10% to add a margin. if new_scope.height< five then new_scope = Scope(new_scope.center, five, five, 0) else new_scope = Scope(new_scope.center, new_scope.width*1.1, new_scope.height*1.1, 0) // Now set the new scope. SetMapScope(, new_scope) // Delete the old path annotation if it existed previously. if aid null then DropAnnotation(, aid) // If path exists, draw the shortest path on the map by: // 1. Getting the list of coordinates of the path given it's link IDs and directions. // 2. Adding a coordinate to beginning and end depicting the origin and destination places. // 3. Drawing an annotation in red with a 3.5 point thickness of the path. // 4. Resetting the scope to the extents of the path. if points_list[choice][1] > 0 then do curr_layer = GetLayer() SetLayer(highway_layer) pthcoords = PathCoords(highway_layer + ".ID", points_list[choice][6], points_list[choice][7]) SetLayer(curr_layer) pthcoords = {clicked_point} + pthcoords + {points_list[choice][5]} aid = AddAnnotation(, "Polyline",{ {"Points", pthcoords}, {"Line color", ColorRGB(65535, 1, 1)}, {"Line width", 3.5} }) // If the path ends are less than five miles apart then set the scope width and // height to 5 miles; otherwise expand the scope by 10% to add a margin. new_scope = GetArrayScope(pthcoords) if new_scope.height< five then new_scope = Scope(new_scope.center, five, five, 0) else new_scope = Scope(new_scope.center,

new_scope.width*1.1, new_scope.height*1.1, 0) SetMapScope(, new_scope) end RedrawMap() end

 To Compile and Run Lesson 3

1. From your text editor, open and examine the contents of the LESSON3.RSC file in the GISDK\SAMPLES folder. 2. From TransCAD, click in the GISDK Toolbox to display the Compile File dialog box. 3. Choose the file named LESSON3.RSC in the GISDK\SAMPLES folder, and click Open. GISDK compiles the file. 4. Click on the Lessons map to make it the active window. 5. Click in the GISDK Toolbox to display the Test an Add-In dialog box. 6. Click Macro in the Type of Add-In radio list. 7. Type "lesson3" in the Name text box. 8. Click OK. The add-in starts running and displays the "Get Best Route" toolbox in the center of the screen. 9. Click the Click on Map tool , then click on the map within 5 miles of a place. Now the add-in displays the dialog box with the scroll list of choices. 10. Choose a place and click OK. The add-in redraws the map zoomed in to show your clicked point and your chosen city. 11. Click the X in the upper right hand corner to close the toolbox. You did not have to display the scroll list in a separate dialog box. You could easily have added it to the toolbox, but then it would have taken up a lot of space in a dialog box that stays on the screen all the time.

Lesson 4: Calling the Toolbox from the Menus

Now it is time to stop calling the toolbox from a test macro, and instead add a menu to the TransCAD menu bar to call it. You will also see how your source code can be kept in separate files, but be compiled into a single program. Your code for adding the new menu will be kept in LESSSON4.RSC in the GISDK\SAMPLES folder. An additional file, LESSSON4.LST, contains a list of the source code files to be compiled. It includes a reference to the

LESSSON3.RSC

file, which we will use unchanged, and also a reference to your new code, LESSSON4.RSC, which is shown below: // This code is in lesson4.rsc. // Add a "Lesson" menu with a "Get Best Route" item to the main menu Macro "lesson4" // This macro adds the "Lesson" menu before the "window" menu // First, make sure the "Lesson" menu is not already there. // This error handler prevents an error message if the menu isn't there. on NotFound goto next // Now remove the menu,... RemoveMenuItem("GISDK Lesson Menu") // Reset the error handling,... next: on NotFound default // And add the menu AddMenuItem("GISDK Lesson Menu", "Before", "Window") endMacro Menu "Lesson Menu System" // This is the top-level title to be added to the main menu system MenuItem "GISDK Lesson Menu" text: "Lesson" key: alt_l menu "Lesson Dropdown Menu" endMenu Menu "Lesson Dropdown Menu" // This is the body of the drop-down menu to be added MenuItem "Get Best Route" text: "Get Best Route" key: alt_Z do // Open the toolbox RunMacro("lesson3") endItem endMenu

 To Compile and Run Lesson 4

1.

From your text editor, open and examine the contents of the LESSON4.RSC and LESSON4.LST files in the GISDK\SAMPLES folder. 2. From TransCAD, click in the GISDK Toolbox to display the Compile File dialog box. 3. Choose the file named LESSON4.LST in the GISDK\SAMPLES folder, and click Open. GISDK compiles both the files listed into a single compiled program. 4. Click on the Lessons map to make it the active window. 5. Click in the GISDK Toolbox to display the Test an Add-In dialog box. 6. Type "lesson4" in the Name text box. 7. Click OK. The Lesson menu is added to the menu bar, and it has one command, Get Best Route. 8. Choose Lesson-Get Best Route. The add-in displays the toolbox created in Lesson 2. Now you can use the toolbox as before. Your add-in is complete!

Lesson 5: Installing the Add-in

GISDK stores compiled resource files in a special database called a user interface database. This database is often referred to as the UI Database, and consists of a collection of files on disk with the same name and extensions of .1, .2, .3, .4, .5, .6, and .DBD. When you compile and test add-ins as we have been doing so far, GISDK stores the compiled macros in a UI Database named TEST_UI, which is stored in the GISDK folder in the TransCAD program folder. To distribute a GISDK application to TransCAD users, you must compile your resource files into a separate, stand-alone UI Database with a different name. This UI Database can then be delivered to other users of TransCAD. Then, the user needs to install the add-in or custom application by using the Setup option in the Add-Ins dialog box. NOTE: Products developed with one version of GISDK (such as TransCAD) cannot be delivered to users of a different product (such as Maptitude). Let’s work through a quick example.

 To Create the UI Database 1. Click in the GISDK Toolbox to display the Compile to UI Database dialog box.

2. Choose the file named LESSON4.LST in the GISDK\SAMPLES folder, and click Open to display the Save As dialog box. 3. Choose the folder that contains the TransCAD program files, type "lesson4" as the UI Database name, and click Save. GISDK compiles the file into the lesson4 UI Database. Note that the only difference between the and buttons is that the latter stores the compiled resources in your own UI Database. Now, let’s configure TransCAD so that it can run the add-in from the Add-Ins dialog box.

 To Install the Add-In

1. Choose Tools-Add Ins to display the Add-Ins dialog box. 2. Click Setup to display the Setup Add-Ins dialog box. 3. Click Add to create a new add-in. The default description will be "Untitled Add-in" and the default name for the macro to call will be "Untitled." 4. Click Macro in the radio list. 5. Type "Get Best Route" in the Description text box. 6. Type "lesson4" in the Name text box. 7. Type "lesson4" in the UI Database text box. 8. Click OK to install the add-in and return to the Add-Ins dialog box. 9. Click Cancel. TransCAD closes the Add-Ins dialog box.

 To Run the Installed Add-In

1. Choose Tools-Add Ins to display the Add-Ins dialog box. 2. Highlight Get Best Route in the scroll list. 3. Click OK. TransCAD runs your add-in, just as you would expect.

Lesson 6: Running the Add-in from the Desktop A handy way to start TransCAD with a custom application is to create a custom program icon. There are two types of custom applications, ones that have a completely customized user interface and others that add to the

standard interface. Since you have created an add-in that adds itself to the standard interface, you can create a custom program icon for it, so the user does not have to do anything special to start the add-in.

 To Create a Custom Program Icon

1. Choose File-Exit to exit TransCAD. 2. Close your text editor. 3. Copy the TransCAD program icon on your Windows desktop by holding the Ctrl key and dragging the icon to a new spot, or by copying and pasting a copy of the icon. 4. Right-click on the new program icon and choose Properties to display the Properties dialog box. 5. Click the General tab and type "TransCAD with Get Best Route" in the edit box. 6. Click the Shortcut tab and add the following to the end of the text in the Target edit box: -q -a lesson4 -ai lesson4 -n "TransCAD with Get Best Route"

The -q option turns off the Quick Start dialog box, -a gives the name of your alternate UI Database, -ai gives the name of the startup macro, and -n gives the program window a new name. 7. Click OK to close the Properties dialog box. 8. Double-click the new program icon.

TransCAD starts with your add-in as a custom application. If Lesson 4 had created a completely customized user interface, you could have used the -u and -i options to start TransCAD without the standard interface, but with your custom application. For more information on custom applications, see Installing and Running Custom Applications.