Overview

Field Name

Description

Add

To add a new cache, click Add and enter a cache name and select a cache type. Once you have added a cache, select that cache from the list and edit properties in the Object Properties dialog.

Cache Name - Enter a unique name for each cache listed. Caches that do not specify a name, as well as caches with a duplicate names, will not be created and an error will print to the console.

Cache Type - Choose a type of cache from the drop down menu (“Table Cache” or “Double Cache”).

Copy

Select a cache from the list and click Copy to create a duplicate of that cache.

Note: You must enter a unique name for each copy you make.

To copy a cache from your current display to another display (.rtv) file, select a cache from the list and click the Copy button  in the toolbar (or Ctrl-C). Then open the other display (.rtv) file and click the Paste button  (or Ctrl-V). If a cache by that name already exists in that display (.rtv) file, you will need to rename the cache.

Note: A cache pasted into another display (.rtv) file will have the same data attachments as the original cache.

Remove

Select a cache from the list and click Remove to delete.

Display Content

Select a cache from the list that is attached to data and click Display Content to view the contents, as well as the number of columns and rows, in the attached current and/or history table(s).

List All Caches

Select to view caches from all display (.rtv) files and included files. See “Include Display Files” for more information.

Note: Only properties for caches defined within the current display (.rtv) file can be modified.

cacheName

A unique name for the cache. An entry for this property is required. Caches that do not specify a cacheName, as well as caches with duplicate cacheName properties, will not be created and an error will print to the console.

Substitutions defined in a Cache Definition File allow the same file to be specified multiple times with different sets of substitutions. Note that each cacheName defined in that file should contain a substitution, since cache names must be unique. See “Application Options -- Caches” for more information.

Substitutions must use the following syntax:

$subname:subvalue $subname2:subvalue2

If a substitution value contains a single quote, it must be escaped using a / :

$filter:Plant=/'Dallas/'

If a substitution value contains a space, it must be enclosed in single quotes. Do not escape these single quotes:

$subname:subvalue $subname2:'sub value 2'

A substitution string cannot contain the following:

: | . tab space , ; = < > ' " & / \ { } [ ] ( )

description

Enter descriptive text which is displayed in the Description column of the Caches table.

indexColumnNames

Enter a semicolon (;) separated list of column names from the attached valueTable to be used as index columns.

timestampColumnName

Specify the name of a timestamp column. If the specified timestampColumnName is not found in the incoming data, a column will be inserted and each row will contain the time that row was received.

queryServerName

Specifies the name of the Data Server to use to perform the initial SQL query to preload the cache's tables, and also to perform any Extend-by-SQL queries for data attachments to the cache. By default, the value of the property is blank, which means that the SQL queries are performed by the local application.

Note: SQL queries are only performed if the cache's historyTableName or currentTableName properties specify a database table name.

updateListenersImmedFlag

If selected, then each time new data is stored in the cache the updated contents of the cache's tables are immediately applied to any listeners attached to those tables. This is the default setting and is appropriate for most caches.

If deselected, the updated contents of the cache's tables are not applied to the listeners immediately after new data is stored in the cache. Instead the listeners are updated on the next RTView update cycle; default is 2 seconds. In very specific conditions, this can improve the performance of the Data Server. For example, in a case where the cache is maintained in a Data Server and raw event-driven data (e.g. high-frequency event data from a JMS, RV, or RTVAgent data attachment) is frequently stored in the cache and the cache's current table or history table can grow to more than 25,000 rows.

maxNumberOfCurrentRows

Specifies the maximum number of rows in a cache current table. The oldest rows in the current table are removed if necessary to maintain this limit. The default value is blank, indicating no limit on the number of rows. A value of zero can also be used to specify no limit.

The cache data source checks the maxNumberOfCurrentRows limit at approximately 10 second intervals, therefore the limit might be exceeded if new data is applied to the cache between those intervals.

Note: In many cases it is not necessary to place a numerical limit on the rows in the current table, since the rows are limited by the number of unique combinations of index column values, or rows are removed via other properties. In the case of a cache with no index columns, each update replaces the entire current table.

rowExpirationMode

Specifies whether to expire rows in the current table and, if so, the mode for doing so. Possible values are:

