Note: The RTVPipe data source may not be licensed in your RTView installation.
The RTVPipe data adapter supports data attachments that launch an external process, reads the text output of that process and converts it into a string or a data table for use within RTView.
The external process can be any executable program or script that writes lines of text to its standard output stream. The connection between RTView and the output stream of the process is referred to as a "pipe". The RTVPipe data adapter uses a Java class known as a "pipe handler" to parse the output it reads from the process.
For more sophisticated conversions it is possible to create a custom RTVPipe Handler. See “Customization - RTVPipe Handler” for details.
System Requirements and Setup - RTVPipe
The RTVPipe data source has no additional “System Requirements”.
The RTVPipe data source requires no additional “Setup”.
Note: The RTVPipe data source may not be licensed in your RTView installation.
The Attach to RTVPipe Data dialog, which can be accessed via the Object Properties window, is used to specify the Command String to be executed by the pipe adapter and select the Handler to process the output.
Right-click on the Property Name from the Object Properties window and select Attach to Data>RTVPipe to display the Attach to RTVPipe Data dialog. The Attach to RTVPipe Data dialog provides several drop down menus that allow you to specify information. The RTVPipe adapter will connect to the output stream of the external process created by executing the specified Command String and send the lines of text from that stream to the selected Handler. Drop down menus for Column(s) and Filter Column populate based on the selected Handler. If the item you require is not listed, type your selection into the field.
|
Field Name |
Description |
|
Command String |
Enter the Command String to be executed by the RTVPipe adapter. This value can contain substitutions. The specified command string must be executable on the host on which the pipe adapter is running. § On Windows, this means the command string must specify an .exe file (e.g. cmd.exe /c x.bat) to run the x.bat script file. § On UNIX, this means the command string must specify an executable program or shell script. In all cases the launched process must write lines of text to its output stream. |
|
Handler |
Select the name of a Handler. Two generic built-in handlers are available, as well as any custom handlers defined on the “RTVPipe Handlers Tab” of the Application Options dialog. RTView Generic Text Handler - Converts process output into a multi-line text string. RTView Generic Table Handler - Converts process output into a single-column table with one row per line of output. Note: A unique instance of the handler class will be created for each unique pipe (i.e. each unique data attachment). |
|
Handler Hints |
Enter string of hints to be passed to the Handler. Note: The syntax of this string is determined by the selected Handler. If the selected Handler does not support hints this field is not visible. Note: The built-in generic handlers do not support hints. |
|
Run Mode |
Select from the following to specify what action the RTVPipe adapter should take once the pipe's process is complete. Once -- Do not re-execute command string. Note: This mode is useful for an on-demand reading of, for example, a complete error log file. Periodic -- Re-execute the command string after waiting the number of seconds specified in the Interval field. Note: This mode is useful for periodically reading an updating log file via a command such as cat or tail (without the -f/-F option). Continuous -- Re-execute the command string immediately. Note: This mode is useful for reading an updating log file via a continuous command such as tail -F. |
|
Interval |
Enter the duration (in seconds) to wait before re-executing the command string once the pipe's process is complete. Note: This field is only visible when the Run Mode selected is Periodic. |
|
Timeout |
Enter the duration (in seconds). If no output is read from the process in the specified timeout period, the process will be restarted. Default is 0, indicating no timeout. Note: This field is only visible when the Run Mode selected is Continuous. |
|
Column(s) |
If the specified Handler returns tabular data, then select which column(s) to display. To bring up the Select Columns dialog, click on the ellipses button |
|
Filter Rows |
Check box to indicate whether or not to filter the RTVPipe data. See “Row Filtering” for more information. |
|
Filter Column |
Name of the column to use as a filter. Multiple column names should be entered as a semicolon (;) delimited list (i.e. col1;col2;col 3). If your column name contains a space or a semicolon, then the entire name must be enclosed in single quotes. |
|
Filter Value |
Value that the Filter Column must equal. Multiple filter values should be entered as a nested list, where values for a given column are separated by commas within a semicolon (;) delimited list (i.e. val1,val2;val3,val4;val5,val6). If your filter value contains a space or a semicolon, then the entire value must be enclosed in single quotes. When * is entered as a filter field value, data for all values in the specified filter column will be used to update the object property. When "*" is entered, only the literal comparative value will be used. |
|
Data Server |
Select to read data through your configured Data Server and not directly from the RTVPipe data source. Default - Select the default Data Server you configured in Application Options>“Data Server Tab” None - Bypass data being redirected through the specified data server(s) for this attachment and instead attach directly to the data source. Named Data Servers - Select a Named Data Server that you configured in Application Options>“Data Server Tab”. Multi-Server Attachment - To configure multiple data servers, enter a semicolon (;) delimited list containing two or more Named Data Servers (e.g. ds101;ds102). Each name specified must correspond with a Named Data Server that you configured in Application Options>“Data Server Tab”. It is also possible to specify __default and __none (e.g. __default;ds101;ds102). Note: The values __default and __none begin with two underscore characters. |
|
|
Alternatively, a value of * can be entered to specify all data servers, including __default and __none. When multiple data servers are specified, the data attachment will be directed to each data server in the list. For tabular data attachments, a column named DataServerName will be added as the first column of the table and contain the name of the server from which the data was received. |
|
|
A multi-server attachment will receive data independently from each of the servers it specifies, so in most cases it will be necessary to combine the tables received into a single table. This can be accomplished in two ways: 1. The multi-server attachment can be applied to a local cache that has the DataServerName column specified as an index column. The current table of that cache will contain the combination of the tables received from all servers. Note: It may also be necessary to configure cache row expiration settings to remove defunct rows. 2. The multi-server attachment can be applied as the Table argument of the RTView function named Combine Multi-Server Tables. See “Tabular Functions” for more information. |
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. Once a property has been attached to data, it receives continuous updates. 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.
Fields in the dialog change colors according to the information entered. These colors indicate whether or not information is valid.
The following describes the significance of the Attach to RTVPipe Data validation colors:
|
Blue |
Unknown |
Cannot validate entry.* |
|
White |
Valid state |
Entry is valid. |
*If a Handler is validated as Unknown (i.e. specified handler class cannot be loaded), RTView will attempt to validate it when you click OK or Apply.
The Substitutions feature allows you to build open-ended displays in which data attachments depend on values defined at the time the display is run. A generic name such as $path is used instead of a specific command string. Later when the display is running, this generic value is defined by the actual command string, such as tail -f $path. 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”.
If the value RTViewDS.Pipes is entered in the Command String field, the Handler and Run Mode fields will be hidden in the data dialog and an internal table of pipe process metrics will be applied to the listener. The RTViewDS.Pipes table will contain one row for each unique combination of Command String and Run Mode that are currently active in the pipe data source. The columns in the table are as follows:
|
|
RTViewDs |
|
|---|---|---|
|
RTViewDs.Pipes |
Column Available |
Description |
|
Command String |
Command string executed by the pipe. |
|
|
Mode |
Run Mode for the command string. If the selected Run Mode is Periodic, the interval is also shown in this column. |
|
|
State |
Current state of the external process, either running or exited. |
|
|
Runs |
Total number of times command string has been executed. |
|
|
References |
Number of handlers that are currently using this pipe. |
|
|
Total Lines Read |
Total number of lines read from all runs of the command. |
|
|
Last Read Time |
Last (most recent) time at which a line of input was read from the pipe. |
|
|
Last Line |
Last line read from the pipe. |
You can specify which table columns to display and in what order they will appear using the Attach to RTVPipe Data dialog.
To display the Select Columns dialog, click on the ellipses button 
in the Column(s) field (or right-click in the Column(s) field and choose Select Columns). 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 on 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 RTVPipe 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 RTVPipe Data dialog commands:
|
Command |
Description |
|
OK |
Applies values and closes the dialog. |
|
Apply |
Applies values without closing the dialog. |
|
Reset |
Resets all fields to last values applied. |
|
Clear |
Clears all fields. Detaches object from data source (once Apply or OK is selected). |
|
Cancel |
Closes the dialog with last values applied. |
Select Tools>Options in the Display Builder to display the Application Options dialog.
Options specified in the RTVPipe Handlers tab can be saved in an initialization file (RTVPIPEOPTIONS.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 RTVPIPEOPTIONS.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. See “Command Line Options - RTVPipe” for more information.
The RTVPipe Handlers tab in the Applications Options dialog allows you to define custom pipe handlers created to parse the output of specific programs or scripts. See “Customization - RTVPipe Handler” for more information.
|
Field Name |
Description |
|
Default Handler |
Select a default Handler from the drop down list. |
|
Add Handler |
Click to open the Add RTVPipe Handler dialog and define a custom handler. To edit an existing Handler, double-click on a name from the Handlers list. |
|
|
Handler Name -- Enter unique name for this handler. This name will appear in the Handler drop down menu of the Attach to RTVPipe Data dialog. |
|
|
Java Class -- Enter the fully-qualified name (Java package name + class name) for the class that implements this handler. You must add this Java class to the “RTV_USERPATH” environment variable. |
|
Remove Handler |
Select a name from list and click Remove Handler to delete. |
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.
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 - RTVPipe”, and “RTV_JAVAOPTS” for more information.
Include the following initialization file when you deploy RTView with this data source:
|
File Name |
Description |
|
RTVPIPEOPTIONS.ini |
Contains general options as well as data source options for RTVPipe. |
Note: Options specified using command line and applet parameters override values set in these initialization files.
Command Line Options - RTVPipe
In addition to General Options, the following command line arguments are enabled with the RTVPipe 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").
|
Name |
Description |
|
-rtvpipetrace |
Set to 1 to enable message tracing. Default is 0 and tracing is disabled. Example: -rtvpipetrace:1 |
in the