XML Data Source

 The XML data source allows data to be delivered via the standard RTView XML schema. In many cases, this is used in prototyping since data can be created via a simple XML text editor. In other cases, customers use the XML format as a quick means for new data sources to provide data to RTView.

An API is provided for creating custom data adapters that can be integrated into the Display Builder environment and provide unique dialogs for data attachment. However, in some cases it is quicker and sufficient to provide the data via XML and use the standard XML data attachment dialog.

This section includes:

§        “XML System Requirements and Setup” on page 806

§        “Attach to XML Data” on page 807

§        “XML Data Source Substitutions” on page 813

§        “Application Options - XML” on page 814

§        “RTView Deployment - XML” on page 816

§        “XML Demos” on page 817

§        “Creating XML Sources” on page 820

§        “XML Data Source Command Line Options” on page 827

XML System Requirements and Setup

System Requirements

The XML data source has no additional “System Requirements”.

Setup

The XML data source requires no additional “Setup”.

Attach to XML Data

The Attach to XML Data dialog, which is used to connect an object property to an element in your XML data, can be accessed from the Object Properties window. Once a property has been attached to an XML element, it receives continuous updates.

When an object property is attached to data, the Property Name and Value in the Object Properties window will be displayed in green. This indicates that editing this value from the Object Properties window is no longer possible. To remove the data attachment, and resume editing capability in the Object Properties window, right-click on the Property Name and select Detach from Data. You will recognize that an object property has been detached from the data source when the Property Name and Value are no longer green.

Right-click on the Property Name from the Object Properties window and select Attach to Data>XML to display the Attach to XML Data dialog. The Attach to XML Data dialog provides three drop down menus that allow you to specify information regarding an XML element. See “Creating XML Sources” for technical details on creating and formatting an XML source.

The XML Source drop down menu lists all available XML sources. Drop down menus for Data Key, Column(s), and Filter Column populate based on the selected XML source. The XML Source field automatically displays the name of the default XML source. The Column(s) and Filter Column drop down menus will only contain options if the selected Data Key is a tabular element that has been included in an XML update. If the item you require is not listed, type your selection into the field. For information on adding XML sources or selecting a default XML source, see “Application Options - XML”.

Validation Colors

Fields in the dialog change colors according to the information entered. These colors indicate whether or not information is valid. Information entered into the dialog is validated against elements included in an XML update.

The following describes the significance of the Attach to XML Data validation colors:

*If an XML source is validated as Unknown, RTView will attempt to read it when you click OK or Apply.

Substitutions

Substitutions allow you to build open-ended displays in which data attachments depend on values defined at the time the display is run. Generic names, such as $data1 and $data2, are used instead of values for specific data keys. Later when the display is running, these generic values are defined by the actual names of specific keys, such as element1_data and element2_data. In this way, a single display can be reused to show data from a number of different sources. For more information on creating displays using substitution values, see “Substitutions”.

RTViewDs

The RTViewDs source provides information about the listeners currently active in the XML data source. The RTViewDs.Server source provides information about all listeners that a data server is currently maintaining for all of its clients. That is, while the RTViewDs.Server source provides information from a data server about all listeners from all of its clients, the RTViewDs source only provides information about listeners that the current client (e.g. Display Builder, Display Viewer) has redirected to data servers.

In the Attach to XML Data dialog, manually enter RTViewDs or RTViewDs.Server in the XML Source field. These options are not available from the drop down list.

Select Table Columns

From the Attach to XML Data dialog you can specify which table columns to display and in what order they will appear. In order to populate the listing of available columns, you must first select a valid XML source and data key.

Click on the ellipses button in the Column(s) field (or right-click in the Column(s) field and choose Select Columns) to display the Select Columns dialog. The dialog should contain a list of Available Columns that you can add to your table.

To add a column, select an item from the Available Columns list and click the Add button. If the item you require is not listed, type your selection into the Enter Column Name field. Click the Remove button to delete an item previously added to the Selected Columns list. You can control the order of columns in a table by arranging the items in the Selected Columns list with the Move Up and Move Down buttons.

Validation colors indicate whether selected columns are valid. However, if even one column selected is invalid, the Column(s) field in the Attach to XML Data dialog will register as an invalid entry.