Off - Row expiration is disabled.

Mark - An Expired column is added to the current table and its value is set to true in each expired row.

Delete - Expired rows are deleted from the current table.

Mark & Delete - An Expired column is added to the current table, its value is set to true in each expired row. Eventually, expired rows are deleted from the current table.

The default value is Off. If this property is set to Mark, Delete or Mark & Delete, the following additional properties are available in the property sheet: rowExpirationTime, rowExpiredIndexColumns and rowExpiredColumnName.

If this property is set to Mark & Delete, the rowExpirationTimeForDelete property is available in the property sheet.

rowExpirationTime

This property is available when the rowExpirationMode property is set to Mark, Delete, or Mark & Delete. If row expiration is enabled on a cache (rowExpirationMode is not Off), the current table is periodically checked for expired rows. A row is expired if the difference between the current time and the timestamp in the row timestamp column is greater than the interval specified by the rowExpirationTime property. This check is performed once every 10 seconds, approximately.

Specify the duration in seconds, or specify a number followed by a single character indicating the desired time interval (e.g. 15m for 15 minutes). Valid characters are as follows:

y - years (365 days)

M - months (31 days)

w - weeks (7 days)

d - days

h - hours

m - minutes

s - seconds

The default value is blank, which specifies no expiration time. A row in the current table is considered expired when it is not updated per the time interval specified by the rowExpirationTime property.

Note: The cache data source checks the expiration time limit at approximately 10 second intervals, therefore the limit might be exceeded by up to 10 seconds.

rowExpirationTimeForDelete

This property is available only when the rowExpirationMode property is set to Mark & Delete. A row is deleted if the difference between the current time and the timestamp in the row timestamp column is greater than the interval specified by this property. The value of this property should specify a longer time interval than that specified for the rowExpirationTime property. The default value is blank, which specifies no deletion time.

Specify the duration in seconds, or specify a number followed by a single character indicating the desired time interval (e.g. 15m for 15 minutes). Valid characters are as follows:

y - years (365 days)

M - months (31 days)

w - weeks (7 days)

d - days

h - hours

m - minutes

s - seconds

This property is useful in cases where a row in the cache current table should be marked as expired after the time period indicated by the rowExpirationTime has passed and the row has not been updated, and then later the row should be deleted after the time indicated by rowExpirationTimeForDelete has passed.

For example, if a cache has the following property settings:

rowExpirationMode: Mark & Delete

rowExpirationTime: 30m

rowExpirationTimeForDelete: 4h

and a row in the cache current table is not updated for 30 minutes, the value of the Expired column for that row will be set to true. If a row is not updated for 4 hours, it will be deleted from the current table.

rowExpiredColumnName

This property is available when the rowExpirationMode property is set to Mark or Mark & Delete.

Specifies the name of the boolean column that is added to the cache current table to indicate if a row is expired. The default value is Expired.

rowExpiredIndexColumns

Previously named indexColumnNamesForDelete, this property is available when the rowExpirationMode property is set to Mark, Delete, or Mark & Delete.

Enter a semicolon (;) separated list of column names. The list must contain some or all of the column names specified in the cache indexColumnNames Property. The default value is blank. See “Table Cache” for more information.

On each update to the cache, the set of values contained in the update for the columns specified in this property is recorded. A row in the current table is considered expired when it has a matching value for those columns but was not updated.

This property can be used in conjunction with the rowExpirationTimeForDelete property. For example, if a cache is configured as follows:

rowExpirationMode = 3 (Mark + Delete)

rowExpirationTime = -1

rowExpirationTimeForDelete = any value > 0

rowExpiredIndexColumns = any subset of the cache's index columns

then if a row X exists in the cache's current table and that row's values in the columns specified by the rowExpiredIndexColumns property are not matched in the data table applied to the cache's valueTable property, the row is marked Expired. Subsequently, if row X is not updated again and the time specified by the rowExpirationTimeForDelete property elapses, then row X is deleted from the cache's current table.

rowsToDeleteTable

Previously named deleteTable, this property is intended to be attached to a data table that specifies the rows to be deleted from the cache current table. The data table attached to the rowsToDeleteTable is expected to contain the columns specified in the indexColumnNames property. If a row in the rowsToDeleteTable has the same values in each of the index columns as does a row in the cache current table, that row will be deleted from the current table. The history table is not affected

