The Database DMI provides a direct connection between RiverWare and an external database. Databases currently supported are the U.S. Army Corp of Engineers Hydrologic Engineering Center’s Data Storage System (DSS), the Hydrologic Database (HDB), and Microsoft Excel. Following are the slot types that can be read or written by each type of DMI:

This section presents an overview of the Database DMI, then presents details on creating database DMIs, datasets, name maps, and sharing database DMIs.

The Database DMI allows RiverWare to import and export data directly from and to the database. In this document, a database refers to a specific database implementation, for example a DSS file or Excel workbook. Figure 4.1 shows the interaction between RiverWare, the DMI Server and the database. The user sets up the Name Maps, configures the Datasets, and identifies slots and time intervals at which to import/export data in the Database DMI.

When the Database DMI is invoked, the Dataset and Name Maps are read specifying the database to use, the units and what slots/objects are named in the database. Any wildcarded slot selections are then fully specified and then any Name Maps are applied. Then commands are passed to the DMI server: for an input DMI, the server locates the data in the database and imports data into RiverWare slots; for an output DMI, the server takes the RiverWare slot data and inserts it into the appropriate place in the database.

Figure 4.2 shows in more detail the three pieces of a database DMI and how they work together to define a DMI.

The three pieces (slot selections, datasets, and name maps) were designed to be very flexible. In the simple case of importing or exporting 1 slot, the user needs 1 slot selection, 1 dataset, and optionally 1 name map (DSS only). It is possible to configure the system with more functionality which leads to more complexity.

For example, in Figure 4.3, slot selections 1 and 2 share dataset 1 which is an HDB dataset; no Name Map is required. In this DMI, Slot selection1 is an input from HDB for the full run and then slot selection 2 is an input from HDB for the full run. Slot selection 3 is used to input initial conditions and uses Dataset 2 which points to a separate DSS file in Dataset 2. Slot selection 4 inputs from a DSS file referenced in Dataset 3 for the full run. Both Dataset 2 and 3 are DSS datasets and share Name Map 1.

We will now look at each component starting with creating a Database DMI, then look at Datasets followed by Name Maps.

A Database DMI is created from the main DMI Manager dialog using the DMI, then New DMI, then Database DMI with Excel, DSS, or HDB menu.

There are two ways to define and edit a Database DMI:

Once a new Database DMI is added to the DMI manager, the user can edit it using the Database DMI Editor. The Database DMI Editor dialog provides a convenient place to create, edit, and view database DMIs. It also provides a single dialog for configuration of a fully functional DSS Database DMIs. To that end, it allows the user to specify all required configuration information and as much optional configuration information as is feasible. The real power of this dialog is that the user can see the fully specified information that will be sent to the database, which is especially useful for DSS.

To open the New Database DMI Editor, the user selects Edit, then Edit with New Database DMI Editor. The Database DMI dialog appears.

This dialog is like an editable view into the Dataset Manager. Thus, the user can see what has already been configured in those dialogs but also make edits that will be applied to those pieces. It is important to note that if the user edits a dataset or Database DMI in the editor window, the user cannot also edit the individual components at the same time.

Figure 4.4 shows a similar figure to the one presented in “Overview”, but with the Database DMI Editor also shown.

Conceptually the dialog has four sections from the top to the bottom, as shown in Figure 4.5 and described in the following sections:

In this dialog, each type of dataset has its own color:

The cyan rows are slot selections. The green boxes are cells in which data entry is possible.

The Database DMI general configuration section (upper section) of the dialog allows you to do the following:

The DMI configuration section (middle section) displays the configuration of the DMI. In this dialog, each type of dataset has its own color:

The information is presented in a tree-view, with each level representing a more detailed specification, as detailed in Table 4.1.

The following sections describe the editable parts of each of the levels of the treeview.

The following actions can be done for a Slot Selection row:

The following actions can be done for a Slot Selection row:

The following actions can be done for Slot Selection rows:

Figure 4.7 shows a fully defined DSS configuration.

Figure 4.8 shows the right portion of the dialog.

Datasets and slot selections can be disabled for debugging purposes. On the left part of each Dataset or Slot selection row, there is a green check if it is enabled. A red X indicates it is disabled. The purpose of this feature is to allow you to debug a DMI by disabling datasets or slot selections and then running the DMI to test other aspects of the DMI. This behaves as follows:

