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 (_).
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.
Each parameter has additional properties you can set, as shown below.
| Property | Description |
|---|---|
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. | |
Can be Input or Output. If the parameter Type is Derived, direction is always equal to Output. | |
Multivalue is Yes if you want a list of values and No if you want a single value. | |
The default value for the parameter. When the parameter data type is either feature set or record set, Default is replaced with Schema. | |
If the default value for the parameter is to come from an environment setting, this property contains the name of the environment setting. | |
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. | |
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. | |
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. |
Type
There are three choices for Type:
- A Required parameter requires an input value from the user. The tool cannot be executed until the user supplies a value.
- An Optional parameter does not require a value from the user.
- A Derived parameter is only for output parameters (see Direction below). A derived output parameter does not show on the tool dialog box.
There are five uses for a derived output parameter, as follows:
- The output is the same as the input, such as Calculate Field. Calculate Field changes the values of a particular field on the input table—it doesn't create a new table or modify the schema of the input. Other tools whose output is the same as the input can be found in the Editing toolbox.
- The tool modifies the schema of the input, such as Add Field. Add Field adds a field to the input table—it doesn't create a new output table.
- The tool creates output using information in other parameters, such as the Create Feature Class tool. With the Create Feature Class tool, you specify the workspace and the name of the new feature class, and the feature class is created for you.
- The tool outputs a scalar value as opposed to a dataset. Get Count, for example, outputs a long integer (the number of records). Whenever a tool outputs a scalar value, the output is Derived.
- The tool will create data in a known location. For example, you may have a script that updates an existing table in a known workspace. The user doesn't need to provide this table in the dialog box or in scripting.
All tools should have outputs
All script tools should have output parameters so 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.
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.)
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.
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.
- Learn more about the CopyParameter function
- Learn more about the GetParameterAsText function
- Learn more about the SetParameterAsText function
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.
- A list of check boxes is used for fields and for strings, longs, and doubles if they contain a ValueList filter.
- All other data types display the multivalue parameter control.
Both types of multivalue controls are illustrated below.
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.
For more information on Feature and Record Sets, follow the links below.
| Topic | Description |
|---|---|
This topic describes how to use FeatureSet and RecordSet objects in Python. | |
This topic describes how to use the Feature and Record Set controls. |
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.
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. |
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 with Python by customizing a script tool's ToolValidator class.
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.
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:
- For a derived output parameter, Obtained from is set to the input parameter that will be modified by the tool. For more information on derived data and Obtained from, see the discussion of the Type property above.
- For input parameters, Obtained from contains the name of other parameters used by the data type. For example, for an input field data type, Obtained from is set to the name of the table parameter containing the fields, as illustrated below.
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 |
Symbology
If the output of your tool is a feature set, raster, TIN, or ArcGIS Network Analyst 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.