allowDuplicatesInHistoryFlag

If this property is deselected, then before adding a new row to the History table the cache data source will first check if an existing row has the identical timestamp and index column values. If a duplicate does exist, the existing row will be replaced with the new row.

Note: If duplicate history rows are acceptable or unlikely to occur, then it is recommended that this property remain selected to maintain optimum performance.

historyColumnNames

Enter a semicolon (;) separated list of column names from the cache current table to be stored in the cache history. The order in which the column names are specified does not affect the order in which they appear in the history table, they appear in the same order as they do in the current table.

By default, the cache current table and cache history table store the same columns. In many cases this is desirable. Data sources may supply data tables containing columns whose values are static (for example, units, version number, description, etc). It can be useful to store these values in the cache current table, but they can take up memory and database space when storing data in the history tables at every update.

The columns specified by historyColumnNames must be a subset of the columns in the cache current table. If a specified column does not appear in the current table, it is ignored. If a column is not specified in historyColumnNames but the column is specified in either indexColumnNames or timestampColumnName, the column is still included in the history table. This is because the index column and the timestamp column are needed for use and maintenance of the history table.

Changing the names specified in historyColumnNames could lead to incompatibility with data previously stored by the Historian. Note that this is also an issue with changes made to the cache schemaTable or the cache valueTable attachment.

The default value is blank, which specifies that all columns from the current table be stored in the history table.

historyTimeSpan

Previously named timeSpan, this property specifies the amount of time that rows will be kept in the History table according to their timestamp. The cache trims its History table by removing rows with timestamps that are older than the limit.

Specify the duration in seconds or specify a number followed by a single character indicating the desired time interval (e.g. 15m for 15 minutes). Valid characters are as follows:

y - years (365 days)

M - months (31 days)

w - weeks (7 days)

d - days

h - hours

m - minutes

s - seconds

The historyTimeSpan property only determines the duration of rows kept in the History table by the cache data source. It does not affect database storage, if any, associated with the cache.

Note: The maxNumberOfHistoryRows property will limit the total number of rows in the History table regardless of the specified historyTimeSpan.

initialTable

Attach this property to a table to pre-populate initial data for a cache. Specify the initialTable property to ensure that data is available for viewing when the cache is accessed for the first time. To properly populate the initial data for the cache using the initialTable property:

§        Specify the index columns for queries using the indexColumnNames property. See “Table Cache” for more information.

§        The SQL query that populates the initialTable must have the same index column(s) specified as those used to setup the cache.

§        The table must contain the same column(s) as the input table attached to the valueTable property.

§        The table must contain a timestamp column if timestampColumnName is specified. If the specified timestampColumnName is not found in the incoming data, a column is inserted.

Data attached to this property works best if it is only updated once at the startup of RTView.

Note: A table attached the initialTable property will be modified if you did not include a column with the timestampColumnName and/or if the rowsToDeleteTable property is updated. If other objects in your RTView application are attached to this same table, those objects might also be affected.

maxNumberOfHistoryRows

The number of rows in the History table. Default is 0. If set to 0, no History table is created and only the Current table is available in the Table drop down menu in the “Attach to Cache Data” dialog.

The “Extend with SQL” option requires this property to have a value greater than 0.

maxNumberOfRowsPerIndex

Enter the maximum number of rows the History table will contain for each unique combination of the cache's index column values. By default the value is blank, meaning that no per-index limit is applied to the History table.

If the condenseRowsFlag is selected, then the maxNumberOfRowsPerIndex will be applied to the cache's history_condensed table. If condenseRowsCombineHistoryFlag is also set, then the maxNumberOfRowsPerIndex will also be applied to the cache's history_combo table.

The maxNumberOfRowsPerIndex is checked only once per minute or, in the case of the history_condensed table, at the condense interval, which ever is less frequent. This means that the per-index limit may be exceeded until the next time the limit is checked.

Note: The maxNumberOfRowsPerIndex property is not visible if the value of maxNumberOfHistoryRows is 0 and therefore no History table exists.

resetTrigger

When data values attached to this property receive an update the cache will be cleared.

