Skip to content

TSTool / Command / For

Overview

The For command iterates through a block of commands between For and matching EndFor commands. A processor property is set to the value of the iteration property and can be used by other commands that support properties, using the ${Property} notation. For commands can iterate over:

  • a list of supplied values (see the List parameter)
  • a sequence of integers or decimal numbers specified with start (SequenceStart parameter), end (SequenceEnd parameter), and increment (SequenceIncrement parameter)
  • values from a table column (see TableID, TableColumn, and TablePropertyMap parameters)
  • a list of time series and corresponding properties (see TSList, TSID, and EnsembleID parameters)

For commands can be nested. Status messages for run mode are accumulated in each command (this update is occurring over time – status messages for some commands may be cleared out each iteration). A limitation of using For with properties is that the command when edited may show time series identifiers and other command parameters as ${Property} values, rather than actual data, because the values get expanded at run-time. This provides increased processing power but errors may not be evident until commands run.

See also the Break and Continue commands, which can be used with If command to skip some commands in a For loop.

Command Editor

The following dialog is used to edit the command and illustrates the command syntax when iterating over a list.

For_List

For Command Editor Illustrating Using a List for Iteration Values (see also the full-size image)

The following dialog is used to edit the command and illustrates the command syntax when iterating over a sequence of numbers.

For_Sequence

For Command Editor Illustrating Using a Sequence of Integers for Iteration Values (see also the full-size image)

The following dialog is used to edit the command and illustrates the command syntax when iterating over table column values.

For_Table

For Command Editor Illustrating Using a Table for Iteration Values (see also the full-size image)

The following dialog is used to edit the command and illustrates the command syntax when iterating over a list of time series.

For_TSList

For Command Editor Illustrating Using a List of Time Series (see also the full-size image)

Command Syntax

The command syntax is as follows. One of the list, sequence, or table parameters must be specified.

For(Parameter="Value",...)

Command Parameters

Iterator Method Parameter                            Description Default                 
All Name
required		 The name of the for loop, which will be matched with the name of an EndFor command to indicate the block of commands in the loop. None - must be specified.
All IteratorProperty The processor property that will be set to the iterator property. The object type will depend on that used to provide the iteration property list. For example, if a sequence of integers is being iterated, the property will contain an integer. Same as Name.
List List A list of comma-separated values to be used as variables for the iteration. Can use ${Property} syntax. No default if list is used – must specify a list of values.
Sequence SequenceStart Starting value when a sequence is specified for iteration, an integer or decimal number. No default if sequence is used.
Sequence SequenceEnd Ending value when a sequence is specified for iteration, an integer or decimal number. No default if sequence is used.
Sequence SequenceIncrement Increment for sequence iterator. 1 or 1.0 depending on inferred type for SequenceStart.
Table TableID The table identifier, when specifying the iterator as a column from a table. Can be specified with processor ${Property}. No default if table is used - required if table is used.
Table TableColumn The table column name, when specifying the iterator as a column from a table. No default if table is used - required if table is used.
Table TablePropertyMap Specify the names of column names and corresponding processor property names to set. This allows other commands to access the values of those properties using ${Property} notation. Specify using format:
ColumnName1:PropertyName1,
ColumnName2:PropertyName2		 No default if table is used - required if table is used. Only the iterator column value will be set as a property using IteratorProperty.
TS List TSList Indicates the list of time series to be processed, one of:
  • AllMatchingTSID – all time series that match the TSID (single TSID or TSID with wildcards) will be processed.
  • AllTS – all time series before the command.
  • EnsembleID – all time series in the ensemble will be processed (see the EnsembleID parameter).
  • FirstMatchingTSID – the first time series that matches the TSID (single TSID or TSID with wildcards) will be processed.
  • LastMatchingTSID – the last time series that matches the TSID (single TSID or TSID with wildcards) will be processed.
  • SelectedTS – the time series are those selected with the SelectTimeSeries command.
 If iterating time series, must be specified.
TS List TSID The time series identifier or alias for the time series to be processed, using the * wildcard character to match multiple time series. Can be specified using ${Property}. Required if TSList=*TSID
TS List EnsembleID The ensemble to be processed, if processing an ensemble. Can be specified using ${Property}. Required if TSList=*EnsembleID
TS List TimeSeriesPropertyMap Map of time series property names to processor processor property names, which allows time series properties to be made visible for processing. No additional time series properties other than iterator property are set as processor properties.

Examples

See the automated tests.

Example to process data for a list of counties

The following example illustrates a simple For and EndFor usage. In this example the StationID column in the input table is used to provide the list of values to iterate over. The following input table is a delimited file but could come from another source:

# Test table data for For() command tests
"Count","Val","StationID","Basin"
1,1.0,Station1,Basin1
2,2.0,Station2,Basin2
3,3.0,Station3,Basin3
4,4.0,Station4,Basin4

The following command file reads the above input table, iterates over the StationID column, and creates a simple output file:

ReadTableFromDelimitedFile(TableID="Table1",InputFile="Data\testtable.csv")
RemoveFile(InputFile="Results/Test_For_TableString_out.txt",IfNotFound=Ignore)
For(Name="TestFor",TableID="Table1",TableColumn="StationID")
WritePropertiesToFile(OutputFile="Results/Test_For_TableString_out.txt",
    IncludeProperty="TestFor",WriteMode=Append,FileFormat=NameTypeValue)
EndFor(Name="TestFor")

The resulting output file is as follows:

TestFor="Station1"
TestFor="Station2"
TestFor="Station3"
TestFor="Station4"

Troubleshooting

See Also