RdfToExcel Help Information

Table Of Contents

  1. Overview
  2. RDF Files
  3. Excel Workbook
    1. Header Sheet
    2. Data Sheets
    3. Slot Names
  4. Interactive Mode
  5. Batch Mode

Overview

The RdfToExcel tool will take a RiverWare Data Format (RDF) file and convert its contents into an Excel workbook using user-specified configuration options. This is accomplished, in part, by automating Excel on the user's computer, so the tool is Windows only, and the user must have Exce. installed. Since the tool automates whatever version of Excel the user has installed, the tool is not tied any particular version of Excel and its associated workbook format or limitations. The tool can be operated in an interactive mode or in a batch model as discussed later in this document.

RDF Files

RDF files are generated from RiverWare and contain data for slots specified by the user. Non-series slots can be written to RDF files, but only data for series slots will be processed by the RdfToExcel tool for writing to Excel. The exact format of an RDF file is described in the Output and Plotting section of RiverWare Online Help. An RDF file for results from a single run in RiverWare can be created from the Output Manager via a RiverWare Data File device. Slot data for a multiple run in RiverWare can be output to an RDF file by configurations in the Output tab of the MRM Configuration dialog.

Excel Workbook

When an RDF file is written to an Excel workbook, a Header worksheet is created followed by sheets containing the slot data. These are discussed below along with the available slot name options.

Header Sheet

The header sheet contains a summary of the information in the RDF file that is not slot data. This includes:

Data Sheets

The appearance of the data sheets depends on the workbook orientation option selected by the user. A workbook has three "dimensions", rows, columns, and worksheets, that can be mapped to the data dimensions of timesteps, slots, and runs. Typical orientations would be to put timesteps as rows, slots as columns, and runs as sheets, or timesteps as rows, runs as columns, and slots as sheets. In this last orientation, for example, the first column would contain a timestep label  in each row, the first row would contain a run label in each column, each sheet would be labeled as a slot, and cells in the sheets would contain the corresponding timestep data as indicated by the header labels and sheet name.Some orientations are more common, but any of the six possible orientations are available.

Slot Names

Because slot names from RiverWare can be very long, fitting them into the workbook can be problematic, most notably in the case where they are sheet tab labels, which are limited to 31 characters. For this reason, the tool provides three options for writing slot names to the workbook:
Slot index labels are Slot0, Slot1, Slot2, etc. The index names are mapped to the actual slot names on the Header sheet, but the index labels are used in the data sheets.

The full slot names are the object and slot name concatenated. If these are used on sheet tabs, colons are removed because these are not legal characters on tabs. Since the number of characters on tabs is limited to 31, the name is truncated to 30 characters to fit, if necessary, and a '~' is appended to the end to show it is truncated.. If this truncating does not make the name unique with respect to other slot names, a sequential number is prepended to the name to make it unique. Note that the full object slot name is placed into the first cell (A1) of the sheet so the actual slot can be easily determined..

Automatically shortened slot names are shortened according to the following criteria:
As an example, PowellStorage becomes PwllStrg. If the shortened name is used on sheet tabs and it still exceeds 31 characters, it is truncated to 30 characters and a '~' is added to the end to indicate the name is shortened. If the truncated name is not unique with respect to other slot names, a sequential number is prepended to the name to make it unique. The full object slot name is placed into the first cell (A1) of the sheet so the actual slot can be easily determined.

Interactive Mode

Interactive mode is started by double-clicking on RdfToExcel.exe in Windows Explorer or by entering the program name with no arguments at a Command Prompt. This brings up the following dialog:

RdfToExcel Dialog

A source RDF file is indicated by either selecting the file via the file chooser or by typing in the path and file name in the Source RDF File frame of the dialog. When a source RDF file is chosen, the result workbook field is defaulted to an Excel file by replacing the .rdf file extension of the source file with .xlsx. This default file can be changed by using the file chooser or by typing a desired file path into the Result Workbook frame of the dialog. In both of these file paths, environment variables of the form $NAME, for example, can be typed in and the NAME environment variable defined on the system would then be substituted in when the program is run.