schemaTable

Optionally attach this property to any tabular data source (e.g. SQL query, XML file, etc.) to provide the structure of a table you would like the Table Cache object to use. Only the table's structure will be used from this data attachment, any row data will be ignored.

Once a schemaTable is specified, Current and History tables will be initialized accordingly and the Attach to Cache Data dialog will show the columns found in that table structure. Once data becomes available, Table Cache objects will contain the columns found in the specified schemaTable, in addition to columns found in the data.

Note: If the data types of columns defined in the schemaTable differ from data types found in the actual data attachment, then the schema types will be used and incoming data will be converted. If the specified timestampColumnName is not found in the incoming data, a column will be inserted.

schemaTableStrictFlag

If selected, then the schemaTable will be applied to all incoming data tables before they are stored in the cache even when the data table and the schema table have the same number of columns. If deselected, the schema is applied only when the data table and schema table have different numbers of columns.

Note: This option should only be selected if it is possible for a data table to have the expected number of columns, but those columns may be in the wrong order. If incoming data tables have a large number of columns and a high update frequency, then applying the schema in all cases will incur additional CPU overhead when updating a cache.

valueTable

Attach your input data to this property if it is tabular. For scalar input data, select the Double Cache object and attach your input data to the value property.

valueTableCount

Allows the Table Cache object to support multiple data attachments. Default is 1, which results in a single valueTable property. If valueTableCount is increased to 2, then valueTable02 will be added to the Object Property list and so on. Maximum value is 99.

condenseRowsCombineHistoryFlag

If selected, the history_combo table is made available. This property is available when the condenseRowsFlag property is selected.

The history_combo table stores rows of recent raw data followed by rows of older condensed data. The raw data rows extend from the current time back for the number of seconds specified by the condenseRowsRawDataTimeSpan property. The condensed rows are limited by the historyTimeSpan and/or maxNumberOfHistoryRows properties.

condenseRowsFlag

If selected, enables the primary compaction feature for the cache. This property makes the following tables available (in addition to the tables available by default, the Current and History tables.):

§        current_condensed: This table stores the most recent row of condensed data for each unique index column value combination.

§        history_condensed: This table stores condensed data history, limited by the cache historyTimeSpan and/or  maxNumberOfHistoryRows properties.

If you also select the condenseRowsCombineHistoryFlag property, the history_combo table is made available:

§        history_combo: This table stores rows of recent raw data followed by rows of older condensed data. The raw data rows extend from the current time back for the number of seconds specified by the condenseRowsRawDataTimeSpan property. The condensed rows are limited by the historyTimeSpan and/or maxNumberOfHistoryRows properties.

This property affects RTView behavior when persisting a cache to, or restoring it from, a database. For example, if condenseRowsFlag is selected on cache C1:

§        If the cache definition file is used as an Historian configuration file, the Historian stores only the condensed rows for C1 in the database table specified by C1's historyTableName property.

§        When the cache definition file is loaded by an RTView application (other than the Historian) the database table specified by C1's historyTableName is queried to get the initial rows for C1.history_condensed and, if enabled, C1.history_combo. This is useful in cases where the Historian should only store data that has already undergone primary compaction, rather than storing raw data which arrives in high volumes.

When condenseRowsFlag is selected, the following additional properties are available in the property sheet: condenseRowsInterval, condenseRowsGroupBy, condenseRowsRawDataTimeSpan and condenseRowsCombineHistoryFlag.

condenseRowsGroupBy

A string that specifies the calculation to be performed on each data column in the cache table. This property is available when the condenseRowsFlag property is selected.

Specify the string using the following format:

name1:calc1;name2;calc2...

where nameN is the name of data column N, and calcN is the calculation to be performed on the values in the column for each time interval. The supported calculations are average, min, max, and sum. The value for this property is configured from a dialog which allows the user to pick a column name and the calculation for that column. If a calculation is not specified for a data column, sum is used. Calculations are not applied to the data table index columns, nor to the timestamp column.

condenseRowsInterval

The time interval at which the cache history is condensed. This property is available when the condenseRowsFlag property is selected.

Specify a value using the following format:

NNu 

where NN is a number and u is a single character. Valid characters are as follows:

