Setting 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 tool's source code. Your tool reads these values and proceeds with its work.

To learn more about parameters, see Understanding script tool parameters.

Script tool parameters can be set when using the Add Script wizard. You can also add, delete, and modify script tool parameters from a tool's Properties dialog box. To access script tool properties, right-click the tool, click Properties, then click the Parameters tab.

Whether you are setting parameters in the Add Script wizard or in the Properties dialog box, the procedures (as described here) are the same.

To add a new parameter, click the first empty cell in the Display Name column and type the name of the parameter. This is the name that will be displayed on the tool dialog box and can contain spaces. For Python syntax, the parameter name will be the display name with spaces replaced by underscores (_).

Creating a new parameter

After entering the display name of the parameter, choose a data type for the parameter by clicking in the Data Type cell, as shown below.

Defining a parameter's data type

Each parameter has additional properties you can set, as shown below.

Parameter properties

Property

Description

Type

Can be Required, Optional, or Derived. Derived means that the user of your tool does not enter a value for the parameter. Derived types are always output parameters.

Direction

Can be Input or Output. If the parameter Type is Derived, direction is always equal to Output.

Multivalue

Multivalue is Yes if you want a list of values, No if you want a single value.

Default or Schema

The default value for the parameter. When the parameter data type is either feature set or record set, Default is replaced with Schema.

Environment

If the default value for the parameter is to come from an environment setting, this property contains the name of the environment setting.

Filter

If you want only certain datasets or values to be entered for a parameter, you can specify a filter. There are six types of filters, and the type of filter you can choose depends on the data type of the parameter.

Obtained from

This property applies to derived output parameters and input parameter data types. For derived output parameters, Obtained from can be set to the parameter containing the definition of the output. For input parameters, Obtained from is set to the parameter containing the information needed for input.

Symbology

This property applies only to output parameters. The value is the location of a layer file (.lyr) that contains the symbology for displaying the output.

Parameter properties

Type

There are three choices for Type:

NoteNote:

If your script tool has derived output, you need to set the value of the derived output parameter in your script using the SetParameterAsText() function.

All tools should have outputs

All script tools should have output parameters so that they can be used in ModelBuilder. The fundamental idea of ModelBuilder is to connect the output of tools to inputs of other tools, and if your script tool doesn't have an output parameter, it isn't very useful in ModelBuilder. At the very least, you can output a Boolean containing true if the tool completed successfully, and false otherwise.

Derived output that modifies an input parameter

The illustration below shows a hypothetical script tool, Update Field Values, used in ModelBuilder. (For purposes of discussion, Update Field Values is used by an organization to examine the contents of a set of known text fields and corrects misspelling and capitalization errors.) Update Field Values doesn't produce a new feature class, but it does update field values on the input feature class.

Tool with no output in ModelBuilder

The correct parameter definition of Update Field Values is shown in the illustration below, where Update Field Values has an output feature class parameter with Type set to Derived. Since the output is the same as the input for this tool, Obtained from is set to the input parameter. (Obtained from uses the name of the parameter, which is the display name with spaces replaced by underscores.)

Tool with derived output

Derived output that does not modify an input parameter

The illustration below shows a different tool, where the output is derived, but it is not obtained from any input parameter (Obtained from is left blank). In this scenario, the hypothetical Post Data to Repository tool copies the input feature class to a known workspace (the repository), then adds and populates a date/time field.

Output derived data that is not obtained from an input parameter

Setting the output value

In the model illustrated above, note that Copy Features tool is empty (white instead of yellow). This is because the Output features variable, although green, does not contain a value—the name and location of the output features are not known until the tool is executed. In this case, your script must specify the output value by using the ArcPy function SetParameterAsText(). The SetParameterAsText() function will set the value of an output parameter using either a text string or an object, such as a value table.

It is possible to provide a value for the output before the tool is executed by providing tool validation code.

Learn more about tool validation

Here is example code that uses SetParameterAsText(), based on the work performed by the Post Data to Repository script, described above.

# Post data to Repository - copies the input features to the
#  current repository, adding and populating a date
#  field
#

