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 nformation !ystem Developer"s #it $G !D#% provides you with a tool &it that you can use to get outside the box and customi'e TransCAD in any way you desire. G !D#$tm% is a collection of software tools and documentation that come with TransCAD and ma&e it possible to automate repetitive TransCAD tas&s, create user designed add(ins, integrate other programs, or build custom applications. G !D# also ma&es it possible to call the TransCAD functionality from other software applications. The primary component of the G !D# is a programming language called Caliper !cript$tm%. This is an easy( to(learn, BA! C(li&e programming language that provides a way to interact with the TransCAD program and data. Caliper !cript is a programming language that is powerful, but easy to use. t is more flexible and powerful that the languages provided with other transportation software. Also code written in other languages such as C or )*+T+A, can be intermixed with G !D# programs written in Caliper !cript, facilitating compatibility with existing software. The primary use of the Caliper !cript is to interact with TransCAD. There are over one thousand G !D# functions in TransCAD, all of which can be called from Caliper !cript. These functions give users a wide variety of tools that range from managing maps and display characteristics to creating, accessing, updating and analy'ing data and data structures, including matrices and networ&s. n addition, the G !D# functions can be called using -indows Automation, since TransCAD can act as both an Automation !erver and Client. TransCAD for the -eb 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 !cript also provides the capability to program complete, custom -indows interfaces for TransCAD applications. Caliper !cript, in turn, is supported by three components. a compiler, a debugger and a toolbox for interacting with the compiler and debugger. The G !D# Compiler ta&es the Caliper !cript code and creates a / 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 G !D# Debugger runs the Caliper !cript code in testing mode to ma&e sure that there are no errors, such as errors in logic or variable handling. f the code does not behave as expected, the debugger allows the user to set brea&points or to step through the code one line at a time, to ma&e sure that the code is executing as expected. The G !D# Toolbox not only has buttons to run the compiler and the debugger but also has tools to ma&e interacting with the program faster and easier. The G !D# for !tandard TransCAD has two additional components. The first is Batch 0ode, which is a