w - weeks (7 days)

d - days

h - hours

m - minutes

s - seconds

For example, to specify a ten minute interval:

10m

If only a number is entered, it is assumed to be seconds.

condenseRowsRawDataTimeSpan

The time span of raw data kept in the cache history table and, if enabled, its history_combo table. This property is available when the condenseRowsFlag property is selected.

compactionType

Select from the following options:

§        None - No compaction.

§        Aggregate - Compact via data aggregation.

§        Displace - Compact via table displacement.

You must specify at least one index column via the indexColumnNames property and, where possible, quoteColumnNamesFlag should be selected to preserve column name case.

Note: Based on your specified compactionRules, use the -smoothcompaction command line option to perform compaction on old data which currently exists in your database from prior executions of the Historian. See “Command Line Options: Historian” for more information.

compactionGroupBy - This property applies only if the selected compactionType is Aggregate. Click on the button to specify the methods used to perform compaction (i.e. sum, count, average, min or max).

compactionRules - Specify compaction rules.

Note: If the selected compactionType is Displace, then currently this property only supports the use of one displacement rule.

Note: These object properties apply to Advanced Historian users only. See “Advanced Historian - Cache Properties” for more information.

Property Name

Description

currentTableName

Enter the name of a table in your Historian database in which to store the cache's current data table. If you specify a currentTableName and no table by that name exists in your database, then one will be created for you the first time you run the Historian.

On each update of the data attached to the valueTable property, the Historian will create or update corresponding rows in the specified currentTableName in the Historian database. The indexColumnNames property will be used to locate rows to update otherwise, if no indexColumnNames are defined, the Historian will replace the entire table on each update.

If the rowsToDeleteTable property is used to delete rows from the cache's current table, then Historian will also delete those rows from the specified currentTableName table in the Historian database.

On startup of an RTView application, the specified currentTableName will be queried from the Historian database for initial rows to be loaded into the cache's current table. To prevent this initial data from being loaded, you can run the Display Builder or Display Viewer from a command window and use the -nohistory command line option.

The currentTableName property is not supported in combination with the Historian's -kdbformat command line option.

databaseName

Name of your Historian database that contains history and/or current tables for this cache. If left blank, the database name RTVHISTORY is assumed.

The “Extend with SQL” option requires that the database specified in this property have a SQL database connection. Or, if this property is blank, there must be a database connection to the default RTVHISTORY database.

historyTableName

Enter the name of a table in your Historian database in which to store the cache history data table. If you specify a historyTableName and no table by that name exists in your database, one is created for you the first time you run the Historian.

When rows are appended to the cache history table, the Historian also appends those rows to the specified historyTableName in the Historian database.

If you specify a timestampColumnName, the Historian assumes that column is to be used for sorting and purging rows in chronological order and does not append its own timestamp columns to the specified historyTableName table.

Before data is stored in the database, the cache schemaTable, if any, is applied.

If you specify a historyTableName, RTView applications automatically query the Historian database table for the initial rows to be loaded into the cache history table, provided that:

§        The initialTable property is not attached to data (indicating an explicit query has been configured to load cache history data), and

§        A timestampColumnName is specified (so that it can be used to sort the SQL query result by time).

The number of rows loaded by this initial query is limited by the maxNumberOfHistoryRows property. To prevent this initial data from being loaded, you can run the Display Builder or Display Viewer from a command window and use the -nohistory command line option.

The “Extend with SQL” option requires that this property specify the cache database table name. The table specified in this property is used for queries.

quoteColumnNamesFlag

If selected, column names will be quoted in all SQL queries and commands for this cache.

Property Name

Description

anchor

Specifies where to anchor an object in the display.

objName

Name given to facilitate object management via the Object List dialog. Select Tools>Object List.

objX

Plot x-axis position of object.

objY

Plot y-axis position of object.

styleClass

Enables you to apply distinct styles to different instances of the same object class. The value entered for styleClass must not contain spaces and must not start with rtv.

cacheName

A unique name for the cache. An entry for this property is required. Caches that do not specify a cacheName, as well as caches with duplicate cacheName properties, will not be created and an error will print to the console.