The on/off state is preserved in the model file when saved.

If you specify a Name Map when configuring the Dataset, then the following will occur:

It is possible to have slot selections that are not used by any of the datasets. To show these selections, select Unused Slot Selections.

The selections are then shown as a golden colored row titled Unused Slot Selections at the Dataset level. You can view and change the selections (and the slots selected). From right-click context menus, you can delete the selection. You can also drag and drop the slot selection onto a dataset to associate that slot selection with a dataset.

For DSS datasets, an additional panel allows you to fully edit the dataset.

When there is a DSS dataset in the DMI, the DSS checkboxes are displayed. Select the DSS Configuration check box to show general configuration settings.

This shows a view similar to the dataset. When you have a DSS dataset selected, the general configuration becomes enabled and allows you to:

See “Datasets Overview” for descriptions of these fields.

You can configure the DSS file path for multiple DSS datasets through the Configure DSS Datasets dialog. The dialog is opened by

The Configure DSS Datasets dialog appears.

The top portion of the dialog shows all of the DSS Datasets in the model and their DSS File in sortable columns. The bottom portion of the dialog shows the file path for the dataset that was selected when the dialog opened.

Specify an alternative DSS file if desired. Then:

If a DSS dataset has been modified in another dialog, the DSS file cannot be set. You are notified with the following message: “The following datasets cannot be modified because they are being modified in another dialog”. Apply the changes to that dialog and you can now use the Configure DSS Datasets dialog again.

For DSS, you can specify values to be used for the user parameters. The parameters must be previously configured using the Parameter Dialog; see “DMI Parameter Dialog” for details.

Edit a parameter value by double-clicking the Value cell to activate a control appropriate for the parameter’s type. To use the parameters in the DSS part information, specify the value with the percent sign; use the following syntax:

Thus if you have a parameter named Run_Name with a text value and you wanted to put the value in part F, you would double-click part F on the desired Dataset row and type %Run_Name%. In the lower portion, double-click the value column and specify the integer to use. The resolved information is shown for each slot that is a part of the dataset. Figure 4.9 shows this example.

Now that we have described the overall approach for creating a Database DMI, we will present a few example use cases of creating various types of Database DMIs.

This example shows how to create a Database DMI to/from DSS using the Database DMI Editor. We assume there are no other Datasets or Name Maps already defined. You would take the following steps:

Figure 4.10 shows the configuration for this example.

This example shows how to create a Database DMI to export data to Excel using the Header approach. We assume there are no other Datasets or Name Maps already defined. You would take the following steps:

Figure 4.12 shows this setup.

This database DMI is now fully configured. You can execute it from the DMI manager.

Figure 4.13 shows the resulting spreadsheet for our three-reservoir model.

This example shows how to create a Database DMI to import data from Excel using the Ranges approach. We assume there are no other Datasets or Name Maps already defined. You would take the following steps:

A dataset encapsulates all RiverWare knowledge about the database. In general, there are two types of knowledge contained in a dataset, configuration information and the database specification.

In RiverWare, datasets are defined and configured in the Dataset Manager as shown in Figure 4.17. The Dataset Manager is accessed from the Utilities, then Dataset menu on the DMI Manager. Selecting Edit, then New DSS Dataset, for example, adds a new DSS dataset.

In general, all of the DSS dataset configuration can (and should) be performed from the Database DMI Editor. The DSS Dataset editor shows the results of configuration but the Database DMI has much more functionality. This section describes the functionality of the Database DMI Editor with respect to DSS datasets.

The DSS File name may contain user parameters as %ParamName% (the same as for the DSS part information). The DSS file name may contain multiple parameters but the parameters must be typed in; they are not available from a context menu. See “DSS DMI User Parameters” for details.

The DSS file name text shows the user parameters while a tooltip shows the substituted values.The user parameters can be all or part of the DSS file name and can be used in conjunction with environment variables, for example:

Optionally, select the desired Name Map from the Name Map menu. The selections are based on the Name Maps configured in the Name Map Manager. See “Name Mapping” for details on Name Maps. If you have no name map selected, select the Name Map Mgr button to open the Name Map Manager. If you do have a Name Map selected, the button says Open to open that Name Map.

The user specifies how missing values are represented in the database. The current choices are

