ArcGIS® Engine Developer Guide ArcGIS® 9.1 PUBLISHED BY ESRI 380 New York Street Redlands, California 92373-8100 Copyright © 2004 ESRI ESRI, ArcView, ArcIMS, SDE, Spatial Database Engine, the ESRI globe All rights reserved. logo, ArcObjects, ArcGIS, ArcMap, ArcCatalog, ArcScene, ArcInfo, ArcEditor, Printed in the United States of America. ArcGlobe, ArcReader, ArcToolbox, 3D Analyst, ArcSDE, GIS by ESRI, the ArcGIS logo, www.esri.com, and @esri.com are trademarks, registered The information contained in this document is the exclusive property of trademarks, or service marks of ESRI in the United States, the European ESRI. This work is protected under United States copyright law and Community, or certain other jurisdictions. other copyright treaties and conventions. No part of this work may be reproduced or transmitted in any form or by any means, electronic or Other companies and products mentioned herein are trademarks or mechanical, including photocopying and recording, or by any information registered trademarks of their respective trademark owners. storage or retrieval system, except as expressly permitted in writing by ESRI. All requests should be sent to Attention: Contracts Manager, ESRI, 380 New York Street, Redlands, California 92373-8100, USA. The information contained in this document is subject to change without notice. Contributing Writers Euan Cameron, Chris Davies, Rob Elkins, Kylie Evans, Anne Frankland, Shelly Gill, Natalie Hansen, Sean Jones, Allan Laframboise, Glenn Meister, Dan O’Neill, Rohit Singh, Steve Van Esch, Zhiqian Yu, and Mark Zollinger U.S. GOVERNMENT RESTRICTED/LIMITED RIGHTS Any software, documentation, and/or data delivered hereunder is subject to the terms of the License Agreement. In no event shall the U.S. Government acquire greater than RESTRICTED/LIMITED RIGHTS. At a minimum, use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in FAR §52.227-14 Alternates I, II, and III (JUN 1987); FAR §52.227-19 (JUN 1987) and/or FAR §12.211/12.212 (Commercial Technical Data/Computer Software); and DFARS §252.227-7015 (NOV 1995) (Technical Data) and/or DFARS §227.7202 (Computer Software), as applicable. Contractor/Manufacturer is ESRI, 380 New York Street, Redlands, California 92373-8100, USA. Attribution.pmd 1 1/25/2005, 3:24 PM Contents CHAPTER 1: INTRODUCING ARCGIS ENGINE .................................................... 1 ArcGIS 9 overview............................................................................................................................... 2 Overview of ArcGIS Engine .............................................................................................................. 6 Who can use ArcGIS Engine? ....................................................................................................... 10 ArcGIS Engine capabilities .............................................................................................................. 12 Getting started .................................................................................................................................. 16 Using this book.................................................................................................................................. 19 Developer resources ........................................................................................................................ 20 CHAPTER 2: ARCGIS SOFTWARE ARCHITECTURE ........................................... 23 ArcGIS software architecture ....................................................................................................... 24 ArcGIS application programming interfaces ............................................................................. 29 ArcGIS Engine libraries .................................................................................................................... 32 CHAPTER 3: DEVELOPING WITH ARCGIS CONTROLS ................................. 41 Working with the ArcGIS controls .............................................................................................. 42 Building applications with the ArcGIS controls ....................................................................... 50 CHAPTER 4: DEVELOPER ENVIRONMENTS ........................................................ 57 The Microsoft Component Object Model ............................................................................... 58 Developing with ArcObjects .......................................................................................................... 70 The Visual Basic 6 environment .................................................................................................... 79 The Visual Basic 6 development environment .......................................................................... 92 Visual C++........................................................................................................................................... 99 .NET application programming interface ................................................................................141 Java application programming interface ...................................................................................182 C++ application programming interface ..................................................................................197 CHAPTER 5: LICENSING AND DEPLOYMENT................................................ 253 ArcGIS licensing options ...............................................................................................................254 ArcGIS Engine Developer Kit ......................................................................................................261 Application development and license initialization ...............................................................286 Testing with ArcGIS Engine Runtime ........................................................................................274 Deployment ......................................................................................................................................277 CHAPTER 6: DEVELOPER SCENARIOS................................................................ 281 Building applications with ActiveX ............................................................................................282 Building applications with visual JavaBeans ............................................................................. 304 Building applications with Windows Controls .......................................................................331 Building applications with C++ and control widgets ...........................................................357 Building a command-line Java application................................................................................409 Building a command-line C++ application ...............................................................................427 Toc.pmd 3 1/25/2005, 5:02 PM APPENDIX A: READING THE OBJECT MODEL DIAGRAMS ..................... 441 Object model key ............................................................................................................................442 Classes and relationships ..............................................................................................................443 Interfaces and members ................................................................................................................446 Putting it together—An example ..............................................................................................449 APPENDIX B: ARCGIS DEVELOPER RESOURCES ............................................ 451 ArcGIS software developer kit ....................................................................................................452 ArcGIS Developer Online Web site ...........................................................................................454 APPENDIX C: CONVERTING PERSONAL GEODATABASES..................... 457 Converting data for use with the GIS Server on UNIX..................................................... 458 APPENDIX D: INSTALLING ARCGIS ENGINE RUNTIME ON WINDOWS, SOLARIS, AND LINUX............................................................ 463 Installing ArcGIS Engine Runtime on Windows .....................................................................464 Installing ArcGIS Engine Runtime on Solaris and Linux ......................................................479 GLOSSARY.......................................................................................................................... 491 INDEX ................................................................................................................................. 507 iv • ArcGIS Engine Developer Guide Toc.pmd 4 1/25/2005, 5:02 PM Introducing 1 ArcGIS Engine ESRI® ArcGIS® Engine is a platform for building custom standalone geographic information system (GIS) applications that support multiple application programming interfaces (APIs), include advanced GIS functionality, and are built using industry standards. This chapter will introduce you, the developer, to the ArcGIS Engine developer kit and the ArcGIS Engine Runtime, discussing how to use it and its different components. Topics covered in this chapter include: • an overview of ArcGIS 9 • introduction to ArcGIS Engine • ArcGIS Engine users • capabilities of ArcGIS Engine • a description of this book Ch01_Intro.pmd 1 1/25/2005, 3:14 PM ARCGIS 9 OVERVIEW ArcGIS provides a scalable framework