The RiverWare Data Management Interface (DMI) provides a mechanism to transfer data into and out of RiverWare in a highly configurable and automated manner. For example, you can configure a DMI that, with the click of a button, brings all of the observed inflows and initial pool elevations into the model.

There are three types of DMIs.

In this section, we describe the DMI user interface components that are general to all of the approaches. Then we describe the Control File-Executable approach and its specific user interface components and the Trace Directory DMI approach and its specific user interface components. Finally, we describe the Database DMI approach and its specific user interface components.

This section describes the user interface used to execute and create DMIs. This section applies to all of the DMI approaches. See “Database DMI” for details on the user interface for the Database DMI.

The DMI Manager dialog enables you to do the following:

In the DMI Manager and related dialogs, actions can be performed using one or more of the following, each of which acts on the current selection:

Main menu items, toolbar buttons and context menu items performing the same action share the same icon. For example, Figure 1.1 and Figure 1.2 illustrate that from the DMI Manager dialog a user can invoke the selected DMI identically using the DMI, then Invoke main menu item, the Invoke toolbar button, the DMI Invoke context menu item and the Control-I keyboard accelerator.

Actions which aren’t valid for the current selection are disabled. (That is, their main menu items, toolbar buttons and context menu items are disabled.)

The document refers to main menu items when describing actions; be aware that in most cases toolbar buttons, context menu items and keyboard accelerators are also available for the actions.

The Edit menu and right-click context menu have a Copy operation. This leads to the following options:

A Paste operation will add the most recently copied items with the name “Copy of DMI Name 1”.

Create a new DMI under the DMI, then New DMI main menu item and choose the type of DMI to create; the DMI has a default name.

Delete a DMI with the Edit, then Delete main menu item.

Open the DMI Editor dialog with the Edit, then Edit main menu item or double-click the row. The DMI Editor is different for the different types of DMIs. See “DMI Editor Dialog” for details on the DMI Editor dialog for the Control File-Executable approach. See “Trace Directory DMI Editor Dialog” for details on the Trace Directory DMI. See “Creating a Database DMI” for details on the DMI Editor for the Database DMI.

Sorting of DMIs and DMI groups is limited to sorting by name or type by selecting column header.

A DMI group is an ordered collection of one or more DMIs. When a DMI group is invoked, its DMIs are invoked in order, until all have completed or one has failed. There are two kinds of groups:

Create a new DMI group with the Group, then New Group or New Year Mapping Group main menu item.

DMIs can appear one or more times in the DMI Manager dialog; once as a top-level DMI and zero or more times as a member of a group. Actions which pertain to a DMI globally (for example, editing it) are only valid when a top-level DMI is selected; actions which pertain to a DMI within a group (for example, moving it up or down) are only valid when a member DMI is selected. See Figure 1.3.

When the distinction is important, a DMI is referred to as either a top-level DMI or a member DMI.

Editing DMI groups includes:

To edit a DMI group’s name double-select the name cell, to edit the name in place.

To add a top-level DMI to a group, select the DMI, then Add to Group main menu item. You are then presented with a dialog listing the available groups; select the desired group and select OK.

If no groups are available (e.g. there are no groups or the DMI is a member of all groups) you will be notified.

To remove a member DMI from a group, select the DMI, then Remove from Group main menu item.

To move a member DMI within a group, select either the DMI, then Move Up main menu item or the DMI, then Move Down main menu item.

To query a group membership for a DMI, select the DMI, then Group Membership main menu item; the group membership is displayed.

Before we describe it in detail, following are the limitations on this utility:

You create the Year Mapping Group, add Input DMIs to the group, define the mapping, and then invoke the group. These steps are described in the following section:

You can copy and paste the information from and to external applications using the right-click context menus shown.

Clear the Years in Database or the selected Comments using the same menu.

Table 1.1 describes how the mapping deals with Leap Years.

Following are some possible error conditions:

To lock the DMI manager dialog, select Edit, then Lock main menu item. Before locking the dialog you must close the DMI Parameter and DMI Editor dialogs (and will be warned if the dialogs are open).

When the dialog is locked, you cannot edit the DMI or DMI group configuration.

To unlock the DMI Manager dialog, select the Edit, then Unlock main menu item.

The DMI Parameter dialog enables the user to do the following:

To create a parameter the user either:

To edit a parameter name the user clicks twice in the Name cell, to edit the name in place. When the edits are applied the new parameter name is validated; the possible errors are:

To edit a parameter type, the user Click-Pause-Clicks in the Type cell, to activate the Type menu and then selects the parameter type.

If the selected type has attributes the default attributes are displayed in the Attributes column.

For an Integer Range the attribute-specific dialog enables the user to enter the minimum and maximum values, ensuring the maximum value is greater-than the minimum value:

Figure 1.5 shows that for a List, the attribute-specific dialog enables the user to append, insert, delete, edit and order text items, ensuring the text items contain only non-white space characters (first image).

Figure 1.6 shows that if the resulting list contains more text than will fit in the Attributes cell, an ellipsis (“...”) is displayed and the entire list is displayed in a tooltip when the mouse pointer is paused on the Attributes cell (second image).