The user specifies how paired data should be imported to table slots in terms of overwriting existing data or leaving extra data unchanged.

This option is only enabled for Input DMIs. The options are:

The units that are used in the DSS database are specified in the Dataset dialog. A pull-down menu allows the user to specify that the Database DMI should Use Database Units, Prefer Database Units, or Use Dataset Units. Figure 4.18 shows an example.

This adds an entry to the list. Double-click the word NONE under the Type to change the type. Figure 4.18 illustrates. Change the Scale and Units in a similar manner. These units are used to specify the units that will be written to the database if an Output DMI is used and the units that the database contains if an Input DMI is used.

Figure 4.19 shows an example of specified units.

Select the Edit Data Types button to edit the data types. In the resulting dialog, you can specify that a selection of slots should have a certain data type. The DSS data types are: PER-VAL, PER-AVER, INST-VAL, INST-CUM. The selection is similar to other slot selections as it is dynamic and can make full use of wildcarding.

Double-clicking an HDB dataset in the Dataset Manager opens the HDB Dataset editor. In this dialog, the dataset can be renamed and configured. It has two tabs, one for general configuration and one specific to the HDB implementation.

Mappings of RiverWare names to HDB IDs are contained in database tables, so Name Maps are not needed for configuring a dataset for HDB. Specifying which database mapping to use is described later in the HDB tab of the configuration dialog.

You specify how missing values are handled when exchanging data with HDB. In general, a NaN in RiverWare is not represented as a data record in HDB. The current choices are as follows:

The Group Slots for Writing check box configures the DMI to group slots together when writing to the database. This option is particularly useful when you have many slots but few values in those slots. Grouping the slots minimizes the network traffic. This can significantly improve performance over a network.

A menu in the Dataset dialog allows you to specify how units should be handled for a dataset. The choices are as follows:

Units are defined in HDB for each piece of data, so Use Database Units is always applicable. If the unit type of the data in HDB does not match the unit type of the slot in RiverWare and the units cannot be converted, the slot is skipped and a warning message is given. The exception is if the unit type of the slot in RiverWare is NOUNITS. Here the unit type matching between HDB and RiverWare is skipped and the data is allowed to be exchanged with no conversions being applied.

In addition, to improve performance you can configure slot units in the Dataset and Use Dataset Units. This prevents additional calls across the network to get the units from the database.

Configuration specific to the HDB database is specified in the HDB tab of the HDB Dataset editor.

The HDB Database field specifies which database the dataset will interact with. The entry in this field should be a TNS name or connect string that will allow connection through Oracle Networking Services (SQL*Net) to the desired database. You need to have Oracle networking available on your computer through Oracle Client or a full Oracle database installation.

The first time in a RiverWare session that a specified database is connected to, you are prompted to provide a user name and password to log in. For a user to retrieve metadata or read and write data to HDB, they must be granted the roles model_priv_role and app_role in the database to have the necessary permissions.

To run in batch mode, the login information must be provided in a file. The code looks for a file named.dblogins in your home directory, which is specified by the HOME environment variable on Solaris, and the combination of the automatically defined HOMEDRIVE and HOMEPATH environment variables on Windows. The format of the file should be a line for every database, with that line containing the database name, login, and password separated by whitespace (blanks or tabs). Blank lines and comment lines starting with # are permitted in the file. If you want to set up a different file, the DBLOGINS environment variable can be defined as a full path (directory and file) where the code will look for the login information.

The Mapping ID field specifies what mapping will be used in the database to map RiverWare objects and slots to HDB sites and data types. You must select the adjacent Select button to pick a mapping from the database.

The Select button brings up the Select HDB Mapping ID dialog populated with all the available mapping IDs, their names, and descriptions from the HDB_EXT_DATA_SOURCE table in the database. You can then select a mapping, which populates the Mapping ID field on the HDB tab of the dataset dialog with the ID and the name of the mapping.

HDB maintains different tables for data of differing intervals (timesteps). Slots of varying timesteps can be freely intermixed in a list that is associated with a dataset, and the correct tables for each timestep will be automatically accessed in HDB. One case that does need specification is for the water year tables in HDB. There is no corresponding water year timestep in RiverWare, although some users have used slots with a 1 Year timestep to hold water year data in some of their RiverWare models. To handle this case, an option box on the dataset dialog to Use water year tables in HDB for 1 Year timestep data has been provided. If a user checks this box, all 1 Year timestep data read and written with the dataset will be moved to and from the water year tables in HDB instead of the year tables.

