This section describes methodology to run RiverWare from the command line and optionally execute a RiverWare Command Language (RCL) script. This Batch Mode allows you to run RiverWare without seeing the user interface and allows for automation of many processes including advancing the run dates, running DMIs to bring in new data, running the model, generating output, and saving the model.

Running RiverWare from the command line provides an alternative to selecting the RiverWare icon from the Windows system. In addition, RiverWare supports certain commands directly from the command line like loading models and rulesets and certain other operations. To access the command line, in the Windows Start menu Search field, type cmd.

Then select the option for cmd.exe.

A window similar to that shown in Figure 2.1 will open. To start RiverWare from this window, enter the full RiverWare path (depending on your PATH configuration).

A complete list of command line options can be viewed by invoking RiverWare with the --help command line argument. On the Windows command line, type:

When RiverWare is executed from a command line window, it is run as an independent process from the command shell, so exiting the command window will not automatically terminate RiverWare. The Windows task manager can be used to terminate batch runs of RiverWare.

Sometimes, the user wishes to run one or more models as automatic tasks (as Windows “Scheduled Tasks”). Setting up the runs using batch mode and the command line options can be useful in this approach. For example, a user may wish to run a series of models overnight when the machine is more available. One command line option that is useful is the --log <file> switch. This option sends any diagnostic output to the specified file.

The RiverWare Command Language (RCL) facility allows models to be run in batch mode. While in this mode, RiverWare does not open a user interface, but instead runs in background mode.

In batch mode, the user provides RiverWare with a script file, which contains the commands RiverWare executes. Commands are entered through the RCL file, rather than through the user interface. The commands are described in detail in the following document.

The syntax to invoke RiverWare in batch mode from a command prompt is:

The following example will invoke the batch script file called BasinOperationsScript.rcl and will write the diagnostics output to file called BasinOperationsDiagnostics.txt.

The <script file> defines how the batch run should proceed. In the file, you specify commands to load a model, load a ruleset if necessary, start a run, and save the results. In the simplest case, you will load a model, run a simulation, save the model, and exit batch mode. The following RCL commands support these actions:

This is a very simple example. The full complement of key words and commands is presented in the following section.

This section provides general information about the RiverWare Command Language (RCL) syntax and variables.

Environment variables are system variables that allow portability of models across machines and platforms.

If you wish to set environment variables and then reference them in the RCL script, they can be set using the TCL command “set env” as follows:

Then the variable can be accessed within the RCL script using the $env(variable) syntax. These variables are only available within the script, RiverWare has already inherited the environment before this is set and are then not available. To set variables to be available to RiverWare, use the SetEnv command; see “SetEnv”. This command has the following syntax:

These variables are then available in RiverWare but not available within the script. Most likely, you will want to set both variables within the script. Consider the following example:

Then within RiverWare, you can reference DMI_DIR using the $DMI_DIR syntax in DMI’s, MRM or other places.

Environment variables set outside of the RCL script can be referenced using the form:

VARIABLE is a letter followed by zero or more letters, digits or underscores. If the variable is followed by a letter, digit or underscore it must be “quoted” with () or {}.