# Import system modules and arcpy
#
import sys
import string
import os
import arcpy

# Get the value of the input parameter
#
inFC = arcpy.GetParameterAsText(0)

# Create the pathname to the output feature class.
#  1) get the name of the feature class
#  2) remove any file extension, such as ".shp"
#     (we're copying to a geodatabase which doesn't
#      allow file extensions, like .shp)
#
fcName = os.path.basename(inFC) 
fcName = os.path.splitext(fcName)[0]
repository = "e:/repository/featuredata.gdb"
outFC = os.path.join(repository, fcName)

# Copy the input to the output, add the date field
#
arcpy.CopyFeatures_management(inFC, outFC)
arcpy.AddField_management(outFC, "PostDate", "DATE")

# Create a locale-specific string containing the current date 
#  and time, then calculate it into the PostDate field, adding
#  the required quotes around the postTime string.
#
import time
postTime = time.strftime("%x %X")
arcpy.AddMessage(postTime)
qPostTime = "\"" + postTime + "\""
arcpy.CalculateField_management(outFC, "PostDate", qPostTime)

# Set output parameter
#
arcpy.SetParameterAsText(1, outFC)

Output values instead of data

The examples above show outputting derived datasets. Some tools, however, output values instead of datasets, such as the Get Count tool, which outputs a Long data type containing the number of rows in a table. Outputting values instead of datasets is common. You may have scripts of your own that perform analysis on several related datasets and output nothing more than a couple of numbers, or a pass/fail Boolean value.

Output parameters containing value data types (such as Long or Boolean) are always Derived rather than Required.

Direction

This property defines whether the parameter is an input to the tool or an output of the tool.

If the parameter type is Derived, then the parameter direction will be automatically set to output.

Multivalue

If you want a parameter to be able to handle a list of values rather than just one value, set the MultiValue property to Yes.

In tool dialog boxes, there are two different user interface controls that are used for multivalues, as illustrated below.

Both types of multivalue controls are illustrated below.

Multivalue controls

Mulitvalues are passed to your script as semicolon-delimited strings. Drawing from the above illustration, if the user selected all road types, the parameter value would be Interstates;Primary roads;Secondary roads. To break apart a delimited string, use the Python split() method, as shown in the code example below.

roadTypes = arcpy.GetParameterAsText(0)
roadTypeList = roadTypes.split(";")

# Process each road type
#
for rType in roadTypeList:
  # rType contains an individual road type string (ex: "Interstates")
  # 
  arcpy.AddMessage("Processing: " + rType)

Default

The default value will be the contents of the parameter when the script's tool dialog box is opened. It is also the value that will be used if a # is entered for the parameter in scripting. If you don't specify a value for the Default property, the parameter value will be blank when the script's dialog box is opened. If you specify a value for this property, the Environment property will become disabled. To enable the Environment property, clear the Default property.

Schema

When the input parameter data type is a Feature Set or Record Set, you must specify the location of a schema that defines the fields and geometry type of the features to be entered. A schema is either a feature class, table, or layer file (.lyr).

About Feature and Record Sets

The Feature and Record Set data types allow interactive input of data. A Feature Set allows the user of your script to interactively create features in ArcMap by clicking on the map. The Record Set allows your user to interactively create rows in a simple table grid.

Feature and Record Sets

For more information on Feature and Record Sets, follow the links below.

Topic

Description

FeatureSets and RecordSets

This topic describes how to use FeatureSet and RecordSet objects in Python.

Using the interactive feature and record input controls

This topic describes how to use the Feature and Record Set controls.

Topics about Feature and Record Sets

Environment

You can set the default value for a parameter to the value of an environment setting by right-clicking the cell next to Environment and choosing the name of the environment setting. Once you choose an environment setting, the Default property will be ignored. To use the Default property instead of the Environment property, clear the Environment property by selecting the blank entry in the drop-down list.

Choosing an environment setting

Filter

If you want only certain values or dataset types to be entered for a parameter, you can specify a filter. Click the cell next to Filter and choose the appropriate filter from the drop-down list. A dialog box opens, and you specify the values for the filter. There are six types of filters, and the type of filter you can choose depends on the data type of the parameter.

