skip to main content
Control File
The control file is an ASCII file which the user provides. The purpose of the control file is as follows:
• Map between slots on the Workspace and data files. In the case of an input DMI, data is imported from the data files to the slots; in the case of an output DMI, data is exported from the slots to the data files.
• Provide information about the data files.
Each control file entry contains three pieces of information:
• An object.slot specification.
• One or more file names listed as file = name
• Optional keyword = value pairs.
The control file format is:
object.slot: file=name keyword=value keyword=value ...
If a file name contains spaces then it must be enclosed in double quotations marks (“), for example:
object.slot: file=”file name” keyword=value keyword=value ...
The DMI must also be configured to allow spaces in file paths; see Allow Spaces in File Paths for details.
Object.Slot Specifications
The object.slot specifications indicate which slots will import from or export to data files. There are four ways of specifying the object:
• <object name> - A specific object name, for example., “Blue Lake,” which matches the object with that name. Aggregate object elements are specified as <aggregate name>:<element name>.
• <object type> - An object type, for example, “LevelPowerReservoir,” which matches all objects of that type.
• <sub-basin name> - A sub-basin name, which matches all objects in the sub-basin.
• * - A wild card which matches all objects of all types.
There are three ways of specifying the slot:
• <slot name> - A specific slot name, for example, “Inflow,” which matches the slot with that name.
• <slot type> - A slot type, for example, “SeriesSlot,” which matches all slots of that type.
• dispatch - Any dispatch slots.
There are two ways of specifying a column within multi-column slots:
• <column name> - A specific column name, which matches one of the columns in the selected slot.
• no name - If no name is given, the DMI defaults to the first column.
An account or supply can be specified as follows:
• <object name>^<account name>
• <supply name>.Supply - the “.Supply” portion of the string is necessary to tell RiverWare that this is a supply in the accounting system and not a slot in the physical system. If a DMI is used to bring in values, it should be setting supplies in the accounting system rather than accounting slots. See Setting Slots Versus Setting Supplies in Accounting for details.
Also, the slots in a Slot Set can be specified using the SlotSet keyword, as follows. See Slot Sets in User Interface for details.
SlotSet.<slot set name>
For example, SlotSet.Reservoir Inflows would expand to all of the slots in the Reservoir Inflows set.
The slot specifications described above are fully expanded when RiverWare writes the Meta Control File. (See Meta Control File for more information.)
The above slot specifications lead to many ways of specifying the object.slot pairs, as follows:
<object name>.<slot name>.<column name>
<object name>.<slot name>
<object name>.<slot type>.<column name>
<object name>.<slot type>
<object name>.dispatch.<column name>
<object name>.dispatch
<object type>.<slot name>.<column name>
<object type>.<slot name>
<object type>.<slot type>.<column name>
<object type>.<slot type>
<object type>.dispatch.<column name>
<object type>.dispatch
<sub-basin name>.<slot name>.<column name>
<sub-basin name>.<slot name>
<sub-basin name>.<slot type>.<column name>
<sub-basin name>.<slot type>
<sub-basin name>.dispatch.<column name>
<sub-basin name>.dispatch
*.<slot name>.<column name>
*.<slot name>
*.<slot type>.<column name>
*.<slot type>
*.dispatch.<column name>
*.dispatch
<object name>^<account name>
<supply name>.Supply
SlotSet.<Slot Set Name>
These pairs are listed from most exact to least exact. It is possible that more than one control file entry will select a specific object.slot pair in the Workspace. In this case, the more exact entry will always take precedence. For example, in the control file:
# All Confluence objects, Inflow1 slot.
Confluence.Inflow1: file=~/%o.inflow1.dat
# Confluence01 object, Inflow1 slot.
Confluence01.Inflow1: file=~/confluence01.inflow1.dat
Both entries will select Confluence01's Inflow1 slot (the first through an object type, the second through an object name). The more exact entry, the second entry, will take precedence.
There are two other concepts this example introduces: the control file may contain comments (lines beginning with #) and the file name may contain special characters (~ and %), described below.
Finally, note that object and slot names and types must be specified exactly as they appear in the user interface, including case and whitespace.
File Name and Directory Specification
The file name indicates from which data files the object.slots will be imported or to which data files the objects.slots will be exported. The file name may be either relative (beginning with ~/) or absolute (beginning with a drive letter, such as C:/). If the file name is relative, then it is relative to the DMI's working directory. The DMI's working directory is where it creates its temporary files. If the RIVERWARE_DMI_DIR environment variable is set, the DMI's working directory is $RIVERWARE_DMI_DIR/dmi_name; otherwise, the DMI's working directory is /tmp/dmi_name. In both cases, dmi_name is the name that appears in the DMI Selector list.
The file name may contain the following directives (currently, it may contain at most one of each):
• %o - The %o is replaced with the object name. These are useful when using symbolic references to object in the file specifications.
• %s - The %s is replaced with the slot name. These are useful when using symbolic references to slots in the file specifications.
• %t - The %t is replaced with the current MRM trace number. If there is no trace number because the DMI is not executed as part of MRM, a trace of 1 is assumed.
• %tempdir - The %tempdir is replaced by a guaranteed unique temporary directory as described below.
Note:  Because dmi names, object names and slot names are mapped to directory and file names, characters which are not valid in directory and file names (currently all characters other than A-Za-z0-9/_.) are replaced with _ when the directory or file name is created.
These symbolic references are fully resolved when RiverWare writes the Meta Control File. (See Meta Control File for more information.)
Consider the following example:
The environment variable RIVERWARE_DMI_DIR is C:\RiverWareData
The DMI name is “Operations Inputs DMI”
The control file contains the following entry:
Reservoir.Inflow: file=~\%o%t.%s.dat
The file which the “Blue Lake.Inflow" object.slot for trace 23 for an MRM would import from or export to, as specified in the Meta Control File, would be:
C:\RiverWareData\Operations_Inputs_DMI\Blue_Lake23.Inflow.dat
The ~ has been replaced with the value of the working directory, RIVERWARE_DMI_DIR\<dmi name>, %o has been replaced with the object name, %t has been replaced with the trace number, and %s has been replaced with the slot name (with the spaces having been replaced with _).
Multiple files can be specified on a single control file line entry for input dmi’s. This enables the user to import data into a slot from two or more files. Use of the data_date file keyword allows the user to specify where in the series slot each file should be placed. The syntax for multiple files is
Object.Slot: file=name file=name
The data files are imported from left to right. If the import = resize is specified, the slot will grow to accommodate the data. Overlapping data is allowed but values will be overwritten by the later data files. If the incoming data does not overlap and there are gaps, any untouched values that existed on the slot will remain.
Another control file directive available is %tempdir, which is replaced by a guaranteed unique temporary directory. When the DMI is invoked RiverWare generates the directory name, makes the directory and passes the directory to the DMI executable via the RW_DMI_TEMPDIR environment variable. The executable should be able to recognize RW_DMI_TEMPDIR. After the DMI finishes RiverWare removes the directory. The directory name will be similar to the following:
b05741ad-2b57-4f82-8044-bda67606e4c9
Because RiverWare removes the directory you most likely won't see these directories, but if you kill RiverWare or RiverWare crashes a directory might be left behind, in which case you can safely remove it.
Time Range Specification
The time range of data that is imported or exported by a Control File-Executable DMI is controlled in the control files and possibly in the data file. If not specified, the default is to export/import the range of the slot. But if you want to limit the data that is imported or exported use one or more of the following options:
• For an output DMI, you can limit the output to only the run range using the “Limit Output to Run Range” check box described in Limit Output to Run Range. See also the note below.
• For an input DMI, specify the timestep of the data that should be imported in the data file using the data_date keyword. This specification is in the data file itself so it is on a per-slot basis. See the description of data_date in Data Files.
• For either an input or output DMI, specify the start_timestep and end_timestep in the control file for each slot specification. Both of these keywords allow you to also specify the timestep symbolically using RPL syntax. For example, the following are valid entries:
– start_timestep=“24:00 November Max DayOfMonth, 1996”
– end_timestep=“Start Month Start DayOfMonth, Start Year - 2 days”
– start_timestep=“Current Timestep” (Current timestep is only supported for rule executed DMIs as they know at which timestep the DMI is executing, see Executing DMIs From Blocks in RiverWare Policy Language (RPL).
– end_timestep=“24:00 3/1/2021”
See DATETIME in RiverWare Policy Language (RPL) for details on datetimes. Basically, any fully specified datetime can be used. No @ symbol is necessary but quotes are necessary when specifying datetimes that contain spaces.
When using these keywords on an input DMI, the data file does not have to have the same start_date and end_date as the control file. The data file should encompass the desired data. Otherwise a warning message will be issued, and no data will be imported. If the data file does not have a start_date keyword, the data will be imported starting with the first value in the data file imported to the start_timestep. Also, using the data_date keyword in the data file is possible. It is recommended to create data files that match the control file’s start_timestep and end_timestep for improved performance.
For an input DMI, the keyword end_timestep will not grow a slot. Use the import=resize to grow a slot to fit the imported data. (See import=<fixed>|<resize>.)
Note:  The time range of the slot after import will be based on the start_date and end_date keywords in the data file consistent with the description for import=<fixed>|<resize>. Data will be imported only for the range specified by the start_timestep and end_timestep in the control file, and any additional timesteps will contain NaN.
On an output DMI, if you specify start_timestep and end_timestep (a symbolic range) in the control file and Limit Output to Run Range in the DMI interface, the following applies: If the run range and symbolic range are disjoint, constrain the data transfer to the symbolic range. Otherwise, constrain the data transfer to the intersection of the run range and symbolic range.
Revised: 11/11/2026