Note: Invalid columns will not update.

If no data is available for a table row within a selected column, the table cell will display one the following values: N/A, false, 0, or 0.0.

The following describes the Attach to XML Data dialog commands:

XML Data Source Substitutions

In addition to standard built-in “Substitutions”, this data source also sets the following drill down substitutions:

Application Options - XML

Select Tools>Options in the Display Builder to access the Application Options dialog.

Options specified in the XML tab can be saved in an initialization file (OPTIONS.ini). On startup, the initialization file is read by the Display Builder, Display Viewer, Display Server, Data Server and Historian to set initial values. If no directory has been specified for your initialization files and OPTIONS.ini is not found in the directory where you started the application, then RTView will search under lib in your installation directory. See “RTV_JAVAOPTS” for more information.

Note: Options specified using command line arguments will override values set in initialization files.

XML Tab

This tab allows you to allows you to add or remove XML sources, set the default XML source, and enter an XML source prefix.

Adding an XML source allows you to associate a name, which you will use when creating data attachments, with the full path to the XML source file used to update objects in your display. See “Creating XML Sources” for technical details on creating and formatting your own XML source file.

Entering an XML source prefix allows you to use the same path for several XML sources. The XML source prefix will be affixed to the beginning of all XML sources with the Use XML Source Prefix check box selected in the “Edit XML Source” dialog.

Once you add an XML source, it will be highlighted in yellow indicating that it has not been read. When you click OK, Apply, or Save, RTView will attempt to read it and populate menu items in the Attach to XML Data dialog unless the XML source definition has the Contains Substitutions check box selected. If the XML source remains yellow, the file was not found. When this information is saved to the initialization file, it will be used to populate Attach to XML Data dialog menus each time you run RTView.

Edit XML Source

When you add an XML source, the name you create (e.g., MyXMLSource) will be associated with the full path to the XML source file (e.g., mydata/update.xml) being used to update objects in your display.

RTView Deployment - XML

This section contains details about the deployment process that are specific to your data source. Please go to the “Deployment” section of this documentation for instructions on how to implement your RTView deployment option. Return to this page whenever you are instructed to refer to deployment information that is specific to your data source.

System Requirements and Setup

The XML data source has additional System Requirements and Setup. See “XML System Requirements and Setup” for more information.

Data Source Configuration File

RTView saves general application settings as well as data source configuration options in initialization files that are read at startup. If no directory has been specified for your initialization files and files are not found in the directory where you started the application, then RTView will search under lib in your installation directory. See “Application Options”, “Application Options - XML”, and “RTV_JAVAOPTS” for more information.

Include the following initialization file when you deploy RTView with this data source:

Note: Options specified using command line and applet parameters override values set in these initialization files.

Rich Client Browser Deployment Setup for Direct Data Connection

Required Applet Parameters

No additional applet parameters are required for this data source. If you have not already, please review the basic applet parameters required to host the Display Viewer Applet. See “Rich Client Browser with Direct Data Connection - Manual Setup” for more information.

Optional Applet Parameters

The following options are read from OPTIONS.ini if not included in the applet parameters of your HTML file.

Setup Client

No additional client setup is required for this data source.

XML Demos

Except where noted, all demos can be run in three ways, as an application, or via rich or thin client in a browser.

Before You Begin

Start the Demo Server 

Rich Client and Thin Client Demos only. 

There are rich and thin client demos already installed on the “RTView Demo Server”.

In an initialized command window (see “Initializing a Command Prompt or Terminal Window”):

Type run_startup_demoserver 

Data Source Demo

The Data Source Demo is designed to illustrate each data source.

1.     Start the Simulators 

Start the simulators for each data source you will be using. To run the XML “Data Simulator”:

In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/dstutorial directory and:

type run_simdata

2.     Run Demos - Application, Rich Client Browser, or Thin Client Browser

Application Demo 

1. In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/dstutorial directory.

2. To view the demo, type:

run_viewer 

3. To edit the demo, type:

run_builder 

Rich Client Browser Demo

“Start the Demo Server” if it is not running.

1. In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/dstutorial directory.

2. Start the Data Server by typing:

run_dataserver -socket 

