地理信息系统开发工具GISDK使用手册英文版第一部分WelcometoGISDKHelp.doc

1 PrefaceTransCAD®, 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 Developers 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 easy-to-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 YouWe made several assumptions about you when we put the GISDK Programmers Guide and On-Line Help together:·You are a frequent user of TransCAD and are familiar with the terms and concepts covered in the Users 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 Users 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 HelpThe GISDK Programmers 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 Programmers Guide and this On-Line Help system describe everything you need to know to start using GISDK. In the GISDK Programmers 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 macrosBatch 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 ResourcesThe GISDK Programmers 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 ApplicationsGISDK 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 end-user solutionsCaliper 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 packageThe 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 VersionsThere 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 HelpIf 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 Corporations World Wide Web site (www.caliper.com).3.Send e-mail via the Internet to supportcaliper.com.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 numberYour name and organizationThe version of the product you are using choose Help-About to check your version numberThe exact wording of any messages that appear on your screenIntroductionAs 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 Developers 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 programsIn 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-InsAn add-in is a program that you can add to TransCAD