EDN Code Exchange

Updated Sep 29, 2010

How to Use the C++ Samples

This topic provides general information on how to use the C++ samples. Additionally, each sample has a help topic with detailed instructions on how to use that particular sample. If you did not selected to install the samples when you installed your ArcGIS Engine, see Installing the samples.

There are two types of samples: tips and tools. A tip is a single function which you will use by pasting simply pasting the function into your own code and calling it. A tool is composed of one or more files and will be as simple as a single function or as complex as an entire application. This document addresses how to use the code provided in a tool.

To use an ArcObjects tool which is not a complete application, but instead simply one or more functions in their own files, you will incorporate the provided files into your own code. This procedure is outlined in Using Sample Functions, and will result in you creating your own complete ArcObjects application.

To use a complete ArcObjects tool application, either from a tool or your own code, you have two development options on Windows:

You can also choose to use the provided executables which install with each sample that is a complete application.

Installing the Samples

The ArcGIS developer samples are not included in the 'typical' installation of the ArcGIS Engine Developer Kit. If you do not have them installed, rerun the Developer Kit install wizard, choose Custom or Modify, and select the samples feature under Software Developer Kit.

The Code Exchange on the ESRI Developer Network (EDN) Web site (http://edn.esri.com) has a download for each sample which contains all of the files associated with the sample. It also has new samples added since the last release.

Location of Sample Source Code and Provided Executables

The source code for C++ samples is located throughout the 'arcgis/developerkit/samples/' folder at your ArcGIS Engine install location. The samples folder contains the top-level samples folders (for example, "Controls"). In each of those folders are compressed files whose names match the sample names, with the addition of the implementation language. For example, the Motif C++ source for a sample located in the TOC at Controls > MapControl and named MapTocToolbar would be found in 'arcgis/developerkit/samples/controls/MapTocToolbarMotif_Cpp.zip'.

There are executables provided with the samples which are included in the compressed files with the code. The name of the exe matches that of the parent directory of the code folder for that sample.

Command Line Applications
Files required for compilation will be found in subfolders of the uncompressed sample: Visual Studio 6.0 projects in the vs6 folder, Visual Studio .NET 2003 (7.1) in the vs7 folder, and Makefiles in the makefiles folder.

Control Applications
Files required for compilation will be found alongside the code files.

Using Provided Executables

If you do not want to compile the samples on your own but instead wish to use the provided executables, you can do so by running that executable from the command line, making sure you pass in appropriate arguments.

For example, to run the sample "Geodatabase > Accessing_Data > Query_a_shapefile" on a machine with the samples installed and this particular sample uncompressed, start by opening a command prompt. This can be done by going to the Start menu > run and typing in cmd. At the prompt go to the directory with the exe by typing the path to where you uncompressed it. For example: 

    cd "\temp\arcgissamples\Geodatabase\Query_a_shapefileCpp"

To run the sample application on the shapefile located at \data\shapefile type:

    Query_a_shapefile.exe "\data\shapefile"

Using Sample Functions

Some tools only include a sample function or functions. These have been provided for you to use in your own applications. If a sample tool only provides *.h and *.cpp files, and no Makefile or project files, it is a sample function and will need to be called from within your own code, as outlined below.

  1. Add the *.h and *.cpp files to your project.
  2. Include the *.h files in your application.
  3. Call the sample function, making sure to pass in valid arguments.
  4. Compile and run your application.

Using ArcObjects Applications in Microsoft's Visual Studio Development Environment 6.0 or .NET 2003 (7.1)

Setting Up Your Compiler

To use the samples, your compiler must be set up to run ArcObjects code. To run the samples from within Microsoft's Visual Studio you will just need to open the code in that environment. No additional setup is needed.

Compiling Sample Applications

Often you will be able to use the executable provided with a sample, in which case you can skip this step and proceed to Running Sample Applications. However, you will need to open the provided project and compile the application yourself if you need (or want) to modify the source code.

  • Microsoft Visual Studio 6.0
    1. Open the vs6.dsw in the vs6 subfolder of the sample.
    2. If you did not install ArcGIS Engine into the default directory, you will need to update the include directories as follows:
      1. Go to Project Menu > Settings.
      2. Choose "All Configurations" in the "Settings for" combobox.
      3. Go to the C/C++ tab and choose "Preprocessor" in the "Category" combobox.
      4. Update the directories listed under "Additional Include Directories" to point to the include/CPPAPI and Com folders for your ArcGIS Engine install.
    3. Press F7 or choose Build vs6.exe from the Build menu.
  • Microsoft Visual Studio .NET 2003
    1. Open the vs7.sln in the vs7 subfolder of the sample.
    2. If you did not install ArcGIS Engine into the default directory, you will need to update the include directories as follows:
      1. Go to Project menu > Properties.
      2. Choose "All configurations" in the "Configuration" combobox.
      3. Click on the C/C++ folder, then click on "General."
      4. Update the directories listed under "Additional Include Directories" to point to the include/CPPAPI and Com folders for your ArcGIS Engine install.
    3. Choose Build from the Build Solution menu.

The sample is now ready for use.

Running Sample Applications

To run in Microsoft Visual Studio 6.0, open the vs6.dsw in the vs6 subfolder of the sample. To run in Microsoft Visual Studio .NET, use the vs7.sln file which is in the vs7 subfolder of the sample.

First you should refer to the How To Use: C++ and Requires sections in the help topic of the sample you wish to use. If you need to do anything specific to use the particular sample you have chosen, follow those steps. For example, the sample may have specific license or data requirements indicated in those sections.

Next add any necessary arguments to your project by customizing your project settings. Make sure the configuration you are working on is selected in the configuration combobox.

  • Microsoft Visual Studio 6.0: Go to the Project menu > Settings > Debug tab and add any arguments to the "Program arguments" textbox.
  • Microsoft Visual Studio .NET 2003: Go to the Project menu > Properties > Debugging item and add any arguments to "Command Arguments".

Now you are ready to run the sample! You will run it by pressing Control-F5.

Using ArcObjects Applications from the Windows Command Line

Setting Up Your Compiler

To use the samples, your compiler must be set up to run ArcObjects code. To use the samples from the command line, you will need to set up a command line prompt from which the development tools of Visual Studio are available. By default the command line build tools of Visual Studio are not available but a batch file, vcvars32.bat, is provided to make them available.

To run the Visual Studio 6.0 compiler, complete the following steps:

  1. Open a command prompt and cd to C:\Program Files\Microsoft Visual Studio\VC98\Bin, or the equivalent directory containing the Visual Studio 6.0 version of vcvars32.bat.
  2. Type vcvars32.bat to run the batch file.
  3. cd to the directory with the sample code and makefiles.

You will need to run the batch file must be run each time you open a new command prompt. For detailed directions on how to create a batch file that will run the Visual Studio 6.0 version of vccars32.bat for you, see the help located in Development Environments -> C++ -> Platform Configuration -> Configuring Windows.

To run the Visual Studio .NET 2003 compiler, complete the following steps:

  1. Go to Start Menu -> All Programs -> Microsoft Visual Studio .NET 2003 -> Visual Studio .NET Tools.
  2. Open Visual Studio .NET 2003 Command Prompt.

Compiling Sample Applications

Often you will be able to use the executable provided with a sample, in which case you can skip this step and proceed to Running Sample Applications. However, you will need to compile the application yourself if you need (or want) to modify the source code.

To compile from the command line, you will use a Makefile, Makefile.Windows, which is included with each sample application in the makefiles subdirectory. If you did not install to the default location, you will need to edit Makefile.Windows so that the lines: 

	INCLUDEDIRS = \
		/I "C:\Program Files\ArcGIS\include\CPPAPI" \
		/I "C:\Program Files\ArcGIS\Com"
point to the include/CPPAPI and Com folders for your ArcGIS Engine install.

Now compile the sample by typing the following at the command line which has access to the Visual Studio development tools (as set up above): 

	nmake /f Makefile.Windows

The sample is now ready to use.

Running Sample Applications

First you should refer to the How To Use: C++ and Requires sections in the help topic of the sample you wish to use. If you need to do anything specific to use the particular sample you have chosen, follow those steps. For example, the sample may have specific license or data requirements indicated in those sections.

You can run the samples by typing the name of the executable at the command line, followed by any necessary arguments. If you are unsure of the arguments needed, simply type in the name of the executable and attempt to run it. If arguments are needed, a usage message will be displayed.

However, it is recommended that you run the samples through the Makefile, Makefile.Windows, which is provided with each sample application in makefiles subdirectory. To use it, you will need to edit Makefile.Windows to provide any required arguments. For example, if a single shapefile is needed, you would modify:

	#
	# Command line parameters: Edit these parameters so that you can
	# easily run the sample by typing "nmake /f Makefile.Windows run".
	#
	# IN_SHAPEFILE is the input shapefile
	#
	
	IN_SHAPEFILE = c:\data\shapefile

replacing c:\data\shapefile with the shapefile you wish to run the sample on.

Now you are ready to run the application. Execute the application by typing the following at the configured command line:

  	nmake /f Makefile.Windows run

Using ArcObjects Applications on Solaris and Linux

Setting Up Your Compiler

To use the samples, your compiler must be set up to run ArcObjects code. To do this, you will source arcgis/initEngine.sh (or .csh, depending on your shell of choice). If you prefer, that can be done in your shell's RC file (.cshrc or .bashrc, for example). Otherwise you must source that file once per shell.

Compiling Sample Applications

Often you will be able to use the executable provided with a sample, in which case you can skip this step and proceed to Running Sample Applications. However, you will need to compile the application yourself if you need (or want) to modify the source code.

You will use a Makefile to compile. There are makefiles included with each sample application:

  • Makefile.Solaris or Makefile.SolarisMotif: for use on Solaris
  • Makefile.Linux or Makefile.LinuxMotif: for use on Linux

Even if you did not install to the default location, the makefile should be able to compile the sample without any changes. However, if you are not having luck with it, you may need to edit the makefile so that the lines:

	#
	# The INCLUDEDIRS macro contains a list of include directories
	# to pass to the compiler so it can find necessary header files.
	#
	# The LIBDIRS macro contains a list of library directories
	# to pass to the linker so it can find necessary libraries.
	#
	# The LIBS macro contains a list of libraries that the
	# executable must be linked against.
	#
	
	INCLUDEDIRS = \
	-I$(SDKHOME)/include \
	-I/usr/openwin/include
	
	LIBDIRS = \
	-L$(SDKHOME)/lib \
	-L$(MWHOME)/lib-sunos5_optimized \
	-L$(ARCENGINEHOME)/bin \
	-L/usr/openwin/lib
	
	LIBS = -larcsdk

point to the locations of those directories and libraries on your computer.

Now compile the sample by typing the following, using the makefile appropriate for your platform: 

	make -f Makefile.Solaris

The sample is now ready to use.

Running Sample Applications

First you should refer to the How To Use: C++ and Requires sections in the help topic of the sample you wish to use. If you need to do anything specific to use the particular sample you have chosen, follow those steps. For example, the sample may have specific license or data requirements indicated in those sections.

You can run the samples by typing the name of the executable at the command line, followed by any necessary arguments. If you are unsure of the arguments needed, simply type in the name of the executable and attempt to run it. If arguments are needed, a usage message will be displayed.

However, it is recommended that you run the samples through the makefile. You will need to edit the makefile to provide any required arguments. For example, if a single shapefile is needed, you would modify: 

	#
	# Command line parameters: Edit these parameters so that you can
	# easily run the sample by typing "make -f Makefile.Solaris run".
	#
	# IN_SHAPEFILE is the input shapefile
	
	IN_SHAPEFILE = /mycomp/data/shapefile
replacing /mycomp/data/shapefile with the shapefile you wish to run the sample on.

Now you are ready to run the application. Execute the application by typing the following, using the makefile name appropriate for your platform: 

  	make -f Makefile.Solaris run