The HDB Table Type frame on the dataset dialog specifies which of the tables in HDB the dataset will interact with. The selection of Model, Real, or Ensemble determines the configuration options that become available in the rest of the dialog.

A selection of Model in the HDB Table Type frame of the dataset dialog means that any data moved using the dataset will be read from or written to the model (m_ xxxx) set of tables in HDB. Model data is typically forecasted data, although there are no restrictions on its dates being future or historic. There can be multiple forecasts made for a piece of data at the same date and time, so data in the model tables must be associated with a model run ID that indicates from what run of a model the data originated. If data is written to a model run ID with a DMI, any previous data that was associated with that ID will be deleted from the model tables. Therefore, only the data from one particular run of a model is represented in a single model run ID. Reading or writing of model data requires metadata selection in the Model Run ID frame that appears with the selection of Model in the dataset dialog.

The Model Run ID frame allows you to select either Select ID or Select ID when DMI is invoked. The Select ID option allows you to preselect a model run ID to associate with the dataset for reading and writing data with the model tables. To select a model_run_id, you must select the Select button adjacent to the model run ID field. This brings up the Select HDB Model Run ID dialog.

All model run IDs are associated with a particular model as defined in the database. The model run ID dialog is designed to display all the IDs in the database for a specified model. The model is selected via the Select model from MODEL table field at the top of the Model Run ID dialog. Selecting the Select button adjacent to the field brings up the Select HDB Model ID dialog populated with all the models defined in the HDB_MODEL table in the database.

You can then select a model, which populates the Select model from MODEL table field on the model run ID dialog with the model ID and name, as well as populating the model_run_id list in the dialog with information for all the model_run_ids defined for the model. You can then select an existing model run ID from the list, which closes the dialog and populates the model run ID field in the Model Run ID frame of the dataset dialog with the model run ID and name.

There are two other options for Model Run IDs on the Select HDB Model Run ID dialog. Instead of just selecting an existing ID, you can also edit an existing ID or create a new one. To edit or create a model run ID you still must have selected a model at the top of the dialog. An existing ID that is displayed can then be highlighted and edited by selecting the Edit button at the bottom. This brings up the Edit HDB Model Run ID dialog, which displays all the information fields for the model_run_id and allows you to edit these fields. Selecting the Save button will then save the edited information for this model run ID to the database.

The Create button at the bottom of the Select HDB Model Run ID dialog allows you to create a model run ID that is associated with the model shown in the Select model from MODEL table field at the top of the dialog. Selecting Create brings up the Create HDB Model Run ID dialog, which contains fields where information can be entered for the new model run ID. The Run Date field is populated with the start time of the run, but can be changed by selecting any portion of the date and typing or using the spinners. At least the required fields marked with an asterisk must be filled out. Selecting the Create button will then save entered data to the database as a new model run ID where it will be assigned the next available model run ID number. The new ID will then be added to the list and highlighted back on the Select HDB Model Run ID dialog.

The Model Run ID frame of the dataset dialog has a second option for specifying model run IDs by selecting Select ID when DMI is invoked. When this option is selected, you do not preselect a model run ID that is always used with the dataset, but rather you are prompted for one when a DMI containing the dataset is executed. This option could be useful in a case where the DMI is run to record forecast data on a regular basis with the data always being preserved in separate model run IDs in the model tables. To limit the potential for you to accidentally overwrite the previously saved data by forgetting to change the ID; you must select the ID each time the DMI is run.

Selecting an ID under the Select ID when DMI is invoked option utilizes the same dialogs as does the preselect ID option. The Select HDB Model Run ID dialog appears where you can select a model and see its existing IDs. An existing ID can then be selected, an existing ID can be edited and then selected, or a new model run ID for the model can be created then selected.

A selection of Real in the Table Type frame means that any data moved using the dataset will be read from or written to the real (r_ xxxx) set of tables in HDB. Real data are typically current or historical observed values; future data cannot be loaded into the real tables. A write of real data to HDB requires that some other metadata be selected by you in the Real frame that appears with the selection of a Real table type in the Dataset dialog.

