Using the C++ samples

Summary
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 this SDK, see Installing the samples.
Each sample is composed of one or more files and may be as simple as a single function or as complex as an entire application. To use an ArcObjects sample 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.
Windows users will build the samples using the Visual Studio integrated development environment (IDE) and/or the Windows command line.
UNIX users will use the Solaris or Linux command shells. These environments are outlined below:
  • Microsoft's Visual Studio development environment
    • Setting up your compiler
    • Compiling sample applications
    • Running sample applications
  • The Windows command line
    • Setting up your compiler
    • Compiling sample applications on Windows
    • Running sample applications on Windows
  • Using ArcObjects applications on Solaris and Linux
    • Setting up your compiler
    • Compiling sample applications on UNIX
    • Running sample applications on UNIX

Installing the samples

The ArcGIS developer samples are included in the default installation of the ArcObjects Software Development Kit (SDK). If you do not have them installed, rerun the SDK install wizard, choose Modify, and select the samples feature.

Location of sample source code

The source code for C++ samples is located in the DeveloperKit<version> folder in your ArcGIS installation location. The /Samples/ArcObjectsCPP folder contains a folder for each sample. In the installed developer help system, the sample's location can be found in the sample's README file, after the table of files.
For example, the Motif C++ source for a sample named MapTocToolbar and located in the help system's table of contents at Samples -> Controls would be found in 'arcgis/DeveloperKit<version>/Samples/ArcObjectsCPP/MapTocToolbar/Motif_Cpp.
  • In the installed developer help system, the sample's location is in the sample's README file after the table of files.
  • If opening a sample downloaded from the ESRI Resource Centers Web site, the README files are included in the downloaded zip file.
  • Command-line applications—The makefiles of the command-line samples can be found in the sample's source directory. This will usually be a UNIX "Makefile" and a windows nmake "NMakefile.mak". There may also be a vs2005 subfolder containing a solution file which can be opened in the Visual Studio 2005 IDE.
  • Control applications—The makefiles required for the Control samples will be found in the folder containing the source files for that sample.

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 the Microsoft Visual Studio development environment

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 need to open the solution file (.sln) in that environment.

Compiling sample applications

To compile a sample application in Visual Studio:
  • Open the solution file from within the Visual Studio version subfolder of the sample.
  • If you did not install ArcGIS Engine and the SDK into the default directory, you will need to update the include directories as follows:
    • Right-click on the project and select Properties.
    • Choose "All Configurations" in the Configurations combo box.
    • Expand the Configuration Properties -> C/C++ -> General options.
    • Update the directories listed under "Additional Include Directories" to point to the locations of your \ArcGIS\DeveloperKit<version>\include\CPPAPI and \ArcGIS\Engine<version>\com folders.
  • You will also need to update the path from the sample to any data used.
  • Choose Build Solution from the Build menu or press F7 to build the sample.
The sample is now ready for use.
If you are working on a Vista or Windows 7 machine, you will need to run Visual Studio with Administrator permissions in order to compile DLL samples.
If you are working on a 64-bit machine, you will need to update the OLB path in the .h files for the samples to work.

Running sample applications

Before running a sample you should first 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.
  • Visual Studio 2005: Go to the Configuration Properties -> Debugging item and add any arguments to "Command Arguments".

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

Using ArcObjects applications from the Windows command line

Setting up your compiler

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. A batch file called vsvars32.bat is provided by Microsoft which can be found in C:\Program Files\Microsoft Visual Studio 8\Common7\Tools which can be used to set up your environment. Once you run vsvars32.bat your include and library paths should be set up for command line (nmake) compiling.
An alternative (and easier) method is to use the Visual Studio Command Prompt. To do this complete the following steps:
  1. Go to Start Menu -> All Programs -> Microsoft Visual Studio <version> -> Visual Studio Tools
  2. Open Visual Studio <version> Command Prompt.
Then change to the folder that contains the sample you wish to compile by typing the following at the command prompt:
cd %ARCGISHOME%\DeveloperKit<version>\Samples\ArcObjectsCPP\BuildPyramidsCpp\Cpp
You may also wish to make sure the sample is freshly built by cleaning up the last build. You can do this by typing the following at the command prompt:
nmake /f NMakefile.mak clean all

Compiling sample applications

To build the sample using the command line you will be using the Microsoft NMAKE utility. NMAKE should be available from the command line if you have set up your environment as mentioned in Setting up your compiler previously.
To compile from the command line, you will specify the NMakefile.mak makefile which is included in the sample's source directory. At the command line, type the following:
nmake /f NMakefile.mak
  • If you see any compile errors you may need to check the following:
    Check that the environment variable ARCGISHOME points to your ArcGIS installation directory (e.g. C:\Program Files\ArcGIS).
  • Run the vsvars32.bat or use the Visual Studio Command Prompt as mentioned above.
  • The NMakefile.mak files includes a global makefile in %ARCGISHOME%\DeveloperKit<version>\Samples\ArcObjectsCPP\MakefileUtilities called "mk.Windows". Check that this file references the correct paths.
  • Build clean to remove any object files from a previous build by typing the following at the command prompt:
    nmake /f NMakefile.mak clean all
If you are working on a 64-bit machine, you will need to update the OLB path in the .h files for the samples to work.

Running sample applications on Windows

Before running the samples 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. If arguments are needed, a usage message will be displayed.

Using ArcObjects applications on Solaris and Linux

Setting up your compiler

To build and run the UNIX samples your environment must be set up to access the Developer Kit header files and scripts. To do this, you will need to source the init_engine.[c]sh script located in your ArcGIS installation directory:
(Cshell)
% source /opt/arcgis/init_engine.csh
(Bash)
% . /opt/arcgis/init_engine.sh

Compiling sample applications on UNIX

To compile the samples on UNIX you will use the GNU "make" utility and build using the supplies makefiles. You will use a Makefile to compile. The makefiles are included in the source directory of each sample application, they are called simply "Makefile". To compile the sample simply run "make":
% make
When compiling using the makefile you should be able to build the sample without any changes. However, if you are seeing compile/link errors you might need to check the following:
  • Check that the environment variable $ARCENGINEHOME points to your ArcGIS installation directory (e.g. /opt/arcgis). This variable gets set when you source the init_engine.[c]sh script (see above).
  • Compile a simple "hello world" program to ensure that your compiler is set up properly.
  • The Makefile includes two global makefiles that contain definitions for your UNIX environment:

    include $(ARCENGINEHOME)/DeveloperKit10.0/Samples/ArcObjectsCPP/MakefileUtilities/mk.global
    include $(ARCENGINEHOME)/DeveloperKit10.0/Samples/ArcObjectsCPP/MakefileUtilities/mk.$(UNAMES)

    Check that this file references the correct paths.
  • Build clean to remove any object files from a previous build:
    % make clean all
The sample is now ready to use.
If you are working on a 64-bit machine, you will need to update the OLB path in the .h files for the samples to work.

Running sample applications on UNIX

To run the UNIX samples you will need to follow the same steps mentioned above in the section Running sample applications on Windows.