RCL Commands Reference
Following are the RCL commands in alphabetical order.
Note: There are also RCL commands specific to RiverSMART. See the RiverSMART documentation for more information on these commands.
CloseWorkspace
CloseWorkspace
Clears the workspace.
Note: The CloseWorkspace command does not close RiverWare. RiverWare closes once the execution of the complete batch script is complete. Multiple OpenWorkspace and CloseWorkspace commands within the same script will be executed within a single RiverWare session.
ConfigureExcelDataset
ConfigureExcelDataset <Dataset Name> [workbook=...] [sheet=...] [workbookDir=...]
This command changes the workbook, the sheet, or the folder for an Excel Dataset used in a Database DMI.
• <Dataset Name> is an existing Excel dataset in the model. If the dataset does not exist in the model or is not an Excel dataset, the batch script will fail with an error message.
Caution: Only Excel datasets using the “Map with Header Text and Sheet Names” are supported by this event. Excel datasets using “Map by Spreadsheet Ranges” are not supported. See Slot Mapping—Header Text and Sheet Names Approach in Data Management Interface (DMI) for more information on this approach.
Caution: If the model is saved using the SaveWorkspace command, the modified Excel datasets will be saved.
Note: The workbook argument takes precedence over the workbookDir argument.
Example
ConfigureExcelDataset {My Excel Dataset} {workbook=C:/My Data/My Workbook.xlsx}
ConfigureExcelDataset {My Excel Dataset} {sheet=MyNewSheetName}
ConfigureExcelDataset {My Excel Dataset} {workbookDir=C:/Temp/MyTempFolder}
CreateSlotCache
CreateSlotCache
Creates a slot cache that contains the current values of all series slots on the workspace, in the range of the current controller. See Slot Cache in User Interface for a description of the cache.
Note: The slot cache is under development. Please contact riverware-support@colorado.edu for more information and the current status of this feature.
DeleteAllOptRestorePoints
DeleteAllOptRestorePoints
This command deletes all optimization restore points currently in existence. It does not have any arguments. See Restore Point in Optimization for a description of optimization restore points.
EnableInfoDiag
EnableInfoDiag <1|0>
Enable Informational Diagnostics in the diagnostics manager dialog. When the argument is 1, diagnostics will be enabled. When the argument is zero, then the diagnostics will be disabled.
ExecuteScript
ExecuteScript <Script Name>
Executes the specified script as defined in the Script Manager. See Script Management for details on RiverWare Script Management. The script name should be enclosed in curly braces {} if it contains embedded white space.
Example:
ExecuteScript {Run Operations Model}
ExportOptAnalysisAsCSV
ExportOptAnalysisAsCSV <file name> [<section name> true|false true|false]
Exports the Optimization Analysis information as a comma separated values file. The arguments are as follows:
• <file name> is the name of the file to write. If the file path contains embedded white space, it should be enclosed in curly braces {}.
• <section name> are the (optional) sections to export. Defaults to all sections. The section names are as follows and correspond to combinations of the Optimization sections; see Export as CSV in Optimization for details.
ConstraintAll
ConstraintNew
ConstraintPhysical
ConstraintPolicy
ConstraintPrior
None
SolutionAndPolicy
SolutionGoalSummary
SolutionInfo
SolutionSingle
VariableAll
VariableOther
VariableSlot
• The first optional true|false specifies whether to skip export of constraint and variable rows associated with fully satisfied constraints or solutions. Defaults to true, i.e., do not export these rows for fully satisfied solutions.
Note: If this argument is present, all previous arguments must also be present.
• The second optional true|false specifies whether to skip export of constraint and variable rows associated with the solution to the postponed problem, which is relevant only for runs in which a seed value was used to postpone one or more solutions. Defaults to true, i.e., do not export these rows for postponed problem solutions.
Note: If this argument is present, all previous arguments must also be present.
Example:
ExportOptAnalysisAsCSV {C:/MyOutputs/MyOptAnalysis.csv} {PolicyConstraints} {true}
ExportOptRestorePoint
ExportOptRestorePoint <restore point name> <file name>
Exports an optimization restore point to a file. See Restore Point in Optimization for information on optimization restore points. The arguments are as follows:
• <restore point name> is the name of the restore point to export. If the name contains embedded white space, it should be enclosed in curly braces {}.
• <file name> is the name of the file to export the restore point. If the name contains embedded white space, it should be enclosed in curly braces {}. Restore point files are generally given the .orp file extension.
The export command will overwrite any existing file with the same name.
Example:
ExportOptRestorePoint {Blue River Restore Pt} {C:/RWFiles/BlueRiverRestorePt.orp}
ExtractMrmData
ExtractMrmData {MRM configuration name} keyword=value ...
This command modifies the MRM configuration in terms of the RDF output options (See RDF Options in Solution Approaches) and then starts the process to write the data in the current model to the RDF output files.
GenerateMrmExcel
GenerateMrmExcel {MRM configuration name} keyword=value ...
This command modifies the MRM configuration in terms of the RDF output Excel options (See RDF Options in Solution Approaches) and then starts the process to convert the RDF file to an Excel workbook.
GetRunInfo
GetRunInfo <#RunInfo|#MRM <MRM configuration>>
[!InitDate] [!EndDate]
[!Duration] [!Step] [!Controller]
Prints single run information (#RunInfo) or multiple run information (#MRM) to standard output. If #MRM is specified, you also need to specify an MRM configuration <MRM configuration>.
• !InitDate prints the run’s initial date.
• !EndDate prints the run’s end date.
• !Duration prints the run’s duration.
• !Step prints the run’s timestep.
• !Controller prints the current controller.
If no parameters are specified, all information is printed.
Following are examples of the syntax:
GetRunInfo #RunInfo !InitDate
GetRunInfo #RunInfo !EndDate
GetSlot
GetSlot <Object.Slot> [<date time>]
Returns the series or scalar slot’s value, in user units, as a Tcl variable. Object.Slot should be enclosed in curly braces {} if it contains embedded white space.
• <date time> is only for series slots and must be enclosed in curly braces {}, as it contains embedded white space - for example, {05-15-2010 12:00}.
The command is used when writing batch mode scripts which make use of the Tcl scripting language. GetSlot returns the value in a Tcl variable, so sample usage includes:
set v [GetSlot {Object.Slot} {05-05-2010 12:00}]
SetSlot {Object.Slot} {05-05-2010 12:00} $v
The Tcl variable can be used in arithmetic expressions, conditionals, etc:
set v [expr 0.5 * $v]
if {$v > 1.0} {
...
} else {
...
}
Further scripting help with the TCL language is beyond the scope of this reference but can be found in online searches.
HDB_EnsembleID
HDB_EnsembleID <HDB dataset name> <Ensemble ID> ...
Sets the Ensemble ID for an HDB dataset that is configured to have its ID selected when MRM is started.
• <HDB dataset name> is the name of the HDB dataset that is configured to have its ID selected when MRM is started. If the name contains embedded white space, it must be enclosed in braces {}.
• <Ensemble ID> is the Ensemble ID to set on the dataset.
IDs can be set for more than one dataset by adding addition pairs of names and IDs.
HDB_ModelRunID
HDB_ModelRunID <HDB dataset name> <Model Run ID> ...
Sets the model run ID for an HDB dataset that is configured to have its ID selected when its DMI is invoked.
• <HDB dataset name> is the name of the HDB dataset that is configured to have its model run ID selected when its DMI is invoked. If the name contains embedded white space, it must be enclosed in braces {}.
• <Model Run ID> is the Model Run ID to set on the dataset.
IDs can be set for more than one dataset by adding addition pairs of names and IDs.
ImportDatabaseDMI
ImportDatabaseDMI <file name> [ReplaceInModel|RenameImported]
Import a database DMI that was previously exported to a file. The first argument (required) is the name of the file which contains exported database DMIs, datasets or name maps. The second argument (optional) specifies how conflicts are resolved when imported entities have the same name as entities in the model:
• <file name> is the name of an exported database DMI file to import. If the file path contains embedded white space, it should be enclosed in curly braces {}.
• [ReplaceInModel|RenameImported]- Specify how to handle DMI items that already exist. The options are:
– ReplaceInModel - the entities in the model are replaced with the imported entity. This is the default.
– RenameImported - the imported entity is renamed with a suffix IMPORT N
Example:
ImportDatabaseDMI {C:/temp/ArborInputDMI.dmi} ReplaceInModel
For more information on import and export of Database DMIs, see Sharing Database DMIs in Data Management Interface (DMI).
Note: Only Database DMIs can be imported with this command. Other types of DMIs are not supported.
ImportOptRestorePoint
ImportOptRestorePoint <file name>
Imports an optimization restore point tat was previously exported to a file. See Restore Point in Optimization for information on optimization restore points.
• <file name> is the name of the restore point file to import. If the file path contains embedded white space, it should be enclosed in curly braces {}. Restore point files are generally given the .orp file extension.
The import command will overwrite any existing restore points with the same name as the restore point being imported from the file.
Example:
ImportOptRestorePoint {C:/RWFiles/BlueRiverRestorePt.orp}
InvokeDMI
InvokeDMI <DMI name> [-UuserParam=value]
Invokes a DMI.
• <DMI name> is the name of the DMI to invoke. If the name contains embedded white space, it must be enclosed in braces {}.
• [-UuserParam=value] sets the user parameter “userParam” to “value”.
Example:
InvokeDMI {Operations Data Input DMI}
InvokeDssDMI
InvokeDssDMI <DMI name> !DssFile <DSS file> !DssFPart <DSS F part>
Invokes a DSS DMI.
• <DMI name> is the name of the DSS DMI to invoke. If the name contains embedded white space, it must be enclosed in braces {}.
• <DSS file> is the name of the DSS file. If the file name contains embedded white space, it must be enclosed in braces {}.
• <DSS F part> is the DSS F part. If the F part contains embedded white space, it must be enclosed in braces {}.
ListDMI
ListDMI [!Type <Input|Output>] [!Dataset <dataset type>]<output file>
Writes the names of the DMIs which match the specified criteria to the output file.
• [!Type <Input|Output>] limits the output to either Input or Output DMIs.
• [!Dataset <dataset type>] limits the output to DMIs which use only the specified dataset type.
• <output file> is the file the DMI list is written to.
Examples:
ListDMI C:/MyOutputs/DMIListFile.txt
Writes the names of all DMIs to the file DMIListFile.txt.
ListDMI !Type Input C:/MyOutputs/DMIListFile.txt
Writes the names of all Input DMIs to the file DMIListFile.txt.
ListDMI !Type Input !Dataset DSS C:/MyOutputs/DMIListFile.txt
Write the names of all Input DMIs which use only DSS datasets to the file DMIListFile.txt.
LoadDiagSettings
LoadDiagSettings <file path>
Loads the diagnostic settings from the specified file.
• <file path> is the path to the diagnostics setting file.
The diagnostic settings file must have been saved from the model file beforehand. See Loading and Saving Diagnostic Configurations in Debugging and Analysis for information on saving diagnostic settings to a file. As an example, you might have preconfigured diagnostic settings for printing out detailed informational diagnostics for debugging purposes when you run in batch mode.
Caution: If the model is saved using the SaveWorkspace command, it will be saved with these new diagnostic settings.
Example:
LoadDiagSettings C:/MyRiverWareFiles/DebugDetails_DiagSettings.txt
LoadOptSet
LoadOptSet <file path>
Loads the optimization goal set into the workspace.
• <file path> is the path to where the optimization goal set resides on disk.
Example:
LoadOptSet C:/MyRiverWareFiles/MyOptGoalSet.opt
LoadRules
LoadRules <file path>
Loads a ruleset into the workspace.
• <file path> is the path to where the ruleset resides on disk.
Example:
LoadRules C:/MyRiverWareFiles/MyRuleset.rls
OpenGlobalSet
OpenGlobalSet <file path>
Opens a global function set.
Note: This must be called before LoadRules if the ruleset references functions in the global set.
• <file path> is the path to where the set resides on disk.
Example:
OpenGlobalSet C:/MyRiverWareFiles/MyGlobalFunctions.gfs
OpenWorkspace
OpenWorkspace <file path>
Loads a model into the workspace.
• <file path> is the path to where the model resides on disk.
Example:
OpenWorkspace C:/MyRiverWareFiles/BasinOperationsModel.mdl
Output
Output <outputDeviceName>
Generates an output file that is specified in the Output Manager of the model. See Output Manager in Output Utilities and Data Visualization for details about the available output devices and how they can be configured. Plot pages cannot be generated from a RCL script.
• <outputDeviceName> is the name of the output device saved in the Output Manager of the model.
Examples:
Output OperationsForecastReport
Output FloodStorageAllocationChart
RequiredInfo
RequiredInfo <message>
This command adds the specified message to the diagnostic output as a Required Information message. It is a means to allow you to specify any text in the RCL script to be added to the diagnostic output file.
• <message> is any user-specified text string. The text must be enclosed in braces {} if it includes spaces.
Example:
RequiredInfo {Executing a planning run}
Output in the diagnostic output file:
_REQINFO_: "Executing a planning run"
RequireVersion
RequireVersion <major version>.<minor version>[.<patch level>]
Specifies the RiverWare version required to execute the batch script. If the RiverWare version is earlier than the required version, the command issues an error message and stops the script file’s execution.
• <major version>.<minor version>[.<patch level>] are the major version, minor version and optional patch level of RiverWare necessary to execute this batch script.
Example
RequireVersion 7.3.1
If the version of RiverWare is earlier than 7.3.1, the batch script will fail with an error message.
ReorderGoalSet
ReorderGoalSet <order slot>
This command allows you to reorder items (goals, groups, or certain statements) within the currently loaded optimization goal specified set. The desired order is specified by the single column order slot, a table slot, each of whose rows corresponds to the name of an item in the goal set. The values in the single column of the order slot are interpreted as integers giving the desired order of that object with respect to other set items referred to in the table. This command is similar to the Reorder RPL Set Script action; see Reorder RPL Set.
Example:
ReorderGoalSet BasinDataObj.GoalPriorities
The command refers to the table slot shown in Figure 2.2.
Figure 2.2 Table slot with priorities to reorder the goal set
SaveRplSet
SaveRplSet <Set Name> <Application Type> <File Path> [DoNotOverwrite]
This command allows you to save to a file a RPL set that is currently open in the model. If the specified RPL set is not open in the model, the batch script will fail with an error message.
• <Set Name> is the name of the RPL set to be saved. If the set name includes spaces, it must be enclosed in braces {}. This is the name displayed at the top of the RPL Set Editor, not the file name.
• <Application Type> refers to the type of RPL set. If the application type includes spaces, it must be enclosed in braces {}. The valid options are
Global Functions
Initialization Rules
Optimization
Rule Based Simulation
• <File Path> is the path to where the RPL set is saved. If the file already exists, the command will overwrite the existing file.
• [DoNotOverwrite] is an optional argument. If present, the command will not overwrite an existing file.
Examples:
SaveRplSet {Bighorn Basin Rules} {Rule Based Simulation} C:\MyFiles\Bighorn.rls
SaveRplSet {Bighorn Opt Goals} Optimization C:\MyFiles\BighornOpt.opt
SaveWorkspace
SaveWorkspace [file path]
Saves the model which is currently loaded into the workspace.
• [file path] is the path to where the model is to be saved on disk. If the file path is not specified, the OpenWorkspace file path is used.
Examples:
SaveWorkspace
Saves the model to the same file name from which it was opened
SaveWorkspace C:/MyOutputs/SavedModelFile.mdl
Saves the model to the file specified
SetDiagFile
SetDiagFile <diagnostic file>
Sets the location of the diagnostic output file.
• <diagnostic file> is the path to where the diagnostic file will be written.
SetEnv
SetEnv <variable> <value>
Sets an environment variable for use within the RiverWare run.
See Environment Variables for details on setting and using environment variables.
SetRunInfo
SetRunInfo <#RunInfo|#MRM <MRM configuration>>
[!InitDate <date time>]
[!StartDate <date time>]
[!EndDate <date time>]
[!Duration <delta time>]
[!Controller <controller type>]
Sets single run information (#RunInfo) or multiple run information (#MRM). If #MRM is specified, you also need to specify an MRM configuration <MRM configuration>.
• !InitDate sets the run’s initial date to <date time> of format {MM-DD-YYYY HH:MM}.
• !StartDate sets the run’s start date to <date time> of format {MM-DD-YYYY HH:MM}.
Note: If you specify both !InitDate and !StartDate with the same SetRunInfo command, the argument that appears second will take precedence.
• !EndDate sets the run’s end date to <date time> of format {MM-DD-YYYY HH:MM}.
• !Duration sets the run’s duration to <delta time> of format {Number TimeUnits}.
• !Controller sets the run’s controller to <controller type>. The controller type must be one of the controllers available in the Run Control dialog:
– Simulation
– Rulebased Simulation
– Optimization
Note: Controller types that contain embedded white space must be enclosed in braces {}.
Following are samples of the syntax:
SetRunInfo #RunInfo !InitDate {04-21-2011 24:00} !EndDate {04-26-2011 24:00}
SetRunInfo #RunInfo !StartDate {04-22-2011 24:00}
SetRunInfo #RunInfo !EndDate {04-26-2011 24:00}
SetRunInfo #RunInfo !Duration {200 Days}
SetRunInfo #RunInfo !Controller {Rulebased Simulation}
SetRunInfo #MRM “Paleo Runs”
SetSlot
SetSlot <Object.Slot> [<date time>] <value>
Sets the series or scalar slot’s value to the value, assumed to be in user scale and units. Object.Slot should be enclosed in curly braces {} if it contains embedded white space.
• <date time> is only for SeriesSlots and must be enclosed in curly braces {} as it contains embedded white space - for example, {05-15-2010 12:00}.
See GetSlot, for details on possible usage.
SetTrace
SetTrace <1|0>
Enable or disable trace messages from the RCL interpreter. The trace messages are prefaced with “TRACE:” and written to standard output; they can be captured in a file with the --log <log file> command line option.
SlotList
SlotList <output file>
Writes information about all slots in the model to the output file.
• <output file> is the file the slot list is written to.
The information is written as comma-separated values to the output file; the following fields are written.
• lnno: line number, always 0 (included for compatibility)
• Section: the containing object's meta-type, one of SimObj, Account, Supply, Exchange or Payback)
• O: the containing object's name
• Otype: the containing object's type, for example Reach
• S: the slot's name
• Stype: the slot's type
• UnitType: the slot's unit type, for example Flow
• UnitScale: the slot's scale
• Units: the slot's unit, for example cfs
• UnitFmt: the slot's format, one of %d %f or %e
• UnitSpec: the slot's display precision
• DataType: the slot's data type, one of OneInit, MultiInit AllInput, AllOutput or Other
SlotListDMI
SlotListDMI <DMI name> <output file>
Writes information about the slots to/from which the DMI imports/exports data; the information is written as comma-separated values to the output file. The information includes:
• The slot’s name.
• The slot’s priority (determined by its dataset association).
• The slot’s begin date “mm-dd-yyyy”.
• The slot’s begin time “hh:mm:ss”.
• The slot’s end date “mm-dd-yyyy”.
• The slot’s end time “hh:mm:ss”.
• The dataset associated with the slot .
• The dataset’s type, currently DSS or HDB. If the Dataset is DSS, then the slot’s DSS path “/A/B/C/D/E/F/” is also provided as another comma separated value.
StartController
StartController [!MRM <MRM configuration>]
[firstTrace=N]
[numTrace=M] ctlFile=file]
Starts the current RiverWare controller.
• !MRM will start the Multiple Run Management controller instead of the single run controller, using the specified MRM configuration. RCL currently does not support many commands for defining multiple runs, so models should already contain the multiple run definitions.
The following commands override the values in the MRM configuration in the model file ([!MRM <MRM configuration>] must be used if you wish to specify these parameters):
• [firstTrace =N] sets the index sequential initial offset
• [numTrace=M] sets the index sequential number of runs
• [ctlFile=file] sets the output control file.
SyncObj
SyncObj [!Acct] [!ExDiffTS]
[!StartDate <start date>]
[!EndDate <end date>]
Synchronize slots to either the Run Control or the specified dates.
• [!Acct] includes accounting slots.
• [!ExDiffTS] excludes slots whose timestep size differs from the Run Control timestep size.
• [!StartDate <start date>] synchronizes slots to the specified start timestep, rather than the Run Control initial timestep.
• [!EndDate <end date>] synchronizes slots to the specified end timestep, rather than the Run Control finish timestep.
Examples:
SyncObj
Synchronizes all series slots to the Run Control initial timestep and finish timestep.
SyncObj !ExDiffTS !StartDate {04-23-2013 12:00} !EndDate {04-26-2013 12:00}
Synchronizes series slots to the specified start and end timesteps and excludes slots that have a timestep size that differs from the Run Control timestep size.
Revised: 07/03/2024