HDB has a per-value Validation field in the R_DAY, R_HOUR and R_INSTANT tables which typically indicates whether the data is provisional or approved. The field is a 1 byte character which is usually a “P” for provisional and an “A” for approved.

The Read and display validation character option allows you to import validation characters from HDB into Notes on Series Slot, which are then shown on slot and SCT dialogs. The Notes Manager dialog enables you to easily see all slots and timesteps with a particular note, for example to easily see all provisional slots and timesteps. See “Notes on Series Slots” in User Interface for details on Notes.

When the Read and display validation character is checked, the Validation field values are also imported through the DMI and set on a Series Slot Note, associated with the particular slot and timestep. The Series Slot Note Group which holds the validation characters is named “HDB Validation Group”. The group's name is fixed; you can't edit it. In the Edit Note Group, the label above the name is Fixed Note Group Name and the name is read-only. You can edit the group's color.

The remainder of the controls for the Real table type are described in this topic.

The Agency ID field specifies what agency ID will be associated with the data when it is written to the real tables. You must select an agency ID by selecting the Select button adjacent to the field. This will bring up the Select HDB Agency ID dialog populated with all the available agency IDs, their names, and abbreviations from the HDB_AGEN table in the database. You can then select an agency, which populates the Agency ID field on the dataset dialog with the ID and name of the agency.

The Collection Sys ID field specifies what collection system ID will be associated with the data when it is written to the real tables. You must select a collection system ID by selecting the Select button adjacent to the field. This will bring up the Select HDB Collection System ID dialog populated with all the available collection system IDs, their names, and comments from the HDB_COLLECTION _SYSTEM table in HDB. You can then select a collection system, which populates the Collection Sys ID field on the dataset dialog with the ID and name of the collection system.

The Use Overwrite Flag check box specifies whether or not data is written to the real tables with an overwrite flag. This flag has some special meaning for how the data is handled in the database, namely that when the value is written to its real table, it cannot be overwritten by aggregations of data from a shorter interval. Normally this box would not be checked.

A selection of Ensemble in the Table Type frame means that any data moved using the dataset will be determined through the REF_ENSEMBLE table in the database. An ensemble has a number of traces associated with it, and each trace has an associated model run ID. An ensemble would be used with MRM so that each run of the multiple run would correspond to a trace in the ensemble, and the data for that trace would reside under the trace’s model run ID in the model (m_ xxxx) set of tables in HDB. See “Ensemble Configuration” in Solution Approaches for details.

The Ensemble ID frame has options for you to Select ID or Select ID when MRM is started. The Select ID option allows you to preselect an ensemble ID to associate with the dataset for reading or writing data with the model tables. You must select an ensemble ID by selecting the Select button adjacent to the ensemble field. This will bring up the Select HDB Ensemble ID dialog populated with all the available ensemble IDs, their names, the agency, the domain for the traces, and comments from the REF_ENSEMBLE table in the database. You can then select an ensemble, which populates the Ensemble ID field on the dataset dialog with the ID and name of the ensemble.

There are two other options for ensemble IDs on the Select HDB Ensemble ID dialog. Instead of just selecting an existing ID, you can also edit an existing ID or create a new one. An existing ID that is displayed can be highlighted and edited by selecting the Edit button at the bottom. This brings up the Edit HDB Ensemble ID dialog, which displays all the information fields for the ensemble id and allows you to edit these fields. Selecting the Save button will then save the edited information for this ensemble ID to the database.

The Create button at the bottom of the Select HDB Ensemble ID dialog allows you to create an ensemble ID. Selecting this brings up the Create HDB Ensemble ID dialog, which contains fields where information can be entered for the new ensemble ID. At least the required fields marked with an asterisk must be filled out. Selecting the Create button at the bottom will then save entered data to the database as a new ensemble ID. The new ID will then be added to the list and highlighted back on the Select HDB Ensemble ID dialog.

It may be convenient to use an ensemble dataset outside of a multiple run to pull a particular trace from the ensemble for use in a single run or to manually test a DMI. Selecting the Select button adjacent to the Trace ID to Use Outside MRM field will open the Select HDB Trace ID dialog that is populated with all the traces for your selected ensemble ID specified for the dataset. The dialog shows descriptive information for each trace from the REF_ENSEMBLE_TRACE table and also information for the trace’s model run ID from the REF_MODEL_RUN table. You can then select a trace, which populates the trace ID into the dataset dialog.