Filter type

Values

Value List

A list of string or numeric values. Used with String, Long, Double, and Boolean parameter data types.

Range

A minimum and maximum value. Used with Long and Double data types.

Feature Class

A list of allowable feature class types: "Point", "Multipoint", "Polyline", "Polygon", "MultiPatch", "Sphere", "Annotation", and "Dimension". More than one value can be supplied to the filter.

File

A list of file suffixes, for example, "txt; e00; ditamap".

Field

A list of allowable field types: "Short", "Long", "Single", "Double", "Text", "Date", "OID", "Geometry", "Blob", "Raster", "GUID", "GlobalID", and "XML". More than one value can be supplied to the filter.

Workspace

A list of allowable workspace types: "File System", "Local Database", or "Remote Database". More than one value can be supplied.

Filter type and values

Usually, there is only one filter type you can choose. Only Long and Double have two choices: Value List and Range.

You can also set filters programmatically by providing validation logic.

Learn more about validation logic

Value List

The Value List filter is very useful for providing a set of keywords. Many tools have a predefined set of keywords, such as the field type parameter found in Add Field, or the JoinAttributes parameter of many of the tools in the Overlay toolset.

A Value List filter can be used for Long and Double data types. For these types, you enter the allowable numeric values.

If you want the user to be able to choose more than one of the values, set the multivalue Multivalue property to Yes.

A Value List can be used for Boolean data types. For Boolean data types, the Value List contains two values: the true value and false value. The true value is always the first value in the list. These values are used in the command line for specifying the value. See, for example, Add Field and the {NULLABLE | NON_NULLABLE} keywords used for the IsNullable property.

Range

A Long or Double parameter can have a Range filter. Range filters have two values: the minimum and maximum. The first value in the list is the minimum. The range is inclusive, meaning the minimum and maximum are valid choices.

Feature Class

For this filter, choose one or more filter values. Input feature classes will be checked against the filter values. So, for example, if you select only Points as the filter value, the user can only enter point feature classes as the parameter value.

File

The file filter contains a list of file suffixes that a file may have, such as txt (simple text file) and csv (comma-separated value). You can supply any text for a suffix—it doesn't have to be a suffix that ArcGIS recognizes. The suffix can be of any length and does not include the dot.

Specifying a file filter

Field

The field filter defines the permissible field types: "Short", "Long", "Single", "Double", "Text", "Date", "OID", "Geometry", "Blob", "Raster", "GUID", "GlobalID", and "XML". More than one value can be supplied to the filter.

Workspace

The workspace filter specifies the types of input workspaces that are permissible. There are three values:

  • File System

    A system folder, used to store shapefiles, coverages, INFO tables, and grids

  • Local Database

    A personal or file geodatabase

  • Remote Database

    An ArcSDE database connection

Obtained from

The Obtained from property has two purposes:

Obtained from for a field data type

You can only set Obtained from for certain input parameters, as shown in the table below.

Input data type

Obtained from data type

Description

Field or SQL Expression

Table

The table containing the fields

INFO Item or INFO Expression

INFO Table

The INFO table containing the items

Coverage Feature Class

Coverage

The coverage containing features

Area Units or Linear Units

GeoDataset

A geographic dataset used to determine the default units

Coordinate System

Workspace

A workspace used to determine the default coordinate system

Network Analyst Hierarchy Settings

Network Dataset

The network dataset containing hierarchy information

Geostatistical Value Table

Geostatistical Layer

The analysis layer containing tables

Obtained from data types

Symbology

If the output of your tool is a feature set, raster, TIN, or ArcGIS Network Analyst extension layer, you can specify the location of a layer file (.lyr) in the Symbology property. When your tool is run from ArcMap, ArcGlobe, or ArcScene, and Add results of geoprocessing operations to the display is enabled, the output is added to the display and drawn using the symbology defined in the symbology layer file.

CautionCaution:

The layer file is read each time the tool is run. If the layer file cannot be found (because it was moved or deleted), default symbology will be used.

Related Topics

3/25/2013