To export parameters the user selects the File, then Export Parameters main menu item, which opens a file chooser dialog. The user selects the file to export the parameters to, then selects Save. If the file has a “.gz” suffix the parameters are saved in a compressed format.

To import parameters the user selects the File, then Import Parameters main menu item, which opens a file chooser dialog. The user selects the file to import the parameters from, then selects Open.

Parameters are imported by name; if the file contains a parameter which already exists, the user is asked whether to keep the existing parameter or replace it with the import parameter:

The user can then:

When the DMI Parameter dialog edits parameters it can invalidate DMIs using the parameters. Consider Param0 (a Boolean parameter), Param1 (a Text parameter) and Param2 (an Integer Range parameter):

Although the DMI is invalid, it isn’t changed; that is, when the DMI is invoked its executable’s command line will still include:

However, when the user edits the DMI there will be a graphical indication that the DMI is invalid, and the user will be constrained in how the DMI can be edited.

Param0 is shown entirely in red to indicate it is deleted; the user:

Param1’s value and Param2’s value are shown in red to indicate they are invalid; the user:

Finally, if the DMI Editor dialog is open when the user edits the parameters, a confirmation dialog appears, notifying the user that the DMI Editor dialog will be updated.

The DMI Invocation Manager dialog displays all DMI invocations which RiverWare has recorded. From this dialog, the user can clear values that were set by a specific DMI.

The dialog is opened from the DMI Manager dialog using the Utilities, then Invocation Manager menu.

For each invocation the dialog displays the following:

The DMI Invocation Manager is a singleton; that is, no other edits or views to any RiverWare window can be made while the DMI Invocation Manager is open. It must be closed first. Use the File, then Close Window menu, Ctrl-W shortcut or Close button.

Values set by a DMI with Invocations Recorded are given the “Z” flag. Tooltips on the slot window displays indicate which DMI set each values on the slot. For example, in Figure 1.7, on Jan 3, 2014 the value 21.81 was set by the InputDailyAccountingFromUCHDB2 DMI.

The dialog has two views, By DMI and By Date.

In the By DMI view, the invocations are grouped by DMI, with the invocations in reverse-chronological order (most recent is on the top).

In the By Date view, the invocations are displayed in a list, in reverse chronological order.

In both views, the slots set by an invocation are displayed in a tree view in alphabetical order.

It is possible an invocation of a DMI will be superseded by other events, perhaps another invocation of the DMI or user inputs from the user interface. In Figure 1.8, the first invocation of “CA Bank Input T1 REC” (bottom) has been superseded by the second invocation (top), and consequently the first invocation (bottom) no longer is responsible for setting the values that are on the slot. This is indicated with the slot name grayed-out and “0 values” in the Status column.

A user is able to select invocations, and then from the Edit menu Clear the values set by the invocation (i.e. the values in the slots).

The Edit, then Clear Selected Values feature clears values set by DMIs on a per-invocation basis; a user selects the DMI invocations to clear, and only the values set during those invocations will be cleared. Suppose a DMI is invoked twice, setting values on a SeriesSlot at timesteps t1 and t2 during the first invocation and at timesteps t3 and t4 during the second invocation. If a user selects the first invocation, only the values set at timesteps t1 and t2 will be cleared.

Following are some limitations on the clearing of DMI values:

DMIs can then be executed directly from the DMI Invocation Manager using the DMI menu.

A user is able to select invocations, and then delete the invocation record by selecting Deleted Selected Records in the Edit menu. This operation deletes the record from the list of invocations but does not delete any of the values.

There sere five ways to invoke a DMI or DMI Group: from the DMI Manager, from the Workspace, from the SCT, from the DMI Invocation Manager, or from RPL blocks.

When a DMI is invoked, each warning is displayed in the Diagnostic Output dialog.

If the DMI is configured to Confirm Warnings (see “Name and Type” and “Confirm Warnings Checkbox”) or an error occurs, a separate dialog called the DMI Status Dialog will open. Figure 1.11 shows the warning or error messages.

If the messages are just warnings and you wish to continue execution of the DMI (Confirm Warnings is selected), select OK. Otherwise, select cancel to stop execution.

Any errors generated by the DMI are displayed in the DMI Status Dialog and in the Diagnostic Output dialog in red text. After an error, the DMI stops executing.

The status of an executing DMI is shown in the bottom of the DMI manager. You can also configure to show a separate DMI Status Dialog that has optional panels for the Progress, Status, and Confirmation. This dialog shows information on the DMI as it executes including the slots that it is processing and the location of the data being processed. To show this status dialog, from the DMI Manager, select DMI, then Show DMI Status or DMI, then Show DMI Progress. The selections are saved with the model file. In Figure 1.12, both Show DMI Progress and Show DMI Status are selected. In addition, there are Confirmation messages that must be confirmed before this DMI can continue.

In Figure 1.13, the Progress panel shows that the DMI is executing including the Group (if there is one), the DMI, and the slots being processed.

The Status Panel shows the results (for an Input DMI only). For example, in Figure 1.14, the treeview has been expanded to show all of the information. This indicates that 363 values were imported for each slot, but three values in each slot were missing. The red messages are also copied to the Diagnostics Output Window so you can see the messages after closing the DMI Status dialog.