Creating the geoprocessor object
Release 9.3 Last modified June 3, 2010	Print all topics in : "Accessing tools within a geoprocessing script"

Note: This topic was updated for 9.3.1.

ArcGIS 9 introduced a scripting object, GPDispatch, that could be used in scripting languages such as Python, VBScript, and JScript. A common object model based on objects supporting IDispatch was created to provide a uniform scripting experience. However, this meant none of the unique capabilities and strengths of a particular scripting language were utilized by the geoprocessing object.

ArcGIS 9.2 introduced native Python support for geoprocessing scripting. Instead of relying on Python's win32com module to create the geoprocessor, the geoprocessor could be created using a new native arcgisscripting module. This change provides the flexibility to use Python geoprocessing scripts on a variety of platforms, instead of being limited to Windows operating systems. The arcgisscripting module also provides some IntelliSense capabilities. Server tasks can only be performed using the arcgisscripting module.

Over the past several releases, users have overwhelmingly selected Python as the scripting language of choice. At 9.3, a further enhanced native Python geoprocessing object was introduced to accept and return common Python structures such as lists and Booleans. This creates an experience for geoprocessing that is richer and more consistent with standard Python use. The 9.3 geoprocessor can be created using an optional version argument with the create method on the arcgisscripting module. The behavior of existing scripts that create the geoprocessor without setting the version will be unchanged.

All geoprocessing Python scripts can import either the arcgisscripting or win32com modules to instantiate the geoprocessor object. The examples below illustrate the difference. The arcgisscripting module is built closely upon Python 2.5.1 and requires this version to create the geoprocessor. Scripts can be run on different versions of Python if they use win32com to create the geoprocessor.

9.3-version geoprocessor

# Create the geoprocessor using the arcgisscripting module using 
#   9.3 for the optional version argument
#
import arcgisscripting
gp = arcgisscripting.create(9.3)

gp.workspace = "c:/Tongass"
gp.clip_analysis("standb4", "clipcov", "standb4_clip", "POLY", "1.25")

# Create the geoprocessor using the arcgisscripting module
#
import arcgisscripting
gp = arcgisscripting.create()

gp.workspace = "c:/Tongass"
gp.clip_analysis("standb4", "clipcov", "standb4_clip", "POLY", "1.25")

# Create the geoprocessor using the win3com.client module
#
import win32com.client
gp = win32com.client.Dispatch("esriGeoprocessing.GpDispatch.1")

gp.workspace = "c:/Tongass"
gp.clip_analysis("standb4", "clipcov", "standb4_clip", "POLY", "1.25")

• Analysis Tools toolbox
  
• Conversion Tools toolbox
  
• Data Management Tools toolbox
  
• Cartography Tools toolbox
  
• Geocoding Tools toolbox
  
• Linear Referencing Tools toolbox
  
• Multidimension Tools toolbox
  
• Spatial Statistics Tools toolbox
  
• Samples toolbox
  

Python lists versus enumerations

For Python scripts with a geoprocessor version of 9.3 or greater, list methods (e.g., ListFeatureClasses, ListDatasets) return a true Python list object. With a 9.2-version geoprocessor, these methods return an enumeration object. With a 9.3-version geoprocessor, the following methods return a Python list: ListTools, ListEnvironments, ListToolboxes, ListFeatureClasses, ListDatasets, ListTables, ListRasters, and ListWorkspaces.

A Python list provides the opportunity to use and manage the results of a list function in a variety of ways. A list is a versatile data type and provides a number of methods (append, count, extend, index, insert, pop, remove, reverse, and sort) that can be used to manipulate and extract information.

The following examples contrast the differences between using ListFeatureClasses with a 9.3-version and 9.2-version geoprocessor.

import arcgisscripting 

# Use 9.3 for the optional version

#    argument

#

gp = arcgisscripting.create(9.3)

gp.Workspace = "c:/data"

# List function returns a

# Python list

#

fcs = gp.ListFeatureClasses()

print fcs







# Step through a Python list 

#   using a while loop

#

for fc in fcs:

    print fc