Substitutions defined in a Cache Definition File allow the same file to be specified multiple times with different sets of substitutions. Note that each cacheName defined in that file should contain a substitution, since cache names must be unique. See “Application Options -- Caches” for more information.

Substitutions must use the following syntax:

$subname:subvalue $subname2:subvalue2

If a substitution value contains a single quote, it must be escaped using a / :

$filter:Plant=/'Dallas/'

If a substitution value contains a space, it must be enclosed in single quotes. Do not escape these single quotes:

$subname:subvalue $subname2:'sub value 2'

description

Enter descriptive text which is displayed in the Description column of the Caches table.

timestampColumnName

Specify the name of a timestamp column. If the specified timestampColumnName is not found in the incoming data, a column will be inserted and each row will contain the time that row was received

historyTimeSpan

Previously named timeSpan, this property specifies the amount of time that rows will be kept in the History table according to their timestamp. Specify the duration in seconds or specify a number followed by a single character indicating the desired time interval (e.g. 15m for 15 minutes). Valid characters are as follows:

y - years (365 days)

M - months (31 days)

w - weeks (7 days)

d - days

h - hours

m - minutes

s - seconds

The historyTimeSpan property only determines the duration of rows kept in the History table by the cache data source. It does not affect database storage, if any, associated with the cache.

The maxNumberOfHistoryRows property will limit the total number of rows in the History table regardless of the specified historyTimeSpan.

initialTable

Attach this property to a table containing initial values for the cache. This attachment must result in a table with a single column of type double, as well as a timestamp column if timestampColumnName is specified.

Note: If the specified timestampColumnName is not found in the incoming data, a column will be inserted.

Data attached to this property works best if it is only updated once at the startup of RTView.

Note: A table attached the initialTable property will be modified if you did not include a column with the timestampColumnName and/or if the rowsToDeleteTable property is updated. If other objects in your RTView application are attached to this same table, those objects may also be affected.

maxNumberOfHistoryRows

Previously named maxNumberOfRows, this property specifies the number of rows in the History table. Default is 100. If set to 0, no History table is created and only the Current table will be available in the Table drop down menu in the “Attach to Cache Data” dialog.

The “Extend with SQL” option requires this property to have a value greater than 0.

resetTrigger

When data values attached to this property receive an update the cache will be cleared.

value

Attach your input data to this property if it is scalar. For tabular input data, select the Table Cache object and attach your input data to the valueTable property.

databaseName

Name of your Historian database that contains history and/or current tables for this cache. If left blank, the database name RTVHISTORY is assumed.

The “Extend with SQL” option requires that the database specified in this property have a SQL database connection. Or, if this property is blank, there must be a database connection to the default RTVHISTORY database.

historyTableName

Enter the name of a table in your Historian database in which to store the cache's history data table. If you specify a historyTableName and no table by that name exists in your database, then one will be created for you the first time you run the Historian.

When rows are appended to the cache's history table, the Historian will also append those rows to the specified historyTableName in the Historian database.

If you specify a timestampColumnName, the Historian assumes that column will be used for sorting and purging rows in chronological order and will not append its own timestamp columns to the specified historyTableName table.

Before data is stored in the database, the cache's schemaTable, if any, is applied.

If you specify a historyTableName, RTView applications will automatically query the Historian database table for the initial rows to be loaded into the cache's history table, provided that:

§        The initialTable property is not attached to data (indicating an explicit query has been configured to load cache history data), and

§        A timestampColumnName is specified (so that it can be used to sort the SQL query result by time).

The number of rows loaded by this initial query is limited by the maxNumberOfHistoryRows property. To prevent this initial data from being loaded, you can run the Display Builder or Display Viewer from a command window and use the -nohistory command line option.

The “Extend with SQL” option requires that this property specify the cache database table name. The table specified in this property is used for queries.

quoteColumnNamesFlag

If selected, column names will be quoted in all SQL queries and commands for this cache.

Property Name

Description

anchor

Specifies where to anchor an object in the display.

objName

Name given to facilitate object management via the Object List dialog. Select Tools>Object List.

objX

Plot x-axis position of object.

objY

Plot y-axis position of object.

styleClass

Enables you to apply distinct styles to different instances of the same object class. The value entered for styleClass must not contain spaces and must not start with rtv.