You can define supplemental programs that can be added to the program order. A supplemental program is a software application that is not included with HEC-RTS. A supplemental program is usually something that has been created by you or your office for use in water control management forecasting. For example, an office might have a locally developed software application that is used to model the unsteady flow regime of one or more rivers. This software application, and the river model associated with it, could be used in addition to or in place of HEC-RAS in the program order.

Supplemental Program Interface

A supplemental program must adhere to a specific interface for communicating with HEC-RTS during the execution of a forecast. This interface includes how to receive arguments for the supplemental program from HEC-RTS, how to output messages to the forecast compute log, and how to inform HEC-RTS about the exit status of the supplemental program.

Receiving Arguments

During a forecast computation, HEC-RTS executes a supplemental program by running its executable with a single command line parameter. The parameter is the fully qualified name of a file that contains the arguments for the supplemental program. This arguments file contains standard HEC-RTS arguments in keyword=value format – one keyword/value pair per line – plus any alternative-specific arguments defined for the supplemental program model alternative being executed.

The standard HEC-RTS argument keywords available in the arguments file are listed:

ComputeTypeType of computation, "Forecast" for HEC-RTS
ProgramNameSupplemental program name
ProgramAlternative Supplemental program model alternative name
ModelAlternative Model alternative identifier
Alternative Forecast run identifier
RunTimeWindowLookback, forecast, and end times of forecast
IOTimeStepInterval of data in a forecast DSS file
TimeZoneOffsetOffset in hours from UTC to watershed time zone
InputPosition Number of characters contained in the InputFPart name
ModelPosition Number of characters contained in the OutputFPart name
ForecastPathForecast directory of current forecast
ForecastDSSFileFully qualified name of forecast HEC-DSS file
InputFPart The F pathname part of data to be read from the forecast HEC-DSS file
OutputFPart The F pathname part of data to be written to the forecast HEC-DSS file
UserThe name of the HEC-RTS user executing the forecast
ClientDisplayThe X-Windows server address of the user's display
ForceRecompute"true" or "false" specifying whether the supplemental program must be executed – if "false", the supplemental program can decide whether it should execute

An example of a Supplemental Program Arguments File is shown in Figure 1.

Outputting Messages to the Forecast Compute Log

The supplemental program architecture allows the executable to output normal messages and error messages to the forecast compute log by writing these messages to a supplemental program log file.

Figure 1 Example Supplemental Program Arguments File
The supplemental program log file:

  • Has the same name as the arguments file name (passed as the only command line parameter to the supplemental program executable) with the ".args" extension replaced by ".log".
  • May contain special message type lines that instruct HEC-RTS how to process the following lines:
    • [No Message] specifies that the following lines will not be included in the compute log
    • [Log Message] specifies that the following lines will be treated as a normal compute log message
    • [Error Message] specifies that the following lines will be treated as a compute log error message
  • The message type lines are case insensitive, but must include the brackets ({*}\[* and *\]{*}) without any adjoining whitespace and may not appear on a line with any other text. The message type remains in force until another message type line is encountered. An implicit *\[No* *Message\]* line is processed at the beginning of the log file, so text in the log file before a message type line will not be included in the compute log.

Informing HEC-RTS of the Exit Status of a Supplemental Program

HEC-RTS uses the exit code returned from the executable to the operating system to determine the status of the supplemental program execution. The exit code is interpreted as follows:

0The supplemental program completed successfully
1The supplemental program skipped computation - the executable should not return this value if the ForceRecompute argument is set to "true"
otherAn error occurred during execution - the executable should output some diagnostic message(s) to the compute log if it returns a value other than 0 or 1

Create a Supplemental Program

To create a supplemental program: 

  1. From the Watershed Tree (Figure 2); right-click Supplemental, from the shortcut menu, click New. The Create New Supplemental Program dialog opens (Figure 3).
    Figure 2 Watershed Tree - Models Folder - Supplemental Shortcut Menu
  2. In the Name box (Figure 3), enter the name of the supplemental program.
    Figure 3 Create New Supplemental Program Dialog
  3. Enter a description in the Description box and click OK.
  4. The Supplemental Program dialog (Figure 4) opens. In the Supplemental Program dialog, specify the location of the software application that implements the supplemental program in the Executable box or click . An Open browser will open, browse to the location of the software application's executable, select the appropriate file, click Open. The Open browser will close, the executable name will display in the Executable box (Figure 4).
    Figure 4 Supplemental Program Dialog
  5. If needed, enter command line arguments in the Arguments box (Figure 4). Click OK, the Supplemental Program dialog closes. From the Watershed Tree, from the Models folder, expand Supplemental, the name of the supplemental program will display.

Add a Supplemental Program - Program Order

Once you have defined a supplemental program, you can add it to the program order. To do this, follow the instructions for adding an HEC program in HEC Software Applications in the Program Order. Instead of selecting an HEC program, you will select the supplemental program that you created and the appropriate input for the program.

Remove a Supplemental Program - Program Order

The steps to remove a supplemental program from the program order are the same as for removing an HEC program (HEC Software Applications in the Program Order).