3. In the Data Server dialog, select:

Start Serving Data

4. Open a browser and navigate to http://localhost:8068/dstutorial_applet.

Thin Client Browser Demo 

“Start the Demo Server” if it is not running.

1. In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/dstutorial directory.

2. Start the Display Server by typing:

run_displayserver

3. Open a browser and navigate to http://localhost:8068/dstutorial.

Features Demo

Presents an overview of the many features of RTView.

Application Demo 

1.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/features directory.

2.     Start the simulator by typing:

Windows: start run_simdata

UNIX: run_simdata &

3.     To view the demo, type:

run_viewer

4.     To edit the demo, type:

run_builder

Rich Client Browser Demo 

“Start the Demo Server” if it is not running.

1.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/features directory.

2.     Start the simulator by typing:

Windows: start run_simdata

UNIX: run_simdata &

3.     Start the Data Server by typing:

run_dataserver -socket

4.     In the Data Server dialog select:

Start Serving Data

5.     Open a browser and navigate to http://localhost:8068/features_applet.

Thin Client Browser Demo 

“Start the Demo Server” if it is not running.

1.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/features directory.

2.     Start the simulator by typing:

start run_simdata

3.     Start the Display Server by typing:

run_displayserver &

4.     Open a browser and navigate to http://localhost:8068/features.

Geothermal Demo

A real-time operational application that allows you to drill down to various levels of detail.

Application Demo 

1.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/geothermal directory.

2.     Start the simulator by typing:

Windows: start run_simdata

UNIX: run_simdata &

3.     To view the demo, type:

run_viewer

4.     To edit the demo, type:

run_builder

Rich Client Browser Demo

“Start the Demo Server” if it is not running.

1.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/geothermal directory.

2.     Start the simulator by typing:

Windows: start run_simdata

UNIX: run_simdata &

3.     Start the Data Server.

type run_dataserver -socket

4.     In the Data Server dialog:

select Start Serving Data

5.     Open a browser and navigate to http://localhost:8068/geothermal_applet.

Thin Client Browser Demo

Start the Demo Server if it is not running.

1.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), go to the demos/geothermal directory.

2.     Start the simulator by typing:

Windows: start run_simdata

UNIX: run_simdata &

3.     Start the Display Server by typing:

run_displayserver

4.     Open a browser and navigate to http://localhost:8068/geothermal/panels.jsp.

Creating XML Sources

Creating and Formatting XML Data

To attach an object property to XML data element, you will need to specify the XML source, data key and, if the element is tabular, column(s). The XML source is the name, including path, of the XML source file that will be used to update the object.

Note: XML source file names cannot contain spaces. RTView does not limit the number of XML source files you may create. Within each XML source file, you must format your data using the “Supported Tags and Attributes” in the table below.

In order to display your application data in RTView, have your application create an XML source file using the supported tags. Each time you would like to update an XML data element, your application must output an updated copy of the XML source file.

Note: Do not directly edit XML source files. This will cause errors if you are writing to the file while RTView is attempting to read it. When creating or updating XML source files, create a temporary file, write your XML data into it, and then rename the temporary file to the XML source file name. If your XML source file contains non-English characters, you must use UTF-8 encoding.

When an XML source file is added, either from Application Options or directly in the “Attach to XML Data” dialog, RTView will populate Attach to Data drop down menus based on that XML source file. If you specify (or modify) an XML source using the Application Options dialog, you may specify whether that XML source is static. Static XML sources are only read once each time you run RTView.

Data Elements: Scalar and Tabular

There are two types of data elements that you may include in an XML source: Scalar and Tabular.

A Scalar data element is a single value element. The data value can be a string, an integer or a double. Here is an example of how to format a Scalar data element in your XML source:

<data key="element1_data" value="10" />

If this example was included in an XML source file named update.xml, you would select the following options from the Attach To Data drop down menus to connect an object property to this data element:

Once you Apply this data attachment, the attached object will update with the value "10".

A Tabular data element contains multiple columns and rows of data. The value for each field can be a string, an integer, a double, or a boolean. Tabular data elements are useful for updating Table and Graph objects in RTView. Each time you update tabular data in your XML source, you must include all of the column and row information. Here is an example of how to format a Tabular data element in your XML source:

