Show Navigation | Hide Navigation
You are here:
Geoprocessing > Automating your work with scripts > Creating script tools

Setting script tool parameters
Release 9.3
Last modified June 3, 2010		 E-mail This Topic Printable Version Give Us Feedback

Print all topics in : "Creating script tools"


Related Topics

Note: This topic was updated for 9.3.1.

Script tool parameters are created and modified



To access script tool properties, right-click the tool, click Properties, then click the Parameters tab.

To add a new parameter, click the first empty cell in the Display Name column and enter the name of the parameter. This is the name that will be displayed on the tool dialog and can contain spaces. For command line, 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 datatype

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 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.


Type


There are three choices for Type:



The remainder of this section discusses the use of Derived output parameters.

There are four reasons for a derived output parameter, as follows:


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.

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 correct spelling 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 illustration above, note that the Output features variable is empty (white instead of green). This is because the name and location of the output features is not known until the tool is executed. In this case, your script must specify the output value by using the geoprocessing object method SetParameterAsText(). The SetParameterAsText() method will set the value of an output parameter using either an object, such as a value table, or a text string.

Methods for parameters

Learn more about the CopyParameter method
Learn more about the GetParameterAsText method
Learn more about the SetParameterAsText method

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 create the geoprocessing object
#
import sys, string, os, arcgisscripting
gp = arcgisscripting.create(9.3)

# Get the value of the input parameter
#
inFC = gp.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 that doesn't
#      allow file extensions, like .shp)
#
fcName = os.path.basename(inFC) 
fcName = os.path.splitext(fcName)[0]
repository = r"E:\repository\featuredata.gdb"
outFC = os.path.join(repository, fcName)

# Copy the input to the output, add the date field
#
gp.CopyFeatures_management(inFC, outFC)
gp.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")
gp.AddMessage(postTime)
qPostTime = "\"" + postTime + "\""
gp.CalculateField_management(outFC, "PostDate", qPostTime)

# Set output parameter
#
gp.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 not uncommon. 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.

For a good example of outputting values, follow the links below. They lead to a topic that discusses outputting two Boolean values in a script tool for use in ModelBuilder.
View example of outputting two Boolean values
View the code that outputs two Boolean values


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 dialogs, there are two different user interface controls that are used for mulitvalues, as illustrated below.



Both types of multivalue controls are illustrated below.

Multivalue controls

Mulitvalues are passed to your script as a semicolon-delimited string. 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 = gp.GetParameterAsText(0)
roadTypeList = roadTypes.split(";")

# Process each road type
#
for rType in roadTypeList:
  # rType contains an individual road type string (ex: "Interstates")
  # 
  gp.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 the command line. 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, remove the Default property.


Schema



When the input parameter data type is a Feature Set or Record Set, you can 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
Feature Sets and Record Sets This topic describes how to create and use Feature and Record Sets in ModelBuilder. Although this is a ModelBuilder topic, all the information applies to script tools as well.
Using the interactive feature and record input controls 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 out the Environment property by selecting the blank entry in the drop-down list.

Choosing an environment setting


Filter



If you want only certain dataset types or values 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, Dimension. More than one value can be supplied to the filter.
File A list of file suffixes. Example: "txt; e00; ditamap".
Field A list of allowable field types: Short, Long, Single, Double, Text, Date, OID, Geometry, Blob, Raster, GUID, GlobalID, 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 Doubles 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 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 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 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, 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:




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


Symbology



If the output of your tool is a feature set, raster, TIN, or 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.

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



Follow the link below to learn more setting symbology. This link leads you to a ModelBuilder topic. Although the context of the topic is ModelBuilder, the same concepts apply to script parameter symbology.

Learn more about output symbology

Please visit the Feedback page to comment or give suggestions on ArcGIS Desktop Help.
Copyright © Environmental Systems Research Institute, Inc.