DateTime Values in Slots
In addition to the standard unit types (Flow, Length, Volume, and so on) that can be configured on custom slots. It is possible to add slots that have values in the slot that represents a DateTime. This is possible by configuring the slot to have a DateTime unit type. Following is a walk through describing how to add a slot with a DateTime value. Following that is a description of each of the date times and a description of how to use the values in RPL.
Adding a Slot with DateTime Values
To introduce how DateTime values exist on RiverWare Slots, this section walks the user through the process of creating a series slot with DateTime values on a data object.
1. Create a Data Object and Add a Series Slot, or any of the following types of Slots. All of the following support DateTime values:
– Series Slot
– AggSeries Slot
– Table Slot
– Scalar Slot
2. From the object dialog, double-click your new Series Slot to show the Open Slot dialog or Slot Viewer.
3. From the View menu, select Configure to open the Series Slot Configuration dialog box.
4. In the Series Slot Configuration dialog box, from the Unit Type option, select the DateTime item.
Note: The “DateTime” Unit Type, and the eight supported DateTime User Units are special in RiverWare. These selections cause the Slot’s values to be displayed and edited as DateTime values rather than as numeric values.
Unlike switching between ordinary Unit Types, switching to the “Date Time” Unit Type, and between the various DateTime “User Units” causes a change in the underlying Slot values. The user must confirm these changes with this dialog.
5. As a result of switching to the DateTime Unit Type and selecting Apply, configuration properties associated with only numeric values are hidden (e.g. Min/Max values, Display Format, Convergence).
Notice the eight different “User Units” associated with the DateTime Unit Type. You can keep the default selection, FullDateTime. Select OK.
Note: AggSeries Slots and Table Slots support independent Numeric / DateTime configuration on each column.
6. As a result of selecting a DateTime unit, the Edit Date/Time Slot Values area is added to the Open Slot dialog.
Figure 4.48
The entry and selection fields shown within the Edit Date/Time Slot Values area depend on which DateTime User Unit selection was made. For the FullDateTime selection, two alternative entry modes are available, selectable with the checkbox on the left.
– Timestep selector. For DateTimes on Timestep Boundaries; see Figure 4.48.
– Unconstrained Date/Times. For selection of any DateTime within the supported RiverWare date range; see Figure 4.49.
7. Try making different cell selections, selecting the Apply button and repeating these steps with different DateTime entry values.
Notice that the Value field at the top of the Open Slot dialog is disabled (not editable, and shown with a gray background). This field shows the actual internal numeric value associated with the selected cell’s DateTime value.
Figure 4.49
Double-clicking a cell assigns the cell’s value to the Edit Date/Time Slot Values area.
When a range of cells is selected with the first and last cell having valid values, interpolated DateTimes can be assigned to the intervening cells. Try Edit, then Interpolate (not illustrated here).
Plotting of DateTime value series is also supported. (Select the Plot icon on the right side of the dialog). DateTime coordinates are not shown on the axes, but relative DateTime “magnitudes” can be discerned.
DateTime values that do not conform to the Slot’s (or Slot column’s) configured DateTime “units” (Partial DateTime configuration) are shown with a yellow cell background. In addition, a value that is Not a Number (NaN) is shown with the syntax DT NaN.
Partial DateTime Editor
The Partial DateTime Editor in the Open Slot dialog also shows the applied DateTime. Table 4.3 shows this dialog in standard numeric configuration and in the various Full and Partial DateTime configurations. The screenshots shown are for a Scalar slot but they are applicable to the other supported slots as well.
DateTime User Unit | Example | Selection Mechanism |
|---|---|---|
Full DateTime | 18:00 May 16, 2007 | Timestep selector  Unconstrained Date/Times  |
Month | January | Month menu  |
Month and Day | January 1st | Month and Day menu  |
Time of Year | 24:00 Jan. 1 | Hour, Month, Day menu  |
Day of Month | 1st | Day of Month menu  |
Time of Month | 24:00 1st | Hour and Day of Month menu  |
Time of Day | 24:00 | Hour menu  |
Year | 2000 | Year selector  |
Access to DateTime Values Using RPL
RPL doesn’t directly support DateTime Slot values as DATETIMES. All Slot values are handled as numeric values. Two Predefined RPL Functions are used to convert the Slot DateTime values to and from RPL DATETIME values. Figure 4.50 and Figure 4.51 demonstrate the use of the DateToNumber and NumberToDate Predefined functions. The following sections provide more information about these predefined functions.
Figure 4.50
Figure 4.51
See the following documents for details:
• DateToNumber. Converts a DATETIME to the corresponding number. See DateToNumber in RiverWare Policy Language (RPL) for details.
• NumberToDate. Converts a number to a corresponding DateTime. See NumberToDate in RiverWare Policy Language (RPL) for details
Note: Only DATETIMES with the FullDateTime unit should be set on slots with rules. Due to the numeric values underlying DATETIME values, trying to set partial DATETIME value with rules can have unintended behavior.
Conversion of DateTimes to Numeric Values
Although rare, you may need to see the value that is stored on the slot. Use the Unit Converter and the DateTime unit type for this purpose. See Converting DateTime Values to Numeric Values for details.
Revised: 07/03/2024