Running a geoprocessing tool


In this topic


About running a geoprocessing tool

Each geoprocessing tool has a fixed set of parameters that provide the tool with the necessary information for execution. Tools usually have input parameters that define the dataset or datasets that will typically be used to generate new output data. Parameters have the following important properties:
When a tool is used in a program, correctly set the parameter values so it can execute when the program is run. Each tool's documentation defines its parameters and properties. Once a valid set of parameter values are provided, the tool is ready to execute.
Parameters are specified as strings, objects, or native types for simple parameters. An example of a native type is the number of neighbors parameters on the CalculateDistanceBand tool. Strings are text values that uniquely identify a parameter value, such as a path to a dataset or a keyword.
Most tool parameters can be specified as a simple string. However, complex parameters such as a spatial reference, can be easier to specify with an object. In the following code example, the required parameters for the Buffer tool are defined. In this case, strings are used to define the input, output, and buffer distance properties of the Buffer tool so the call to the tool is easier to read.
Be aware that the syntax for specifying fields in query expressions is different for different data formats. The following are some of the most commonly encountered differences:

The Execute method uses null references instead of an ITrackCancel object. The ITrackCancel interface provides access to properties and methods that determine if a cancellation has been executed by the user, and allows developers to specify what actions constitute a cancellation. See the following code example:
[Java]
// Initialize the geoprocessor.
Geoprocessor GP = new Geoprocessor();
Buffer bufferTool = new Buffer("c:/data/usa.gdb/wind.shp", 
    "c:/data/usa.gdb/bufferedWind.shp", "distance");
GP.execute(bufferTool, null);

System toolbox names and namespaces

The following table shows the system toolbox names and associated namespaces:
Toolbox names
Namespaces
Analysis tools
com.esri.arcgis.geoprocessing.tools.analysistools
Conversion tools
com.esri.arcgis.geoprocessing.tools.conversiontools
Data Management tools
com.esri.arcgis.geoprocessing.tools.datamanagementtools
3D Analyst tools
com.esri.arcgis.geoprocessing.tools.analyst3dtools
Cartography tools
com.esri.arcgis.geoprocessing.tools.cartographytools
Coverage tools
com.esri.arcgis.geoprocessing.tools.coveragetools*
Geocoding tools
com.esri.arcgis.geoprocessing.tools.geocodingtools
Geostatistical Analyst tools
com.esri.arcgis.geoprocessing.tools.geostatisticalanalysttools
Linear Referencing tools
com.esri.arcgis.geoprocessing.tools.linearreferencingtools
Multidimension tools
com.esri.arcgis.geoprocessing.tools.multidimensiontools
Network Analyst tools
com.esri.arcgis.geoprocessing.tools.networkanalysttools
Spatial Analyst tools
com.esri.arcgis.geoprocessing.tools.spatialanalysttools
Spatial Statistics tools
com.esri.arcgis.geoprocessing.tools.spatialstatisticstools
Tracking Analyst tools
com.esri.arcgis.geoprocessing.tools.trackinganalysttools
* Only available with an ArcInfo Workstation install (not available on Linux).

Running custom geoprocessing tools

In addition to using the existing tools and toolboxes provided by ESRI, you can execute custom tools, such as model tools and script tools, which exist in custom toolboxes. Use Eclipse's integrated development environment (IDE) integration framework or the command line to generate a geoprocessing assembly that represents any custom toolbox. For more information, see Custom geoprocessing tools.

Executing a tool by name

It is not a prerequisite to generate a geoprocessing assembly to represent your custom toolbox. There is an alternative way to use the Execute method on the geoprocessor. The Execute method is overloaded and has additional parameters that allow you to execute a tool by specifying the tool name, parameters to the tool, and the ITrackCancel object.
The following code example shows executing the CalculateBestPath model tool located in the Bestpath toolbox:
[Java]
// Initialize the geoprocessor.
Geoprocessor GP = new Geoprocessor();
// Add the BestPath toolbox.
GP.addToolbox("c:/SanDiego/BestPath.tbx");
// Generate the array of parameters.
VarArray parameters = new VarArray();
parameters.add("c:/SanDiego/source.shp");
parameters.add("c:/SanDiego/destination.shp");
parameters.add("c:/SanDiego/bestpath.shp");
// Execute the model tool by name.
GP.execute("CalculateBestPath", parameters, null);

