RCL Commands Reference

Automation Tools : Batch Mode and RiverWare Command Language : RCL Commands Reference

Following are the RCL commands in alphabetical order.

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

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

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}

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 --help command line option lists the output fields.

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/09/2023