The Ensemble ID frame of the dataset dialog has a second option for specifying ensemble IDs by selecting Select ID when MRM is started. When this option is selected, you do not preselect an ensemble ID that is always used with the dataset, but rather you are prompted for one when an MRM run containing this dataset in an input or output ensemble is started. This option could be useful, for example, where you want to select a different output ensemble for each execution of the multiple run so that data from earlier runs is not overwritten.

Selecting an ID under the Select ID when MRM is started option utilizes the same dialogs as does the preselect ID option. The Select HDB Ensemble dialog appears when you start the multiple run where you can see existing ensemble IDs. An existing ID can then be selected, an existing ID can be edited and then selected, or a new ensemble ID for can be created then selected.

In addition to the ensemble id options discussed above, there is also an option under the Ensemble Configuration frame to select an Agency ID to use when writing. Selecting Select will open the Select HDB Agency ID dialog where one of the agency ids defined in HDB can be chosen. If chosen, that agency id will be written to the dataset’s ensemble when that dataset is executed as part of an output ensemble. If one is not chosen, the behavior will be to preserve any agency id that is already defined in the database for the output ensemble.

An HDB ensemble can have metadata that describe the ensemble as well as metadata that describe each trace. Metadata is a keyword associated with a value, such as “comment”/”Historic Hydrology”. In the HDB database, values for the “domain”, and “comment” keywords are held in the trace_domain, and cmmt fields of the REF_ENSEMBLE table. Other keyword/value pairs to describe ensembles are held in the REF_ENSEMBLE_KEYVAL table.

For trace metadata, the values for the “name” and “numeric” keywords are held in the trace_name and trace_numeric fields of the REF_ENSEMBLE_TRACE table. Other keywords to describe traces are held in the REF_MODEL_RUN_KEYVAL table.

See “Ensemble Configuration” in Solution Approaches for details on using Ensembles in MRM.

Excel datasets provide user configuration options to specify how you wish the Database DMI to work with Microsoft Excel. Excel datasets can only be used on the Windows platform and Excel must be available on the system. RiverWare will start a non-visible copy of Excel in the background and access the specified workbook during DMI execution. As a result, there are two important things to remember:

See “Example 2: Excel DMI to Export Data Using Headers” for a use case of creating a DMI to Excel.

Double-clicking an Excel dataset in the Dataset Manager opens the Excel Dataset editor. In this dialog, the dataset can be renamed and configured. It has two tabs, one for general configuration and one specific to the Excel implementation. Following is a description of the configuration options.

Select the desired Name Map from the Name Map menu. The selections are populated based on the Name Maps configured in the Name Map Manager. See “Name Mapping” for details on creating Name Maps. Name maps have special relevance for moving data using range specifications and header specification. See “Slot Mapping—Spreadsheet Ranges Approach” and “Using Name Maps” for details.

The user specifies how missing values are handled with Excel. The current choices are

The units that are used in interacting with Excel are specified in the Dataset dialog. A pull-down menu allows the user to specify that the Database DMI should Use Database Units, Prefer Database Units, or Use Dataset Units.

See “Units” for instructions on specifying the units to use.

Configuration specific to Excel is specified in the Excel tab of the Excel Dataset editor.

In all cases, the Workbook that the dataset will read data from or write data to must be specified. The path and workbook name can be typed into the Workbook text box, or you can select the adjacent button to select the file. When executing an input DMI, this workbook must already exist. For an output DMI, the workbook will be created if it does not already exist.

Two approaches are provided for mapping data between RiverWare and Excel.

Table 4.3 compares these approaches. Then more information is presented on the configuration options for both the Range and Header approach.

The Map by Spreadsheet Ranges approach presents several options for specifying ranges associated with slots. In all cases, the Name Map functionality of Database DMIs is used to map individual slots to their range specifications. You can map Series, Table, Periodic, or Scalar slots using this approach.

Discussions of the range specification options along with example Name Maps follow.

Under the Map to Excel Named Ranges with Name Map option, the user would set up named ranges in their Excel workbook. Named ranges are a feature of Excel where a number of cells can be selected and assigned a name by the user to identify these cells. The Name Map created in RiverWare and selected in the General tab of the dataset dialog then will associate the RiverWare slot with the named range as seen in the following example name map. In this case, BigResInflow and BigResOutflow are named ranges in the Excel sheet.