Executing geoprocessing server tools

With ArcGIS Desktop 9.2 and ArcGIS Engine 9.2, you can execute geoprocessing tools that have been published on an ArcGIS server. Server tools can be accessed and executed the same as custom tools. Add the custom toolbox by generating a geoprocessing toolbox assembly to represent the toolbox or by adding the custom toolbox using the AddToolbox method. 
Toolboxes can be published on a local area network (LAN) or published as a Web service on the Internet. Add the toolbox to access the geoprocessing server tools. The following code example adds toolboxes published on an ArcGIS server using the AddToolbox method:
[Java]
// Add the BestPath toolbox published on a LAN.
// Entered as server name;folder/toolbox.
gp.addToolbox(� � �flame7; SanDiego / BestPath ");
// Add the BestPath toolbox published as a geoprocessing Web service.
// Entered as Web service;folder/toolbox.
gp.addToolbox(� � �http:  //flame7:8399/arcgis/services;SanDiego/BestPath");
Toolboxes published on the server can contain tools that require you to enter the input parameter values by specifying the path to the data or contain tools that require the user to choose from a list of inputs referencing layers in a map document on the ArcGIS server. For more information about publishing geoprocessing tools to an ArcGIS server, see ArcGIS Server and Geoprocessing.
The following are examples of how to execute server tools:
[Java]
// Intialize the geoprocessor.
Geoprocessor gp = new GeoProcessor();
// Add the BestPath toolbox.
gp.addToolbox("http://flame7:8399/arcgis/services;GP/Bestpathtoolbox");
// Inputs reference layers in a map document on the server.
ArrayList parameters = new ArrayList();
parameters.add("source");
parameters.add("destination");
// Execute the server tool by reference.
IGeoProcessorResult result;
result = gp.execute("CalculateBestPath", parameters, null);
  • Execute a tool by value. The input parameters are shapefiles on a local drive. See the following code example:
[Java]
// Intialize the geoprocessor.
GeoProcessor gp = new GeoProcessor();
// Add the BestPath toolbox.
gp.addToolbox("http://flame7:8399/arcgis/services;GP/Bestpathtoolbox");
// Input values are data on a local drive.
ArrayList parameters = new ArrayList;
parameters.add("C:\\sandiego\\source.shp");
parameters.add("C:\\sandiego\\destination.shp");
// Execute the server tool by reference.
IGeoProcessorResult result;
result = gp.execute("CalculateBestPath", parameters, null);

Geoprocessing results

All geoprocessing tools generate results. The Execute method returns an IGeoProcessorResult object that manages the results. The result object is necessary for supporting geoprocessing with ArcGIS server. This result object will have the return value of a tool when executed; it will return the status of a job on the server and the result ID and provide the geoprocessing messages. The following code example executes a server tool and retrieves the status and messages:
[Java]
// Intialize the geoprocessor.
GeoProcessor gp = new GeoProcessor();
// Add the BestPath toolbox.
gp.addToolbox("http://flame7:8399/arcgis/services;GP/Bestpathtoolbox");
// Input values are data on a local drive.
ArrayList parameters = new ArrayList();
parameters.add("C:\\sandiego\\source.shp");
parameters.add("C:\\sandiego\\destination.shp");
// Execute the server tool by reference.
IGeoProcessorResult result;
result = gp.execute("CalculateBestPath", parameters, null);
while (result.getStatus() == esriJobStatus.esriJobSucceeded){
    for (int i = 0; i <= result.getMessageCount() - 1; i++){
        System.out.println(result.getMessageCount());
    }
}