simpler way of automating transportation analysis. The second is the ability to access TransCAD 0atrix D11s directly from C and )*+T+A,. The 0atrix D11s are provided for 2isual C and Compa3 2isual )*+T+A,. )or running travel demand applications and for some routing and logistics procedures, TransCAD has a Batch 0ode capability that ma&es 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 4ou About the Boo& and this *n(1ine 5elp *ther G !D# +esources 1icensing of G !D# Add( ns and Applications G !D# 2ersions f 4ou ,eed 0ore 5elp

About You

-e made several assumptions about you when we put the G !D# 6rogrammer"s Guide and *n(1ine 5elp together.

4ou are a fre3uent user of TransCAD and are familiar with the terms and concepts covered in the /ser "s Guide. f you wish to use Batch 0ode, which is part of !tandard TransCAD, you should also be familiar with the terms and concepts covered in the Travel Demand 0odeling /ser"s Guide. 4ou have some basic &nowledge and experience in programming, either in Basic, 2isual Basic, C, or some other language. 4ou want to automate or customi'e TransCAD to help you accomplish your wor& more efficiently, or to provide assistance to other users. 4ou want to get started 3uic&ly, without wee&s of training or hard wor&.

About the Book and this On-Line Help

The G !D# 6rogrammer"s Guide gives you the essential bac&ground information that you need to start using G !D#. The full G !D# documentation is provided electronically as part of this *n(1ine 5elp system. This comprehensive *n(1ine 5elp system gives you detailed bac&ground, instructions, a complete listing of the

G !D# functions, and samples in a clear and concise layout. Together, the G !D# 6rogrammer"s Guide and this *n(1ine 5elp system describe everything you need to &now to start using G !D#. n the G !D# 6rogrammer"s Guide. Chapter 7, Introduction, provides an introduction to G !D# and an overview of its capabilities, along with instructions for starting the G !D# Toolbox and the G !D# Debugger. Chapter 8, Quick Start, provides a concise overview of how you use G !D# to build applications to automate repetative tas&s. f you are an experienced developer, this chapter provides most of the information you need to get started. f 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 wor&s. Chapter 9, GISDK Mechanics, describes the tools that come with G !D#, including the G !D# Toolbox and the G !D# Debugger, and how you use these tools to write and develop add(ins and custom applications, and access TransCAD as an application server. n addition, this *n(1ine 5elp system contains comprehensive information on calling G !D# functions, on creating G !D# macros, and on other G !D# applications. This *n(1ine 5elp system includes a complete listing of the G !D# functions. The additional sections in this *n(1ine 5elp for G !D# include. Common Calling Conventions. standards that are used for arguments in G !D# functions /sing G !D# )unctions. overviews of G !D# functions by topic, including windows, maps, layers, editors, tables, and views /sing 6ro:ections and Coordinate !ystems. details on setting a map;s pro:ection or coordinate system, including units, ellipsoids, datums, and transformations 1isting of G !D# )unctions. individual descriptions of the G !D# functions, including syntax, return values, and examples G !D# 0echanics. the compilation tools that come with G !D# 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 G !D# macros, and how to access TransCAD as an Automation !erver 1anguage <lements. the syntax, organi'ation, and elements of the Caliper !cript language +esources. introduction to and explanation of the format and structure of the resource files that contain your add(in or custom application !tandard nterface 0acros. a listing of macros in the standard interface useful in custom applications for closing files, setting styles, and other tas&s, plus geocoding and other macros

Batch 0ode, which comes with !tandard TransCAD, is an easy way to create and run planning models as a set of Caliper !cript macros, as well as to run some of the routing and logistics procedures. Batch 0ode for transportation planning is described in the Travel Demand 0odeling with TransCAD /ser;s Guide and in the on(line 5elp for 6lanning. Batch 0ode for routing and logisitics procedures is described in the +outing and 1ogistics with TransCAD /ser;s Guide and in the on(line 5elp for +outing. f you have purchased TransCAD for the -eb, the TransCAD for the -eb /ser;s Guide and the on(line 5elp for TransCAD for the -eb explain how to use G !D# functions and G !D# macros in web mapping

applications.

Other GISDK Resources

The G !D# 6rogrammer"s Guide and *n(1ine 5elp give some examples of how you can use G !D#. 0ore examples are available on the Caliper Corporation web site $ ---.CA1 6<+.C*0=ADD ,!.5T0%. 4ou are free to adopt and adapt these Caliper !cript and Automation !erver examples to meet your own needs. 4ou are also encouraged to contribute to the growing list of examples, so that others can benefit.

Licensing o GISDK Add-Ins and Applications

G !D# enables you to create add(ins, custom applications, or Automation !ervers. G !D# also ma&es it possible for third parties to create and distribute add(ins and custom applications. -e expect that many G !D# users will fall into one of three classes. ndividual users who want to automate or simplify tas&s they routinely perform with TransCAD nternal systems staff who develop add(ins and applications to be used by others within their organi'ation Developers, resellers, and consultants who use TransCAD along with G !D# to provide custom end( user 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 re3uired G ! functionality for your application. +un(time licensing involves the payment of a processing fee plus technology license fees that are negotiated on a case(by(case basis. -hen you develop an add(in or custom application using G !D#, the product is a user interface database $/ Database% containing the add(in or custom application. 6rovided that you comply with the TransCAD license agreement, you may distribute, sell, or give away completed / Databases containing your add(ins or custom applications. 4ou may also distribute, sell, or give away Caliper !cript source code that you create for your G !D# programs. At the same time, the TransCAD license agreement imposes certain restrictions upon you. )or example,

!ou are not per"itted to cop! or distribute#

The TransCAD program file $TCW.EXE% The supporting dynamic lin& libraries $D11s% Geographic and tabular data files that are provided with Caliper G ! products Any files that are part of the TransCAD product pac&age

The license agreement for TransCAD for the -eb gives you rights to create, test, and publish web mapping applications that access TransCAD as an Automation !erver. *ther licensing arrangements $such as runtime licenses% are available for other forms of access to TransCAD as an Automation !erver. f you have any 3uestions about the above licensing information, please discuss them with us.

GISDK $ersions

There are different versions of G !D# for each Caliper Corporation G ! pac&age. All of the versions of G !D# share a common language structure and syntax, and many common functions. 5owever, products developed with one version of G !D# $such as TransCAD% cannot be delivered to users of a different product $such as 0aptitude%. The TransCAD version of G !D# includes a substantial number of additional functions that support the map display and transportation analysis capabilities of TransCAD, including functions for creating and maintaining networ&s, route systems, surfaces, matrices, and transit schedules. f you have !tandard TransCAD you also have access to Batch 0ode and the 0atrix D11s.

I You %eed &ore Help

f you find yourself stuc& or in need of additional assistance, please contact our Technical !upport department. NOTE: You must be a registered user to receive Caliper Technical upport ervices! "egister #our soft$are b# fa%ing or mailing in the registration card that came $ith #our soft$are pac&age, or b# filling out the Caliper Corporation 'nternet registration form at HTTP://WWW.CALIPER.COM/REGISTER.HTM! Caliper Corporation soft$are support services are sub(ect

to support fees and terms in place at the time the services are used! 4ou can get technical support from Caliper Corporation in four ways.
1. FAX your requests for he ! to "#1$% &'$(&11).

8. Chec& the technical support notes at Caliper Corporation"s -orld -ide -eb site $WWW.CALIPER.COM%. ). Se*+ e(,-. /.- the I*ter*et to su!!ort01- .!er.1o,. 2. C- C- .!er Te1h*.1- Su!!ort -t "#1$% &'$(3#1$. 4ou can reach TransCAD Technical !upport by telephone between >.9? a.m. and @.9? p.m., <astern Time, 0onday through )riday. -hen you call, please be at your computer, have your documentation available, and be prepared to provide the following information.
4 4 The !ro+u1t re5.str-t.o* *u,6er 7our *-,e -*+ or5-*.8-t.o*

A 4

The version of the product you are using B choose Help-About to chec& your version number The e9-1t :or+.*5 of -*y ,ess-5es th-t -!!e-r o* your s1ree*

Introduction

As an experienced TransCAD user, you may have thought about how nice it would be to automate some tas& that you perform on a regular basis, so you could accomplish it by clic&ing a single button or choosing a single menu item. 6erhaps you have thought about creating a custom application, one that has a subset of the capabilities of TransCAD, but organi'ed and structured differently to appeal to a particular audience. 4ou may also have thought about calling TransCAD from another programming environment, such as 2isual Basic, to provide transportation analysis or mapping services to an application, such as finding a route or displaying a map around a location. f you have had these thoughts, the G ! Developer"s #it is for you. G !D# lets you customi'e and extend the capabilities of TransCAD in almost any way you li&e. There are three types of things you can do with G !D#. 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 customi'ed program operation Access TransCAD as an *utomation erver to add maps or transportation analysis functions to your own programs

n addition, the planning and the routing and logistics procedures in standard TransCAD offer Batch 0ode 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( ns About Custom Applications About Batch 0ode About Accessing TransCAD as an Automation !erver G !D# !ystem +e3uirements !tarting G !D# !tarting the G !D# 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 re3uire. 4ou 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. *nce installed, you or other TransCAD users can run the add(in by choosing the Tools-Add Ins command and then pic&ing 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. 0ore 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 loo& :ust li&e the toolboxes you are used to seeing in TransCAD.

About 'usto" Applications

G !D# lets you create a mapping application program with your own user interface. 4ou design the menus, toolbars, toolboxes, and dialog boxes, and you program the application to respond to user actions in any way you want. 4our user interface can be added to the standard interface, typically as one or more additional menus, or can be a completely customi'ed user interface. 4ou 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. *nce installed, you can create your own program icon in any -indows 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. 1i&e 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 G !D#. The on(line help provides descriptions of how to call many of the standard interface macros, for opening files, setting styles, and other tas&s.

About Batch &ode

!tandard TransCAD offers Batch 0ode as a way of recording and running planning procedures and routing and logistics procedures. )or the planning procedures, Batch 0ode provides facilities for building integrated model applications, creating custom user interfaces for planning models, and running models without user intervention $i.e., in Batch 0ode%. n 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 G !D# program that runs some or all of your various planning procedures.

The model will be faster since it does not re3uire the additional time necessary for interactive use <rror may be reduced 0odel and file management will be easier

*ne easy way to create the G !D# script necessary to run planning procedures is to use the Batch 0ode tools. The tools are li&e a bac&ground recorder that allows you to CcaptureC all the input and output files, parameters and settings associated with a planning procedure. 4ou first turn on the Batch +ecorder and ma&e it active. Then, you set up and run planning procedures li&e you normally would interactively. n this mode, in addition to running the procedure, you would create G !D# 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 0ode. The G !D# script that is created using the Batch 0ode tools is fully compatible with the full functionality of G !D#. Thus, you can add all of the G !D# capabilities to your batch(created G !D# script to produce an unlimited amount of applications. Batch 0ode for planning procedures is described in the Travel Demand 0odeling with TransCAD /ser;s Guide and in the on(line 5elp for 6lanning. There you will also find information on building custom applications that utili'e travel demand model procedures.

)or the routing and logistics, Batch 0ode can be used with procedures such as creating a routing matrix, solving the routing problem, and displaying vehicle routes. Batch 0ode for routing and logisitics procedures is described in the Routing and Logistics with TransCAD Users Guide and in the on(line 5elp for +outing.

About Accessing (rans'AD as an Auto"ation Ser)er

G !D# provides an environment for accessing G !D# functions in a variety of ways. /sing Caliper !cript, you can write add(ins or custom applications composed of G !D# macros that call G !D# functions. These add(ins or custom applications are run from within TransCAD. G !D# also allows you to call G !D# functions and macros from another application, written in another programming language such as 2isual Basic. 4ou do this using *1< Automation. TransCAD is accessed as an Automation !erver, which can provide map, data, and transportation analysis services. 4ou write your application in a programming language that can ma&e *1< Automation calls, and when you need map services you call the TransCAD ob:ect to supply those services. 4ou can call G !D# functions directly, or you can call G !D# macros, compiled in a / Database, that call G !D# functions. Calling G !D# functions directly is good for simple operations, while using G !D# macros is helpful when doing more complex or fre3uently needed operations. The *1< Automation model is designed so that clients have access to the full range of Caliper !cript functions through the main TransCAD ob:ect. This ob:ect includes the methods for calling G !D# functions and macros with the necessary arguments. The subsidiary 0acro2al ob:ect provides a wrapper for the custom compound types that are used by many of the G !D# functions. )or more information, see Accessing TransCAD as an Automation !erver.

GISDK S!ste" Re*uire"ents

To use G !D#, you must have TransCAD installed on your computer. The hardware re3uirements for G !D# are minimalD if you can run TransCAD, you can run G !D#. G !D# does not include its own editor. nstead, you can create, edit, and display G !D# source code using any text editor you li&e. -e strongly recommend that you use an editor that is -indows(based, designed for

programmers, and supports editing of multiple files at one time. A good example is Codewright $by !tarbase Corp., www.starbase.com%. A -indows(based editor allows you to switch bac& and forth between programs as often as you li&e. This ma&es you more efficient in developing and testing G !D# programs.

Starting GISDK

G !D# is installed when you install TransCAD. )rom within TransCAD, you can use G !D# through a toolbox to test and debug add(ins and custom applications written in Caliper !cript. -hen you are accessing TransCAD as an Automation !erver, you create a TransCAD Automation !erver ob:ect through which you can call G !D# functions and macros.

(o Start GISDK
1. If you h-/e *ot - re-+y +o*e so; st-rt your te9t e+.tor. '. If you h-/e *ot - re-+y +o*e so; st-rt Tr-*sCA<.

9. Choose Tools-Add Ins to display the Add( ns dialog box. E. 5ighlight G ! Developer"s #it in the Add( ns list. &. C .1= O>. TransCAD displays the G !D# Toolbox. 4ou are now ready to use G !D#. )or more information on the G !D# Toolbox , see Compiling with the G !D# Toolbox.

Starting the GISDK Debugger

G !D# includes a debugger that helps you find and fix runtime problems in G !D# macros. The G !D# Debugger runs along side TransCAD, in a separate window. 4ou start the G !D# Debugger from the G !D# Toolbox.

(o Start the GISDK Debugger

7. Choose Tools-Add-Ins, highlight G ! Developer"s #it, and clic& *# to display the G !D# Toolbox. '. C .1= to st-rt the GIS<> <e6u55er; -*+ 1 .1= GIS<> <e6u55er o* the W.*+o:s T-s=6-r to +.s! -y

the GIS<> <e6u55er !ro5r-, :.*+o:.

)or more information on the G !D# Debugger, see -or&ing with the G !D# Debugger.

+uick Start

This section is designed to give you 3uic&, practical experience using G !D# to develop add(ins and custom applications for TransCAD. f 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 !cript language, and tell you almost everything you need to &now about the mechanics of using G !D#. f 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 G !D# applications. 4ou may want to spend some extra time studying the code samples to ma&e sure you understand them, and you may even want to loo& up some of the functions that are used here in the on(line help. n a series of lessons, this 3uic& start will build a simple but useful add(in that you can adapt to your own needs. 4ou will use sample programs whose source code is included in the G !D#F!A061<! folder within your TransCAD program folder. )irst, you will load and run these programs as isD later on, you can modify them and experiment on your own. -hen 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 s&etch on paper the way the user interface should loo&. The more detail you include in your CspecC the easier it will be to write the program. t will have fewer errors and re3uire less revision. !o, let;s write the spec first, and then begin programming. 4ou want to create an add(in to ma&e it easy to find a best route over a networ& from a point to one of the nearby points. t will allow the user to clic& on the map, see a list of point locations within a specified search distance, choose one of them, and 'oom the map to show the route to the chosen point from the original clic&ed point. 4our detailed specification loo&s li&e this. 7. Assume that a map is already open and that it contains a layer of point locations and a layer with lines. 4ou will use the populated places layer called 6laces and the line layer called 5ighways in the map 1<!!*,!.0A6 in the G !D#F!A061<! folder. '. The user 1hooses - 1o,,-*+ fro, - *e: .te, o* the ,e*u 6-r th-t o!e*s - Get ?est Route too 6o9. The too 6o9 1o*t-.*s - C .1= o* M-! too -*+ -* e+.t 6o9 for ty!.*5 - se-r1h +.st-*1e; -*+

:. oo= .=e th.s: ). The user sets -* -!!ro!r.-te se-r1h +.st-*1e; 1hooses the C .1= o* M-! too ; -*+ 1 .1=s so,e:here o* the ,-!. 2. If *o !o.*ts -re :.th.* the se-r1h +.st-*1e the* +.s! -y - ,ess-5e -*+ retur*; other:.se +.s! -y +.- o5 6o9 :.th - s1ro .st 1o*t-.*.*5 the !o.*ts :.th.* the se-r1h +.st-*1e; ! us O> -*+ C-*1e 6utto*s. Sho: the *et:or= +.st-*1e; the 1ro: f .5ht +.st-*1e; 1.ty; -*+ st-te .* the s1ro .st; :.th the 1.t.es or+ere+ 6y 1ro: f .5ht +.st-*1e. The +.- o5 6o9 :. oo= .=e th.s: &. If the user 1 .1=s C-*1e the* 1 ose the +.- o5 6o9. O*1e the user h-s 1hose* - ! -1e e*-6 e the O> 6utto*. Whe* the user 1 .1=s O> 8oo, the ,-! to .*1 u+e the 1 .1=e+ !o.*t -*+ the 1hose* ! -1e; +.s! -y the route; the* 1 ose the +.- o5 6o9. #. Set u! the -++(.* -s - 1usto, -!! .1-t.o* so th-t; :he* the user ru*s Tr-*sCA< fro, - *e: !ro5r-, .1o* o* the +es=to!; the -++(.* .s -uto,-t.1- y ru* -*+ .ts ,e*u .s -++e+ to the ,e*u 6-r.

-ith your spec in hand, you are ready to set up the wor& environment and get started.

(o ,repare or -riting an Add-In

7. f you haven"t already done so, start TransCAD and start your text editor. '. M-=e Tr-*sCA< the 1urre*t -!! .1-t.o*. 9. f you have not already done so, start G !D# by choosing Tools-Add Ins, highlighting G ! Developer"s #it, and clic&ing *#. E. Choose Help-GISDK Help to open the G !D# help file so that you can loo& up the full documentation of the G !D# functions you will be using. t is very helpful to &eep the on(line help window open when reading and writing G !D# code. -hen you &now the name of the function you are loo&ing for, clic& the ndex tab and type in the first few characters of the function, then clic& the appropriate item in the list. f you are trying to decide which function to use, clic& the Contents tab and choose the *utline of Topics page in the -elcome to G !D# 5elpG boo&.

For more information, see:

1esson 7. A !earch 0acro and a Test 6rogram 1esson 8. Adding a Toolbox 1esson 9. Adding a Dialog Box 1esson E. Calling the Toolbox from the 0enus 1esson @. nstalling the Add(in 1esson H. +unning the Add(in from the Des&top

Lesson .# A Search &acro and a (est ,rogra"

4ou will start with a macro that does the searching for the nearest points and calculating of the networ& distances. As your user interface develops, it can continue to call this same macro. By ma&ing it a separate macro, you are beginning to build a library of reusable macros. t is also easier to develop and maintain your program this way because you can test the search macro independently from the calling environment. 1ater 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. n 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 1<!!*,7.+!C, which was installed in your G !D#F!A061<! folder. The test macro name is the same as the file name $Clesson7C% to ma&e it easy to remember, but the macro name could be different. +ead through the macros carefully to get an idea of what is going on. == This code is in lesson7.rsc. 0acro ;lesson7; == !ave the name of the current layer. currIlayer J Get1ayer$% == !et the line and node layer variables. lineIlayer J C5ighwayC nodeIlayer J CCD) ,ode 1ayerC == !et the current layer to the line layer. !et1ayer$lineIlayer% == Define the fields in the networ& as length and travel time. The first element in the array is the == field name you assign in the networ&. The second and third elements are the field names in == the highway database in the forward and reverse directions. lin&flds J KKC1engthC, lineIlayerLC.1engthC, lineIlayerLC.1engthCM, KCNTravel TimeOC, lineIlayerLC.NTravel TimeOC, lineIlayerLC.NTravel TimeOCMM == !hare the networ& as you will need it in other macros in this file. shared net == Create the networ& and assign a temporary name to the networ&. net J create,etwor&$,GetTemp)ile,ame$CP.netC%,C,etwor&C,lin&flds,,%

== +estore the current layer. !et1ayer$currIlayer% == !et up the arguments for the nearest points macroD by setting these in variables it is easier == to read the actual +un0acro$% call and &now what is being passed. == !pecify a layer name in the current mapD layer names are case sensitive. layer J ;6lace; == /se an arbitrary coordinate near Boston for now. Coordinates are given as integer millionths == of degrees, longitude first, then latitude. This coordinate is at (Q7.789E@H degrees longitude == and E8.E@H987 degrees latitude. clic&edIpoint J Coord$(Q7789E@H, E8E@H987% == !et a search distance of @ miles, based on the current map units. currentIunits J Get0ap/nits$C6luralC% distance J @ P Get/nit!i'e$C0ilesC, currentIunits% == Call the nearest points macro. result J +un0acro$Cget nearest pointsC, layer, highwayIlayer, nodeIlayer, clic&edIpoint, distance% == !how the list of nearest points. !howArray$result% end0acro == A macro to get the nearest points on the search layer and the highway distances == between the source and target points 0acro Cget nearest pointsC $searchIlayer, nodeIlayer, sub:ectIpoint, searchIdistance% == <ach macro should have a description at the beginning. == )inds points within searchIdistance units of sub:ectIpoint on searchIlayer and returns an array == containing a data array for each point, with networ& distance, crow flight distance, city and stateD == the data arrays are in order by networ& distance. This macro is designed to wor& with the 6lace == and 5ighway layers in 1essons.map. == !tore the current layer, then ma&e the specified layer the wor&ing layer. currIlayer J Get1ayer$% !et1ayer$searchIlayer% == )ind the nearest points in the wor&ing layer and return, in array rhs, the record handles $the string

== form of the record D% for the closest records. The last argument, an options array, can be null. rhs J 1ocate,earest+ecords$sub:ectIpoint, searchIdistance, null% == f no points were found then display message and return. if rhs J null then do !how0essage$;!orry, no points were within your search distance.;% == +eset the layer to the stored layerD this is very important when an == add(in is wor&ing with the standard interface !et1ayer$currIlayer% return$% end == Dimension an array to the length of the record handles $rhs% array. Dim dataNrhs.lengthO == share the networ& variable shared net == 1oo& through the record handles array. for i J 7 to rhs.length do == /se the record handle to set the current record position on the == current view $which in this case is the 6lace layer%. !et+ecord$, rhsNiO% == Get the point coordinate for the current record on the current layer, == converting the record handle to its numeric e3uivalent $an D%. targetIpoint J Get6oint$rh8id$rhsNiO%% == Get the distance between the clic&ed point and the current point. distance J GetDistance$sub:ectIpoint, targetIpoint% == !et the current layer to the node layer and get the node Ds of the nodes closest to the == sub:ectIpoint and the targetIpoint, converting the record handle to its numeric e3uivalent !et1ayer$nodeIlayer% rh7 J 1ocate,earest+ecord$sub:ectIpoint, searchIdistance% rh8 J 1ocate,earest+ecord$targetIpoint, searchIdistance% node7 J rh8id$rh7% node8 J rh8id$rh8% == Calculate the shortest path between the sub:ect and target point using the first networ& == field $distance%. *nly do this if the two nodes are not the same, otherwise, networ&Idistance J ?.

== Also, gather the list of lin& Ds and directions that form the best networ& path. if node7 RS node8 then do sp J !hortest6ath$net, Knode7, node8M, 7, % networ&Idistance J spN7O lin&s J spN8O directions J spN9O end else networ&Idistance J ? == Add data to the output array. To add data from a current record for a layer use a Cfield specificationC, == which is the layer name in a variable L C.C L field name, e.g. layer.city, not 6lace.city. dataNiOJKnetwor&Idistance, distance, searchIlayer.city, searchIlayer.state, targetIpoint, lin&s, directionsM !et1ayer$searchIlayer% end == end of record handles loop == +eset the layer and return the data array to the calling program !et1ayer$currIlayer% return$data% <nd0acro f you have done any programming before, the syntax of this language should loo& familiar. 0acros are called li&e subroutines, with arguments. A )or loop is used to loop through a list. Arrays can be dimensioned and referenced with subscripts. The macro calls several functions $1ocate,earest+ecords$%, GetDistance$%, etc.% that find records and compute distances.

(o 'o"pile the Sa"ple Add-In

1. M-=e your te9t e+.tor the 1urre*t -!! .1-t.o*.

8. /sing your text editor, open and examine the contents of the [email protected] file in the GIS<>ASAMPLES folder. ). M-=e Tr-*sCA< the 1urre*t -!! .1-t.o*. 2. C .1= .* the GIS<> Too 6o9 to +.s! -y the Co,!. e F. e +.- o5 6o9. @. )rom the G !D#F!A061<! folder, choose the file named 1<!!*,7.+!C and clic& *pen. G !D# compiles the file. The compiler chec&s the syntax of the statements in the file. f there are any errors, they are displayed, and also written to a file of the same name, but with the extension .<++. n this case, there are no errors.

 (o Run the Sa"ple Add-In

7. Choose File-Open or clic& on the toolbar, choose 0ap as the file type, browse to the G !D#F!A061<! folder in your TransCAD program folder, choose 1<!!*,!.0A6, and clic& *pen to display a map of the 0assachusetts, Connecticut and +hode sland with the 6lace layer showing city and town points. '. C .1= .* the GIS<> Too 6o9 to +.s! -y the Test -* A++(I* +.- o5 6o9. ). C .1= M-1ro .* the Ty!e of A++(I* r-+.o .st. 2. Ty!e B esso*1B .* the @-,e te9t 6o9.
&. C .1= O>. Tr-*sCA< f.*+s the ! -1es :.th.* & ,. es of the su!! .e+ !o.*t -*+ +.s! -ys - +.- o5 6o9 :.th -* -rr-y 1o*t-.*.*5 the +.s! -y +-t-. The +.st-*1es :. 6e .* the 1urre*t ,-! u*.ts. #. C .1= O>.

TransCAD closes the dialog box. That"s all there is to itG 4ou have compiled and tested your first G !D# program. 4ou can leave the 1essons map open, because you will be using it again in a few minutes.

Lesson /# Adding a (oolbo0

,ow, instead of having the test program supply a coordinate, you want to get it from the users when they clic& on the map. A toolbox is a dialog box that stays on the screen all the time. t can contain a CtoolC that captures the user"s interaction with the map. The test program $now called macro Clesson8C% calls the toolbox which will, in turn, call the Cget nearest pointsC macro developed in 1esson 7. The source code for 1esson 8 is stored in the 1<!!*,8.+!C file in the G !D#F!A061<! folder. Below is the source code, excluding the Cget nearest pointsC macro that remains unchanged. == This code is in lesson8.rsc. 0acro Clesson8C == !ave the name of the current layer. currIlayer J Get1ayer$% == !et the current layer to the line layer. lineIlayer J C5ighwayC !et1ayer$lineIlayer% == Define the fields in the networ& as length and travel time. The first element in the array

== is the field name you assign in the networ&. The second and third elements are the field == names in the highway database in the forward and reverse directions. lin&flds J KKC1engthC, lineIlayerLC.1engthC, lineIlayerLC.1engthCM, KCNTravel TimeOC, lineIlayerLC.NTravel TimeOC, lineIlayerLC.NTravel TimeOCMM == !hare the networ& as you will need it in other macros in this file. shared net == Create the networ& and assign a temporary name to the networ&. net J create,etwor&$,GetTemp)ile,ame$CP.netC%,C,etwor&C,lin&flds,,% == +estore the current layer. !et1ayer$currIlayer% == Call the toolbox. resultJ+unDbox$Cget best route toolboxC%% end0acro == Create a toolbox, which is a type of dialog box $dbox%. == The &eyword CToolBoxC ma&es the dialog box display until closed by the user. == The &eyword ,o#eyboard moves the focus to the toolbox immediately when user clic&s in it. Dbox Cget best route toolboxC center,center Title. CGet Best +outeC ToolBox ,o#eyboard == A description of the dialog box. == Displays Clic& on 0ap tool and <dit Text item to input search distance. Defaults search distance to == @ milesD when user clic&s 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. nit do == !et the point layer variable for use belowD 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. pointIlayerJC6laceC == set the highway and node layer variable for use belowD highwayIlayer J C5ighwayC nodeIlayer J CCD) ,ode 1ayerC == nitiali'e the searchIdistance to @ miles, based on the current map units. == +8 $% changes a real number to an integer. currentIunits J Get0ap/nits$C6luralC%

searchIdistance J +8 $@ P Get/nit!i'e$C0ilesC, currentIunits%% end tem == This is needed to allow the user to close the toolbox by clic&ing on the T in the upper(right == corner. This also clears any path annotations that were drawn previously. Close do if aid RS null then DropAnnotation$, aid% return$% end tem == Create a tool that, when chosen, waits for the user to clic& on the map. 4ou will use the find == icon from the standard TransCAD bitmap file $buttons.bmp%, with bitmaps for not chosen, == chosen and disabled. Tool Cclic&ItoolC ?,7 cons.CbmpFFbuttonsU99C, CbmpFFbuttonsUHQC, CbmpFFbuttonsU7?7C help. CClic& on 0apC do == -ait for user to clic& on map. clic&edIpoint J Clic&Coord$% == +un the nearest places macro from lesson 7. == A program line can be continued on to the next line at any point == except in the middle of a string. pointsIlist J +un0acro$Cget nearest pointsC, pointIlayer, highwayIlayer, nodeIlayer, clic&edIpoint, searchIdistance% == f the macro found points then display the dataD if no points are found, the macro == has already displayed a message, so :ust drop through to end of item. if pointsIlistRSnull then do == 4ou will copy the data into a formatting array for use in a scroll list in lesson 9. == To demonstrate another way to create an array, you will build it by == concatenation rather than dimensioning it. == )irst set the formatting array to null. formattingIarray J null == ,ow loop through the list of points and their data for i J 7 to pointsIlist.length do == Concatenate the array with an array containing your data. == )irst, create arrays for the formatting of each field. == ,et distance and Crow distance will be right :ustified, == 7 decimal, ending in columns @ and 7>. fInetdistance J K@, C+P?.?C, pointsIlistNiON7OM

fIdistance J K7>, C+P?.?C, pointsIlistNiON8OM == City will be left :ustified, starting in column 8@. fIcity J K8@, C1C, pointsIlistNiON9OM == !tate will be left :ustified, starting in column EH. fIstate J KEH, C1C, pointsIlistNiONEOM == !econd, put them together in an array. fIarray J K fInetdistance, fIdistance, fIcity, fIstate M == Third, concatenate the formatting array with that array. formattingIarray J formattingIarray L K fIarray M end == )or chec&ing purposes loo& at the original array and the formatting array. To == show more than one variable with !howArray$%, combine them both into an array. !howArray$KCpointsIlistJC, pointsIlist, CformattingIarrayJC, formattingIarrayM% end end tem == Display the current integer value of searchIdistance and allow user to change it. == 6lace the title at column H, .@ rows down, and 7H characters wide. Text C!earch DistanceC H, .@, 7H == 6lace the integer edit box below the C!earch DistanceC title and ma&e it E characters wide. <dit nteger >, 8.?, E 2ariable. searchIdistance == 6lace the text for the current map units right after and on the same line as the integer edit box. Text after, same 2ariable. currentIunits <ndDBox NOTE: This updated macro includes an intentional typo on line 8V $an extra close parenthesis in the +unDbox$% command%, to show you what happens when G !D# encounters a syntax error during compilation. 1et"s go ahead and compile the new version.

(o 'o"pile the 1nhanced $ersion

7. )rom your text editor, open and examine the contents of the 1<!!*,8.+!C file in the G !D#F!A061<! folder. '. Fro, Tr-*sCA<; 1 .1= .* the GIS<> Too 6o9 to +.s! -y the Co,!. e F. e +.- o5 6o9.

9. )rom the G !D#F!A061<! folder, choose the file named 1<!!*,8.+!C and clic& *pen. G !D# compiles the file. -hen the G !D# 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 .<++, and is always placed in the same folder as the resource file itself. G !D# also displays the contents of the error file as shown below. $ f you don"t see the error message, it is possible that someone else may already have run this tutorial and fixed the typo.%

)or 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(&ey through the error and resource files.

(o 'orrect the Resource 1rror

1. S:.t1h 6-1= to the te9t e+.tor. '. Re,o/e the e9tr- 1 ose !-re*thes.s .* .*e 'C. ). S-/e the ,o+.f.e+ f. e. 2. S:.t1h 6-1= to Tr-*sCA<. &. C .1= .* the GIS<> Too 6o9 to +.s! -y the Co,!. e F. e +.- o5 6o9.

H. Choose the 1<!!*,8.+!C file and clic& *pen. This time, G !D# compiles the file successfully. ,ote that G !D# compiles programs that are stored in files. This means that you ust sa!e your "i#e using your te$t editor %rogra &e"ore you can co %i#e and run it with GISDK . ,ote also that you do not actually need to be running your text editor to compile or run a G !D# program. 5owever, if you get into the habit of running G !D# and your text editor at the same time, you"ll find you can modify your files and compile them very efficiently.

(o Run the 1nhanced Add-In

1. C .1= o* the Lesso*s ,-! to ,-=e .t the -1t./e :.*+o:. '. C .1= .* the GIS<> Too 6o9 to +.s! -y the Test -* A++(I* +.- o5 6o9. ). C .1= M-1ro .* the Ty!e of A++(I* r-+.o .st. 2. Ty!e B esso*'B .* the @-,e te9t 6o9. &. C .1= O>. The -++(.* st-rts ru**.*5 -*+ +.s! -ys the BGet ?est RouteB too 6o9 .* the 1e*ter of the s1ree*.

#. C .1= the C .1= o* M-! too ; the* 1 .1= o* the ,-! :.th.* & ,. es of - ! -1e. The -++(.* +.s! -ys the -rr-ys of +-t- for the *e-rest !o.*ts. $. Ch-*5e the se-r1h +.st-*1e to 1 ,. e -*+ 1 .1= o/er - ,. e -:-y fro, -*y ! -1es. The -++(.* +.s! -ys the B*o !o.*tsB ,ess-5e. 3. C .1= the X .* the u!!er r.5ht h-*+ 1or*er to 1 ose the too 6o9.

4ou have proven that the toolbox is wor&ing. Again, leave the map open. 4ou"ll be using it again in a few minutes.

Lesson 2# Adding a Dialog Bo0

,ow you can add a dialog box $Cget choiceC% to display the formatted list of networ& and crow flight distance, city, and state, and allow the user to pic& one or to cancel. 4ou will revise the Cget best route toolboxC dialog box code to call the Cget choiceC dialog box and, if the user pic&s a place, create a new scope for the map to show the clic&ed point and the chosen place, and then redraw the map. The test macro $now Clesson9C% and the Cget nearest pointsC macro remain the same and are not shown below. All of the 1esson 9 source code is stored in the 1<!!*,9.+!C file in the G !D#F!A061<! folder. 5ere is the the Cget choiceC dialog box. == Create a dialog box to display the choices DBox Cget choiceC $pointsIlist% Title. CChoose a 6laceC == Displays the pointsIlist formatted array of dataD re3uires the user to choose one and == clic& *#. +eturns an array index for *# or null if Cancel is clic&ed. nit do == disable the *# button to startD enable it when a line in the scroll list is chosen. Disable tem$C*#C% end tem == Add some titles for the scroll list. Text C,et DistanceC 7, ? Text CCrow DistanceC 79, ? Text CCityC 8H.@, same Text C!tateC EQ.@, same == Display the formatted arrayD the &eyword CmultipleC is not used, so only one choice == will be possible. The pointsIidx variable will contain the index $subscript% of the == selected array element. !croll 1ist 7, 7, @@, 7@ 1ist. pointsIlist 2ariable. pointsIidx

Do == -hen user ma&es a choice, enable the *# button. <nable tem$C*#C% end tem == Add an *# button. Default &eyword allows the user to press <nter. Button C*#C 9@, 7Q, V, 7 Default Do == +eturn the index $subscript% of the chosen element return$pointsIidx% end tem == Add a Cancel button. Cancel &eyword allows the user to press <sc. Button CCancelC EH, same, V, 7 Cancel Do == +eturn null if user cancels return$% end tem <ndDBox 0ost of the code for the Cget best route toolboxC dialog box is the same as in 1esson 8. *nly 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 J +unDbox$Cget choiceC, formattingIarray% == f the user didn;t press Cancel then create a scope and 'oom if choiceRSnull then do == Get the conversion between miles and the current map units miIcmu J Get/nit!i'e$C0ilesC, Get0ap/nits$C6luralC%% == Compute .7 and @ miles in current units tenth J .7 P miIcmu five J @ P miIcmu == Create a tiny scope for the clic&ed point. A scope is a center point, and a width == and height in the current map units. The last argument to !cope$% must be 'ero. clic&edIptIscp J !cope$clic&edIpoint, tenth, tenth, ?% == Create a tiny scope for chosen pointD the coordinate is in array element @. chosenIptIscp J !cope$pointsIlistNchoiceON@O, tenth, tenth, ?%

== ,ow combine the two scopes newIscope J !cope/nion$clic&edIptIscp, chosenIptIscp% == f the two points were less than five miles apart then set the scope width and == height to @ milesD otherwise expand the scope by 7?W to add a margin. if newIscope.heightR five then newIscope J !cope$newIscope.center, five, five, ?% else newIscope J !cope$newIscope.center, newIscope.widthP7.7, newIscope.heightP7.7, ?% == ,ow set the new scope. !et0ap!cope$, newIscope% == Delete the old path annotation if it existed previously. if aid RS null then DropAnnotation$, aid% == f path exists, draw the shortest path on the map by. == 7. Getting the list of coordinates of the path given it;s lin& Ds and directions. == 8. Adding a coordinate to beginning and end depicting the origin and destination places. == 9. Drawing an annotation in red with a 9.@ point thic&ness of the path. == E. +esetting the scope to the extents of the path. if pointsIlistNchoiceON7O S ? then do currIlayer J Get1ayer$% !et1ayer$highwayIlayer% pthcoords J 6athCoords$highwayIlayer L C. DC, pointsIlistNchoiceONHO, pointsIlistNchoiceONQO% !et1ayer$currIlayer% pthcoords J Kclic&edIpointM L pthcoords L KpointsIlistNchoiceON@OM aid J AddAnnotation$, C6olylineC,K KC6ointsC, pthcoordsM, KC1ine colorC, Color+GB$H@@9@, 7, 7%M, KC1ine widthC, 9.@M M% == f the path ends are less than five miles apart then set the scope width and == height to @ milesD otherwise expand the scope by 7?W to add a margin. newIscope J GetArray!cope$pthcoords% if newIscope.heightR five then newIscope J !cope$newIscope.center, five, five, ?% else newIscope J !cope$newIscope.center,

newIscope.widthP7.7, newIscope.heightP7.7, ?% !et0ap!cope$, newIscope% end +edraw0ap$% end

(o 'o"pile and Run Lesson 2

7. )rom your text editor, open and examine the contents of the 1<!!*,9.+!C file in the G !D#F!A061<! folder. '. Fro, Tr-*sCA<; 1 .1= .* the GIS<> Too 6o9 to +.s! -y the Co,!. e F. e +.- o5 6o9. 9. Choose the file named LESSO@).RSC in the GIS<>ASAMPLES folder, and clic& *pen. G !D# compiles the file. 2. C .1= o* the Lesso*s ,-! to ,-=e .t the -1t./e :.*+o:. &. C .1= .* the GIS<> Too 6o9 to +.s! -y the Test -* A++(I* +.- o5 6o9. #. C .1= M-1ro .* the Ty!e of A++(I* r-+.o .st. $. Ty!e B esso*)B .* the @-,e te9t 6o9. 3. C .1= O>. The -++(.* st-rts ru**.*5 -*+ +.s! -ys the BGet ?est RouteB too 6o9 .* the 1e*ter of the s1ree*. C. C .1= the C .1= o* M-! too ; the* 1 .1= o* the ,-! :.th.* & ,. es of - ! -1e. @o: the -++(.* +.s! -ys the +.- o5 6o9 :.th the s1ro .st of 1ho.1es. 1D. Choose - ! -1e -*+ 1 .1= O>. The -++(.* re+r-:s the ,-! 8oo,e+ .* to sho: your 1 .1=e+ !o.*t -*+ your 1hose* 1.ty. 11. C .1= the X .* the u!!er r.5ht h-*+ 1or*er to 1 ose the too 6o9. 4ou did not have to display the scroll list in a separate dialog box. 4ou could easily have added it to the toolbox, but then it would have ta&en up a lot of space in a dialog box that stays on the screen all the time.

Lesson 3# 'alling the (oolbo0 ro" the &enus

,ow 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. 4ou will also see how your source code can be &ept in separate files, but be compiled into a single program. 4our code for adding the new menu will be &ept in 1<!!!*,E.+!C in the G !D#F!A061<! folder. An additional file, 1<!!!*,E.1!T, contains a list of the source code files to be compiled. t includes a reference to the

1<!!!*,9.+!C

file, which we will use unchanged, and also a reference to your new code, 1<!!!*,E.+!C, which is shown below. == This code is in lessonE.rsc. == Add a C1essonC menu with a CGet Best +outeC item to the main menu 0acro ClessonEC == This macro adds the C1essonC menu before the CwindowC menu == )irst, ma&e sure the C1essonC menu is not already there. == This error handler prevents an error message if the menu isn;t there. on ,ot)ound goto next == ,ow remove the menu,... +emove0enu tem$CG !D# 1esson 0enuC% == +eset the error handling,... next. on ,ot)ound default == And add the menu Add0enu tem$CG !D# 1esson 0enuC, CBeforeC, C-indowC% end0acro 0enu C1esson 0enu !ystemC == This is the top(level title to be added to the main menu system 0enu tem CG !D# 1esson 0enuC text. C1essonC &ey. altIl menu C1esson Dropdown 0enuC end0enu 0enu C1esson Dropdown 0enuC == This is the body of the drop(down menu to be added 0enu tem CGet Best +outeC text. CGet Best +outeC &ey. altIX do == *pen the toolbox +un0acro$Clesson9C% end tem end0enu

 (o 'o"pile and Run Lesson 3

7.

)rom your text editor, open and examine the contents of the 1<!!*,E.+!C and 1<!!*,E.1!T files in the G !D#F!A061<! folder. '. Fro, Tr-*sCA<; 1 .1= .* the GIS<> Too 6o9 to +.s! -y the Co,!. e F. e +.- o5 6o9. 9. Choose the file named [email protected] in the GIS<>ASAMPLES folder, and clic& *pen. G !D# compiles both the files listed into a single compiled program. 2. C .1= o* the Lesso*s ,-! to ,-=e .t the -1t./e :.*+o:. &. C .1= .* the GIS<> Too 6o9 to +.s! -y the Test -* A++(I* +.- o5 6o9. #. Ty!e B esso*2B .* the @-,e te9t 6o9. Q. Clic& *#. The Lesson menu is added to the menu bar, and it has one command, Get Best Route. >. Choose Lesson(Get Best Route. The add(in displays the toolbox created in 1esson 8. ,ow you can use the toolbox as before. 4our add(in is completeG

Lesson 4# Installing the Add-in

G !D# stores compiled resource files in a special database called a user interface database. This database is often referred to as the +' ,atabase, and consists of a collection of files on dis& with the same name and extensions of .7, .8, .9, .E, .@, .H, and .DBD. -hen you compile and test add(ins as we have been doing so far, G !D# stores the compiled macros in a / Database named T<!TI/ , which is stored in the G !D# folder in the TransCAD program folder. To distribute a G !D# application to TransCAD users, you must compile your resource files into a separate, stand(alone / Database with a different name. This / 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 !etup option in the Add( ns dialog box. NOTE: 6roducts developed with one version of G !D# $such as TransCAD% cannot be delivered to users of a different product $such as 0aptitude%. 1et"s wor& through a 3uic& example.

(o 'reate the 5I Database

1. C .1= .* the GIS<> Too 6o9 to +.s! -y the Co,!. e to EI <-t-6-se +.- o5 6o9.

8. Choose the file named [email protected] in the GIS<>ASAMPLES folder, and clic& *pen to display the !ave As dialog box. ). Choose the fo +er th-t 1o*t-.*s the Tr-*sCA< !ro5r-, f. es; ty!e B esso*2B -s the EI <-t-6-se *-,e; -*+ 1 .1= S-/e. G !D# compiles the file into the lessonE / Database. ,ote that the only difference between the and buttons is that the latter stores the compiled resources in your own / Database. ,ow, let"s configure TransCAD so that it can run the add(in from the Add( ns dialog box.

(o Install the Add-In

7. Choose Tools-Add Ins to display the Add( ns dialog box. '. C .1= Setu! to +.s! -y the Setu! A++(I*s +.- o5 6o9. ). C .1= A++ to 1re-te - *e: -++(.*. The +ef-u t +es1r.!t.o* :. 6e BE*t.t e+ A++(.*B -*+ the +ef-u t *-,e for the ,-1ro to 1- :. 6e BE*t.t e+.B 2. C .1= M-1ro .* the r-+.o .st. &. Ty!e BGet ?est RouteB .* the <es1r.!t.o* te9t 6o9. #. Ty!e B esso*2B .* the @-,e te9t 6o9. $. Ty!e B esso*2B .* the EI <-t-6-se te9t 6o9. 3. C .1= O> to .*st- the -++(.* -*+ retur* to the A++(I*s +.- o5 6o9. C. C .1= C-*1e . TransCAD closes the Add( ns dialog box.

(o Run the Installed Add-In

7. Choose Tools-Add Ins to display the Add( ns dialog box. '. H.5h .5ht Get ?est Route .* the s1ro .st. ). C .1= O>. TransCAD runs your add(in, :ust as you would expect.

Lesson 6# Running the Add-in ro" 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 customi'ed user interface and others that add to the

standard interface. !ince 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.

(o 'reate a 'usto" ,rogra" Icon

7. Choose File-Exit to exit TransCAD. '. C ose your te9t e+.tor. ). Co!y the Tr-*sCA< !ro5r-, .1o* o* your W.*+o:s +es=to! 6y ho +.*5 the Ctr =ey -*+ +r-55.*5 the .1o* to - *e: s!ot; or 6y 1o!y.*5 -*+ !-st.*5 - 1o!y of the .1o*. E. +ight(clic& on the new program icon and choose Properties to display the 6roperties dialog box. &. C .1= the Ge*er- t-6 -*+ ty!e BTr-*sCA< :.th Get ?est RouteB .* the e+.t 6o9. #. C .1= the Short1ut t-6 -*+ -++ the fo o:.*5 to the e*+ of the te9t .* the T-r5et e+.t 6o9:
(q (- esso*2 (-. esso*2 (* BTr-*sCA< :.th Get ?est RouteB

The (q o!t.o* tur*s off the Fu.1= St-rt +.- o5 6o9; (- 5./es the *-,e of your - ter*-te EI <-t-6-se; (-. 5./es the *-,e of the st-rtu! ,-1ro; -*+ (* 5./es the !ro5r-, :.*+o: - *e: *-,e. $. C .1= O> to 1 ose the Pro!ert.es +.- o5 6o9. 3. <ou6 e(1 .1= the *e: !ro5r-, .1o*.

TransCAD starts with your add(in as a custom application. f 1esson E had created a completely customi'ed user interface, you could have used the (u and (i options to start TransCAD without the standard interface, but with your custom application. )or more information on custom applications, see nstalling and +unning Custom Applications.