Desktop Help 10.0 - Understanding script tool parameters

Almost all tools have parameters, and you set their values on the tool dialog box or within a script. When the tool is executed, the parameter values are sent to your script. Your script reads these values and proceeds with its work.

The illustration below shows a script tool dialog box with three parameters: an input workspace, a clip feature class, and an output workspace. All feature classes in the input workspace are clipped to the clip feature class (using the Clip tool) and written to the output workspace.

In the illustration above, once parameter values have been entered on the tool dialog box and the OK button is clicked, the script reads the values of the parameters using GetParameterAsText(), as follows:

# Import arcpy site-package
#
import arcpy
from arcpy import env

# Read the parameter values:
#  1: input workspace
#  2: input clip features
#  3: output workspace
#
inWorkspace   = arcpy.GetParameterAsText(0)
clipFeatures  = arcpy.GetParameterAsText(1)
outWorkspace  = arcpy.GetParameterAsText(2)
env.workspace = inWorkspace

Parameter order must match

The parameter order on the tool dialog box must match the parameter order in your script. If, for example, you change the Clip Features from parameter 2 to parameter 1 in the script tool, you must also change the parameter order in the script tool's properties.

sys.argv and arcpy.GetParameterAsText

There are two methods for reading parameters: sys.argv and the arcpy function GetParameterAsText(). Either approach can be used. The example above could be rewritten to use sys.argv:

# Read the parameter values:
#  1: input workspace
#  2: input clip features
#  3: output workspace
#
inWorkspace   = sys.argv[1]
clipFeatures  = sys.argv[2]
outWorkspace  = sys.argv[3]
env.workspace = inWorkspace

Note:

sys.argv has a limit of 1,024 characters for a single parameter. GetParameterAsText() has no character limit. For this reason alone, it is recommended that you use GetParameterAsText.

sys.argv is 1-based (the first parameter is 1) as opposed to GetParameterAsText(), which is 0-based (the first parameter is 0).

Legacy:

Prior to ArcGIS 9.2, stand-alone scripts (scripts executed from the operating system prompt) could only use sys.argv—GetParameterAsText() would only work for script tools. This limitation was removed at version 9.2. You may see code examples that use sys.argv. These examples were written before 9.2. At version 9.2 and higher, you can substitute GetParameterAsText() for sys.argv. Just be careful to decrease the parameter index: sys.argv[1] becomes GetParameterAsText(0).

Parameter data types

Every script tool parameter has an associated data type. When the script tool dialog box is opened, geoprocessing uses the data type to check the parameter value. For example, if you enter a feature class for a parameter with a workspace data type, geoprocessing generates an error (a red "X" on the dialog box), as shown below.

Geoprocessing generates an error when data types don't match

The data type is also used in browsing for data—only data that matches the parameter data type will be shown in the browse dialog box.

Another way to think about parameters and data types is that geoprocessing does not send values to your script that are of the incorrect data type. This is one distinct advantage to creating a script tool—the parameter value is checked against the parameter data type before the value is sent to your script.

4/14/2011