In the Map to Excel Range Specifications with Name Map option, there are two ways to specify ranges for slots. If all the ranges for the slots are on the same worksheet, then the Ranges on same worksheet option can be used. Here the worksheet name is specified in the Worksheet text box. Ranges specified in the name map can be of the form B2:B50, meaning the range will be from cell B2 to cell B50 of the specified worksheet. Figure 4.20 shows an example of the type of Name Map created and selected on the General tab of the dataset dialog for this approach.

If ranges for the slots are on different worksheets then the Ranges on different worksheets option must be used. Under this option, ranges specified in the name map must include the worksheet name as part of the range specification in the form Sheet1!B2:B50. In this way, ranges referring to different worksheets can be included in the same name map. Figure 4.21 shows an example of this type of Name Map.

Under all variations of the Map by Spreadsheet Ranges approach, there is an option available to Specify Range Offset for each Run of Multiple Run. In a multiple run, the user may want to read different data into a slot for each run or write out the results for the slot under each run. If the option is checked, the mapped range for the slot is used for the first run, and the specified row and column offset is applied for each run thereafter. For example, the range for a slot specified in the dataset’s name map could be Sheet1!B2:B50 and the offset specified here could be 0 rows and 1 column. For an input DMI in a multiple run, the first run will read range B2:B50 on Sheet1 into the slot, the second run will offset one column and read range C2:C50 on Sheet1, the third range D2:D50, etc. For an output DMI, the slot’s results from the first run will be written to range B2:B50 on Sheet1, results from the second run will offset one column and be written to range C2:C50 on Sheet1, the third to range D2:D50, etc.

The Map by Header Text and Sheet Name approach is the alternative to using ranges to move RiverWare slot data to or from Excel. The approach uses a row header, a column header, and a worksheet name to map Excel data with a RiverWare slot. Figure 4.22 shows an example of the dataset dialog with this configuration selected.

Name maps are not needed in the header approach. However they can be used to map to a different name in Excel. The following is performed for each slot:

When the Series Slots option is chosen, you can specify the format of the series slots in the spreadsheet.

The Header Orientation frame provides four orientation choices for how timesteps, slots, and runs will map to rows, columns, and sheets in Excel. For example, the first orientation as selected in the adjacent screenshot indicates that rows are timesteps, columns are slots, and worksheets are runs.

Figure 4.23 shows an Excel spreadsheet with the first orientation. In this orientation, timesteps are rows, so the timestep header is the first column with a time label for each row. Similarly, the slot header is the first row with each column labeled with the slot name. Sheets are runs, so the sheet is named with the single run name specified in the dialog.With the orientation specified, the data in Excel associated with a slot over a time range can be found for reading via an input DMI, or can be found and overwritten, if existing, or be newly created by writing via an output DMI.

The headers may not always be the first row and the first column. To accommodate these cases, an option is provided to specify how the headers are offset from the corner of the spreadsheet. By indicating how many rows and how many columns the header is offset from the upper left corner of the spreadsheet, the user can match how data resides in an existing spreadsheet or indicate where the headers and data should be written to a new sheet.

When the Table / Periodic / Scalar Slots option is chosen, you are not allowed to specify the format of the slots in the spreadsheet. Instead, there is a very specific format that is used. Figure 4.24 shows a sample workbook. Table slots have a header merged cell for the slot name, cells for column headers, and the columns that contain row headers and data columns. Periodic slots include a column of dates, one or more columns of data, and a header cell. Scalar slots are represented by a header cell and a value cell.

Functionality to import/export Table, Periodic, and Scalar slots from/to Excel has the following limitations:

The Run Name Type options indicate how runs in the Excel workbook will be labeled.

Use one of the following options:

For Series Slots approach, an option is provided to Use Begin Timestep Time Instead of End of Timestep.

Timesteps in RiverWare are dated with the end of timestep time, that is, a 1 Day timestep for the last day of the year 2000 is dated 12/31/2000 24:00. If the begin timestep option is not checked, this date is written to (and is expected to be read from) Excel as 12/31/2000 23:59. A minute is subtracted compared to the RiverWare end of time so that the date appears in the correct month and year in Excel. (Excel has no concept of a 24:00 display, so 12/31/2000 24:00 is interpreted by Excel as 1/1/2001 00:00, which would appear to be the wrong month and year.)