import arcgisscripting





gp = arcgisscripting.create()

gp.Workspace = "c:/data"

# List function returns an

# enumeration

#

fcs = gp.ListFeatureClasses()

print fcs

# To get the next feature

#   class, you must use the

#   Next method

#

fc = fcs.Next()

# Step through an enumeration

#   using a for loop

#

while fc:

    print fc

    fc = fcs.Next()

import arcgisscripting

import types

# Use 9.3 for the optional version

#    argument

#

gp = arcgisscripting.create(9.3)

# AddField returns a result

#   object

#

result = gp.AddField(
    "c:/data/fc.shp", "flag")

# Use the result object's

#   GetOutput method to 

#   get a unicode

print result.GetOutput(0)



# The result object has a 

#   several other methods

#   and properties

# Print the last message

# Print the tool status

#

print result.GetMessage(

    result.MessageCount-1)

print result.Status 

# 4 indicates 'Succeeded'

import arcgisscripting

import types





gp = arcgisscripting.create()



# AddField returns a string

#

result = gp.AddField(
    "c:/data/fc.shp", "flag")





print result

import arcgisscripting

# Use 9.3 for the optional version

#    argument

#

gp = arcgisscripting.create(9.3)

fc = r"C:\geometry.gdb\fc"

# Create a describe object from 

#   a feature class

#

desc = gp.describe(fc)

# Get the extent property from 

#   the describe object

#

extent = desc.extent

# Extent returns an extent object

# Print some of the extent

#   properties (others include

#   MMin, MMax, ZMin, ZMax, 

#   Height, Depth

#

print ("XMin: %f") % extent.xmin

print ("YMin: %f") % extent.ymin

print ("XMax: %f") % extent.xmax

print ("YMax: %f") % extent.ymax

print ("Width: %f") % extent.width

# Return a point object for the 

#   lowerleft point of the extent

#   (lowerright, upperleft and 

#   upperright are also available)

#

lowerleftPoint = extent.lowerleft

# Print the x, y coordinates of

#   the lowerleft extent

print ("LowerLeft point X: %f") 
    % lowerleftPoint.x

print ("LowerLeft point Y: %f") 
    % lowerleftPoint.y

import arcgisscripting





gp = arcgisscripting.create()

fc = r"C:\geometry.gdb\fc"

# Create a describe object from 

#   a feature class

#

desc = gp.describe(fc)

# Get the extent property from 

#   the describe object

#

extent = desc.extent

# Extent returns a space-

#   delimited string of coordinates

#

print ("Extent: %s") % desc.extent

import arcgisscripting

# Use 9.3 for the optional version

#    argument

#

gp = arcgisscripting.create(9.3)

gp.OverWriteOutput = True

# Overwriteoutput returns a

#    Boolean value

#

print gp.OverWriteOutput

import arcgisscripting





gp = arcgisscripting.create()

gp.OverWriteOutput = True

# Overwriteoutput returns a

#    1 or 0

#

print gp.OverWriteOutput

# ASCII string
#
fc = 'river.shp'

# Unicode string
#
fc = u'river.shp'

Although Python is the most commonly used scripting language for geoprocessing, geoprocessing scripts can also be created in a number of other script languages such as Perl, VBScript, and JScript. The following examples demonstrate how to create the geoprocessor, set the workspace environment, and run the Clip tool in different languages.

Perl example

use Win32::OLE;
my $gp = Win32::OLE->new('esriGeoprocessing.GPDispatch.1');
$gp->workspace = "c:/Tongass";
$gp->clip ("standb4", "clipcov", "standb4_clip", "POLY", "1.25");

Set gp = WScript.CreateObject("esriGeoprocessing.GPDispatch.1")
gp.workspace = "c:/Tongass"
gp.clip "standb4", "clipcov", "standb4_clip", "POLY", "1.25"

var gp = WScript.CreateObject("esriGeoprocessing.GPDispatch.1");
gp.workspace = "c:/Tongass";
gp.clip ("standb4", "clipcov", "standb4_clip", "POLY", "1.25");