Interpreting a tool reference page

About interpreting a tool reference page

As a .NET developer, you will frequently use geoprocessing tools; however, not every tool has a code snippet. Consequently, you need to learn how to read the tool documentation and successfully call a tool with the available information in the tool documentation. The basic pattern for calling a geoprocessing tool is always the same; however, the following are the parts of the pattern that change:
  • Tool name
  • Toolbox alias
  • Tool parameters
Obviously, you need to know the name of the tool you want to use before you can begin reading its documentation. This is not always easy as there are hundreds of tools and finding the right one for the job can be daunting. For a good starting point and information on how to search for tools, see A quick tour of finding tools.

Contents of a tool reference page

Once you know the name of the tool, you need to find its reference page in the ArcGIS Desktop Help system. A tool reference page provides the basic information you need to run a tool. Tool reference pages are located in the ArcGIS Resource Center at Library > ArcGIS Help (Desktop) > Geoprocessing > Tool reference. 
All tool reference pages have the same schema. See the following:
  • Title containing the tool label and toolbox alias—A tool label is what ArcGIS for Desktop users see in a toolbox (it can contain spaces). A tool name has no spaces and is what you use in .NET.
  • Summary—Can contain a link to another topic that provides more detail about how the tool works.
  • Illustration (optional).
  • Usage notes—Helpful notes about using the tool. 
  • Syntax—Where you find the tool name, toolbox alias, and the parameter order and type.
  • Code sample—Currently, only Python code is used in samples.
  • Environments—List of geoprocessing environment settings that affect the tool's execution.
  • Related topics—Contains links to other relevant topics. One standard link is to the toolset overview page that links to the toolbox overview page. These overview pages can be helpful in understanding what other tools are available and higher-level concepts about the tools in the toolset or toolbox.
  • Licensing information.
For more information about finding and reading a tool's reference page, see A quick tour of geoprocessing tool references.
Caution—Multiple tools can have the same name as long as they are located in different toolboxes. For example, there are three tools named Clip—one in the Analysis toolbox for clipping features, one in the Data Management toolbox for clipping rasters, and one in the Coverage toolbox for clipping coverages. A quick scan of the tool reference page should be enough to determine if you have the correct page opened.

Buffer analysis example

As an example, suppose you want to execute the Buffer tool in .NET. After opening the tool reference page and reading the summary and usage notes, scroll down to the Syntax section. The first thing you'll see is the tool signature. From this signature, you know that the toolbox alias is "analysis." The first three parameters are required, and the remaining parameters are optional (enclosed in curly brackets {}).
See the following illustration that shows the Syntax section:
On the tool reference page, the syntax is followed by a description of each parameter, which includes the following:
  • Parameter name.
  • An explanation of the parameter. Some parameters show enumerators in their explanation.
  • Parameter data type.

Enumerators for Boolean and string parameters

All Boolean parameters and some string parameters have enumerators. Enumerators are simple keyword strings. For example, the line_side parameter for the Buffer tool has the following four enumerators: 
  • FULL
  • LEFT
  • RIGHT
  • OUTSIDE_ONLY
By convention, the first enumerator (FULL) is the default value, which means you do not need to pass any value if you keep the default value. However, if you need to pass a value for a following optional parameter, pass an empty string for it.

Scripting example

These are examples in the Python scripting language that provide information about how the tool is used.

Geoprocessing environments

This is a list of geoprocessing environments recognized by the tool. For more information about the use of environments, see A quick tour of geoprocessing environments. 

Licensing information

At ArcGIS 10 and later, the definitive source of license information is the tool reference page. Each tool reference page lists the licensing requirements at the bottom. For example, the tool reference page for Buffer (analysis) shows that the tool is licensed to run on all licensing levels ("Yes" next to the license level). The reference page for the Near (analysis) tool, however, shows it is available only at the ArcGIS for Desktop Advanced license level.
Tool licensing information for all tools within a toolbox is summarized in one topic at the toolbox level. The following links are to toolbox-level licensing topics:

Running a tool in .NET

In .NET, you run a geoprocessing tool by calling the geoprocessor's Execute method. At a minimum, you need the tool name, toolbox alias, parameters, and their types and values, all of which you can get from the tool reference page. For more information and examples, see How to run a geoprocessing tool and Executing tools.