<table key="production_table">

        <tc name="Plant"

                 type="string"

                index="true" />

        <tc name="Units in Production"

                 type="int"

                index="false" />

<tr name="PID 0">

       <td>San Francisco</td>

       <td>99</td>

</tr>

<tr name="PID 1">

       <td=San Jose</td>

       <td=75</td>

</tr>

</table>

All of the table columns must be specified before you specify any row data. The order of the table data elements in each row should correspond to the order of your columns. For example, if the first column you specified was a boolean, then the first field you add to each row must contain a boolean value.

If this example was included in an XML source file named update.xml, you would select the following options from the Attach To Data drop down menus to connect an object property to the Plant column in this data element:

Once you Apply this data attachment, the attached object will update with the value San Francisco.

Supported Tags and Attributes

The following tags and attributes in XML data files are supported:

An example XML data file:

<?xml version="1.0"?>

<dataset xmlns="www.sl.com" version="1.0">

   <data key="element1_status" value="completed" />

   <data key="element2_status" value="broken" />

   <data key="element1_load" value="0.0" />

   <data key="element2_load" value="1102.0" />

   <table key="trade_table">

            <tc name="Customer"

                     type="string"

                    index="true" />

            <tc name="Symbol"

                     type="string"

                    index="false" />

            <tc name="Shares"

                     type="int"

                    index="false" />

            <tc name="Purchase Price"

                     type="double"

                    index="false" />

            <tc name="Current"

                     type="double"

                    index="false" />

            <tc name="High"

                     type="double"

                    index="false" />

            <tc name="Low"

                     type="double"

                    index="false" />

           <tr name="TID 0">

                   <td>Alice Chen</td>

                   <td>IBM</td>

                   <td>18</td>

                   <td>44.7</td>

                   <td>27.5</td>

                   <td>177.5</td>

                   <td>17.5</td>

           </tr>

           <tr name="TID 1">

                   <td>Betty Jones</td>

                   <td>CVTX</td>

                   <td>19</td>

                   <td>32.0</td>

                   <td>10.8</td>

                   <td>160.8</td>

                   <td>0.8</td>

           </tr>

          <tr name="TID 2">

                   <td>Chris Smith</td>

                   <td>AWE</td>

                   <td>61</td>

                   <td>98.6</td>

                   <td>4.1</td>

                   <td>154.1</td>

                   <td>0.1</td>

           </tr>

   </table>

</dataset>

Data Simulator

A sample data simulator is provided to allow you to work with RTView without setting up your own XML data. The simulator creates and updates a group of data elements according to information specified in a data file. These data elements are given initial values and output to the init.xml initialization file. Once every update period the values for these data elements are updated and output to the update.xml update file.

From an initialized terminal window (see “Initializing a Command Prompt or Terminal Window”) type:

run_simdata 

By default, the update period is set to 2000 milliseconds (2 seconds) to match to default update period for RTView. To change the update period, you must run the XML simulator from a command prompt or terminal window and specify the desired rate on the command line using -u. For example, the following will set the update period to 1 second:

run_simdata -u1000 

The data simulator outputs the following values:

Additionally, the simulator will output the following data keys when using the default data file:

You may create your own data file for use with the simulator; however, tabular data cannot be generated from a data file.

Use the following syntax to create custom data files:

From the command line, specify the name of the custom data file for the simulator to use:

run_simdata mydatfile 

An example data file:

step50_75                step 50 75 50 1

step0_100                step 0 100 0 1

step0_50by2.5          step 0 50. 0 2.5

step0_100by5.0        step 0 100. 0 5

step-10_150.0           step -10 150 -10 1

random0_100            random 0 100

random0_100.0         random 0 100.

step_100                  step 0 100

step_circ_50_200.0   step_circ 50 200.

XML Data Source Command Line Options

In addition to general options, the following command line arguments are enabled with the XML data source when you run RTView applications from a Windows Command Prompt or UNIX terminal window. See “Command Line Options: Display Builder and Display Viewer” for more information.

Note: If a command line argument contains a space or a semicolon, then the entire argument must be enclosed in quotes (e.g.: "-sub:$data:my Data").