The Workbook Orientation frame of the dialog provides a combo box with choices of how the workbook's rows, columns, and worksheets should map to the RDF file's timesteps, runs, and slots. The following choices are available:

Orientation Choices

If slots are selected to go onto worksheets, then the Slot Labels for Sheet Tabs frame of the dialog is visible as shown above. With radio buttons, the user selects which slot name option to use for the worksheet's tab labels.

If slots are not selected to go onto worksheets in the Workbook Orientation combo box, then the Slot Labels for Sheet Tabs frame is not visible, and instead the user gets a checkbox option for naming as shown below:

Slot Name Checkbox

If the checkbox is checked, automatically shortened slot names are used in the header columns or rows, depending on the orientation. This may be desired even though the number of characters are not limited in this situation as in sheet tab labels in order to make the slot names discernible without having to widen the cells so much. If the checkbox is unchecked, the full slot name (object and slot name concatenated) is used in header cells.

Clicking the "Create Workbook" button will then run the program and create the result workbook. If any errors are encountered, they will be displayed as a separate message box. Clicking the "Show Diagnostics" button will bring up a separate dialog where diagnostics and errors from runs are displayed. Clicking the "Help" button will display this help document in a text window. Clicking the "Cancel" button will exit the program.

Batch Mode

RdfToExcel has a batch mode where the program can be executed without invoking the GUI. This can be useful for incorporation into a script that might automatically execute a number of operations in a sequence, including creating an Excel file from an RDF file. Batch mode is initiated by entering the program name with one or more arguments at a Command Prompt. The following shows its usage along with valid arguments and their description:

Usage:  RdfToExcel <-i file> <-o file> <-l file> <-a number> <-n name> <-h> <-v>
-i: This specifies the input rdf file (required).
-o: This specifies the output Excel workbook (required).
-l: This specifies the log file for messages.
    (will default to the workbook file name plus a .log file extension)
-a: This number specifies the arrangement of the result workbook as follows:
    0 - Rows = Timesteps Columns = Slots     Sheets = Runs
    1 - Rows = Timesteps Columns = Runs      Sheets = Slots (default)
    2 - Rows = Slots     Columns = Timesteps Sheets = Runs
    3 - Rows = Slots     Columns = Runs      Sheets = Timesteps
    4 - Rows = Runs      Columns = Timesteps Sheets = Slots
    5 - Rows = Runs      Columns = Slots     Sheets = Timesteps
-n: This specifies the slot naming option:
    Full  - Full Object.Slot name 
    Short - Automatically shortened Object.Slot name (default)
    Index - Index name of Slot0, Slot1, Slot2, etc.
-h: This will print help information.
-v: This will print the version number.

Examples:

1)  RdfToExcel.exe -h
Entering this on the command line will bring up a console window that displays the usage and argument information presented above. The console can be exited by pressing any key.

2)  RdfToExcel.exe -v
This prints out the version number of the RdfToExcel program to a console window that can then be exited by pressing any key.

3)  RdfToExcel.exe -i C:\Temp\Test.rdf -o C:\Temp\Test.xlsx -l C:\Temp\Test.log -a 0 -n Full
This represents a full specification for creating a workbook named Test.xlsx from an RDF file named Test.rdf. The input (-i) and output (-o) arguments are required. Informational messages and any error messages from the run will be written to the specified Test.log file. If the -l  argument is not specified, the log file will default to the workbook file name plus a .log file extension. Note that environment variables of the form $NAME, for example, can be typed in any of the file paths, and the NAME environment variable defined on the system would then be substituted in when the program runs. The -a arrangement argument of 0 specifies that rows will be timesteps, columns will be slots, and worksheets will be runs. If the -a argument is not provided, the arrangement will default to 1, meaning rows as timesteps, columns as runs, and worksheets as slots. The -n name argument is specified to use the full object slot name where used in data sheets (in this case in column header cells). If not specified, the name option will default to be automatically shortened slot names.