If Use Begin Timestep Time Instead of End of Timestep is checked, then the timestep is written to (and is expected to be read from) Excel as the beginning of timestep in RiverWare. For the above example, the time in Excel would be 12/31/2000 00:00. This option may be particularly useful if the user is entering data into Excel and is typing in 1 Day timesteps as 12/30/2000, 12/31/2000, 1/1/2001, etc., which end up by default with 00:00 hours and minutes in the Excel date format. With the begin timestep option checked, the data associated with these times will be moved into RiverWare for their correct timesteps.

An option is also provided with the header approach to Use Unit Name with Slot Name. In an output DMI, this option will attach the unit name to the slot name when the slot name is written out to its appropriate row, column, or sheet, depending on the orientation selected. The format is the slot name, a space, and the unit name in parentheses, such as Storage Reservoir.Inflow (cfs). In an input DMI, this option means that the DMI will expect the unit name to be attached to the slot name as indicated above when it is looking for the slot in the Excel headers or sheets.

The final part of the Excel DMI tab is the choice of Connection Process as shown in Figure 4.25.

This configurations setting specified how the RiverWare DMI should connect or communicate with the Excel workbook. The two choices are:

It is likely that RiverWare object or slot names do not match their associated database names. For example, the reservoir inflow is called Inflow in RiverWare while in DSS Part C, it is instead called RES-INFLOW. Because different databases use different naming conventions, there is no way for RiverWare to know the database’s naming convention. The name mapping tool provides a tool for the user to specify the link between the two naming systems. The name mapping tool allows the user to define multiple name mappings.

To bring up the name mapping editor from the DMI Manager, the user selects Utilities, then Name Maps.

Double-clicking the newly added Name Map opens the Name Map dialog as shown in the following screenshot. In this dialog, the user is able to edit the name of the Name Map. Selecting Name Map, then New adds a new entry to the list.

Selecting the newly selected entry opens the context menu options shown in Figure 4.26. Either select Select Simulation Object or Select Slot. This action opens the selector dialog for the appropriate selection. In this dialog, the user selects the desired objects or slots that will be part of this Name Map. If accounting is enabled, supplies, accounts, exchanges, and paybacks are also available. Use the filters and wildcards to select generic slots. For example, the user could select Reservoir.Inflow as an entry. See “Creating a Name Map of All Reservoir.Inflow Slots” in User Interface for details on using the selector. The selections made here are considered dynamic root selections. That is, the selection is saved with the model file and is automatically updated if objects or slots are added to or removed from the model. This is especially useful when using wildcards.

To define the data name, in the Name Map manager, select the blank area to the right of the entry under the word Name. This is where the user specifies the database’s variable name for the entry. Figure 4.26 shows an example.

The entries in the Name Map are prioritized with the highest priority first. If there is a conflict between two entries, the entry with the highest priority takes precedence and the other entry becomes disabled with a red X. This means that if there is a red X, there is a higher priority selection that controls the item. For example, in Figure 4.27, the first entry for ResA.Inflow (INFLOW) takes priority over the second entry (RESINFLOW). The green check marks show that the first item is controlling the selection. This functionality allows users the functionality to create a name map in a generic case but redefine it in special case.

The Database DMI utility includes a feature that allows the user to Export and Import the Database DMI configurations. The user is able to export and import Database DMIs, Datasets, and Name Maps. Following are instructions and descriptions of both exporting and importing Database DMI configurations.

To export the Database DMI configuration, the user selects File, then Export Database DMI from the DMI Manager. The Database DMI Export dialog appears.

The user types a file path into the File field or selects an existing file using the browser button.

Once a file is entered and a selection is made, the Export button becomes active. Selecting Export will export the configuration to the file.

Importing a set of configurations is similar to exporting. The user selects the File, then Import Database DMI menu on the DMI Editor to open the Database DMI Import dialog.

The user then selects the items to import. If the item already exists in the model, a small warning sign is displayed. Toggle on the Import conflicts with a unique name button to import the item and give it a new name. In addition, when this option is checked the imported Database DMIs will be modified access any newly imported Datasets and Name Maps that are also imported.

If the checkbox is cleared and there is a conflict, the import will overwrite any existing items of the same name in the model. When the user is satisfied with the selection, selecting Import brings the items into the model.