The Historian is used to archive data from any RTView data source to any database using JDBC. The SQL data source is required to view data from the Historian in RTView. It is not required to use the Historian to archive data. You can verify that the SQL data source is licensed in your installation in the Display Builder About dialog.

You configure the Historian by creating Data Configuration (.rtv) files, configuring the Historian to create connections to your data sources, and setting final configurations in the Historian application. The Data Configuration (.rtv) files specify which data the Historian is to archive from each data source. You create Data Configuration (.rtv) files in the Display Builder. The Data Configuration (.rtv) files also specify how to access the data, and perform required transformations in the data.

When you start the Historian, it immediately begins gathering data as specified and places the time-stamped data into the designated tables. After the Historian has stored data over a period of time, you can Build a Display Using History Data.

You can install multiple versions of the Historian to segment data collection into different databases, and configure fault-tolerance. The Historian comes with default schemas that are largely configurable. For example, you can use configuration files to specify your own table names and, optionally, let the Historian automatically create the tables in your database if they do not already exist.

Data Configuration File Options
To configure the Historian you create Data Configuration (.rtv) files in the Display Builder. Data Configuration (.rtv) files specify which data to archive from each data source, how to access the data, any transformations to perform with the data, and the table in which to then store the data. There are two Data Configuration (.rtv) file options, Display Files or Cache Definition Files.

Display Files
Use this option if your RTView deployment does not use caches. With this option you use your existing RTView display (.rtv) files (that you created in the Display Builder) to configure the Historian. Your existing display (.rtv) files contain objects that are already attached to your data. A record is stored in the history database every time new data is received by the Historian for each data attachment in your configuration display.

To use RTView display (.rtv) files to configure the Historian, you must have two history tables configured in your database: one for numeric data, the other for string data (for example, textual data). Numeric values must be attached to numeric object properties, and text values must be attached to string object properties. If you attach a numeric value to a meter label (which is a string object property), the numeric value is stored in the database as a string instead of a number, and the data is not available for trend graphs.

Cache Definition Files
Use this option if your RTView deployment uses caches or, if you need to use the Advanced Historian. With this option you configure Cache object properties to point to the historical data to be archived. You can also specify which sources of current and/or historical data to keep in memory. To configure the Historian using this option, you specify which of these cached values to archive in a history database and then use these cache definition (.rtv) files to configure the Historian. The cache definition (.rtv) file specifies the following for the Historian: the data source, the cache and the database in which to store historical data.

The Cache data source allows for much higher performance than the traditional means of either performing analytics on information stored in a database, or querying it from the database to make calculations.

Basic Steps To Configure the Historian
Perform the following steps in the order given to configure the Historian:

Display File Configuration
Perform the following steps to create a Data Configuration (.rtv) Display File for configuring the Historian. These procedures assume you are using your existing RTView display (.rtv) files (the displays you currently use to view your data) to configure the Historian. These procedures assume that you have already attached your historical data to an object.

To configure the Historian using a Display File
1. In the Display Builder, verify that your data is attached to the appropriate type of object property for the corresponding value. That is, numeric values must be attached to numeric object properties, and text values must be attached to string object properties. If you attach a numeric value to a meter label (which is a string object property), the numeric value is stored in the database as a string instead of a number, and the data will not be available for trend graphs).

2. Verify that you have two history tables in your database: one for numeric data, and another for string data (textual data). If you do not, configure the two tables. By default, if the -rebuildtables option is on, the first time you run the Historian two tables are created: a numeric table named HISTORY and a string table named HISTORY_S.

If you can verify the default numeric table (HISTORY) and the string table (HISTORY_S) are in your database, and you want to use these tables, proceed to Configure Database Connections.

If you do not want the Historian to create the HISTORY and HISTORY_S tables, you can create your own history tables manually. The tables must be created before running the Historian application.  

To create your own history tables, use your preferred database client tools or database vendor client tools to do the following:

	A. Use the -tablename command line option for the Historian to specify a single table name (other than HISTORY and HISTORY_S). The table name you specify is used for the numeric table, and _S is appended to the name to create the string table. For example, if you specify:
		MY_TABLE
	The table name MY_TABLE is then established, and another table name is automatically created which has _S appended to the name. You then have the following two tables:
		MY_TABLE  is used for the numeric table.
		MY_TABLE_S is used for the string table.
	NOTE: Table names cannot contain spaces.
	B. Configure the numeric table as described in the Numeric Data Table, below.
	C. Configure the string table as described in the String Data Table, below.
	D. Specify the table name on the command line for the Display Builder and Display Viewer Application and/or in your Display Viewer Applet parameters.

NOTE: The two manually created tables are automatically rebuilt as data is received (you do not need to manually rebuild the tables).

NOTE: Tables created manually cannot utilize the valueHistoryFlag property to load initial history data on graph traces.

Numeric Data Table
The following fields are supplied in the numeric data table (HISTORY or the table name you specified):
 

Field Name	Field Type		Field Description	Recommended Field Length (if applicable)
VAR_NAME	Text		The data attachment used to store this record.	80-160
TIME_STAMP	Text	The time this record was stored. This value is rounded to the closest second. Two columns are stored with each record. This field is only necessary if String Timestamps (2) is selected in the Historian GUI. This is the default selection.		30
	Standard SQL TIMESTAMP data type.	This field is only necessary if SQL Timestamp is selected in the Historian GUI.		N/A
TIME_STAMP_LS	Text		A string value of the time this record was stored. This value contains the time including milliseconds. This field is only necessary if String Timestamps (2) is selected in the Historian GUI. This is the default selection.	14
VAR_VALUE	double		The value for this field. This value is a number.	N/A

NOTE: If you select the historyTableRowNameFlag checkbox in Object Properties, then you must include and additional text column placed at the beginning of the table to store row name values. The Historian assumes that columns in the history table you create are in the same order as those in your tabular data element. If not, you can use the -insertColumnNames command line option for the Historian to match data to the correct columns.

String Data
The following fields are supplied in the string (textual) data table (HISTORY_S or the table name you specified):
 

Field Name	Field Type	Field Description	Recommended Field Length (if applicable)
VAR_NAME	Text	The data attachment used to store this record.	80-160
TIME_STAMP	Text	The time this record was stored. This value is rounded to the closest second. Two columns are stored with each record. This field is only necessary if String Timestamps (2) is selected in the Historian GUI. This is the default selection.	30
	Standard SQL TIMESTAMP data type.	This field is only necessary if SQL Timestamp is selected in the Historian GUI.	N/A
TIME_STAMP_LS	Text	A string value of the time this record was stored. This value contains the time including milliseconds. This field is only necessary if String Timestamps (2) is selected in the Historian GUI. This is the default selection.	14
VAR_SVALUE	Text	The value for this field. This value is a string.	40

NOTE: When you attach data to a tabular object property, such as valueTable, it is recommended that you create a table in the history database to store that data. If you do not create a table, data from your tabular element is stored in standard history tables and, in the case of tabular data with multiple columns, row integrity is lost. See Tabular Data for details about how to store tabular data.

For step-by-step instructions on creating data configuration files for the Historian or to learn how to create a table in the history database to store tabular data, go to Examples>Historian.

Proceed to Configure Database Connections.

Cache Definition File Configuration
Perform the following steps to configure the Historian using a Cache Definition File. The Cache Definition file specifies the following for the Historian: the data source, the cache and the database in which to store historical data. In these Steps you specify your data source and your cache.

To configure the Historian using a Cache Definition File
1.Use the RTView Builder to create a Cache Definition file, or select a cache on which you want to enable the Historian.

2. Select the cache from the Caches dialog and edit the following Historian properties in the Object Properties dialog. (In this Step you specify your cache.)

3. When you have finished configuring the properties, Save the display (.rtv) file. You will add this Cache Definition file to the list of Data Configuration files in the Historian application.

Proceed to Configure Database Connections, next.

Database Connection Configuration
Perform the following steps to configure the Historian connections to your data sources. There are two options: a direct JDBC connection, or an ODBC-JDBC bridge connection.

Direct JDBC Connection
For the Historian to use a direct JDBC Connection to communicate with your database, you must have a JDBC driver for your database. JDBC drivers are available from most database vendors.

To configure a direct JDBC Connection
1. Locate the JDBC driver on your machine.

2. Define an environment variable named RTV_USERPATH that includes a path to the driver class or .jar file containing the driver class.

NOTE: You can define RTV_USERPATH to include paths to multiple driver classes. The RTV_USERPATH variable is included in the classpath for RTView and the Historian.

3. Note the fully qualified class name for the driver class and the database URL required to connect to your database. You need this to setup the database (when you Configure the Historian application). The database URL typically contains protocol and sub-protocol strings for your database, as well as the path to the database and a list of properties. If you do not know the syntax for your database URL, consult the documentation for your JDBC driver.

Proceed to Historian Application Configuration.

ODBC-JDBC Bridge Connection
For the Historian to use an ODBC-JDBC bridge to communicate with your database, you must have a ODBC driver for your database. JDBC drivers are available from most database vendors. Most databases that run on Microsoft Windows come with an ODBC driver.

To configure a direct JDBC Connection
1. Register your database with ODBC.
 

	Windows: 1.    From the Windows Control Panel, double-click on the ODBC Data Sources icon. If this icon is not listed, double-click on the Administrative Tools icon and then double-click on the Data Sources (ODBC) icon. This will open the ODBC dialog. 2.    In the ODBC dialog, click Add. In the Create New Data Source window, select the driver for which you want to setup a data source. Click Finish to bring up the Setup dialog. 3.    Enter a Data Source Name (e.g. RTVHISTORY). NOTE: This Data Source Name must match the name of the history database configured in the Display Builder SQL Application Options tab, as well as the Historian Database Name specified in the Historian GUI. 4.    Click Select and choose the database to which you would like the Historian to store data. 5.    Click OK in the Select Database, Setup, and ODBC dialogs.
	UNIX: UNIX systems do not come standard with an ODBC driver. Contact your system administrator for information on how to install and setup an ODBC driver for your database.

2. If you are using a direct JDBC connection or a password protected ODBC-JDBC bridge connection to communicate with the history database, you must configure the history database in the Display Builder. To configure the history database in the Display Builder, select Tools>Options>SQL and add a database with the same configuration options used in the Historian. See SQL Application Options for information. After completing this step, proceed to the next step.

If you are not using a direct JDBC connection or a password protected ODBC-JDBC bridge connection to communicate with the history database, proceed to the next step.

Proceed to Historian Application Configuration, next. 

Historian Application Configuration  
This section describes how to add the Data Configuration file you previously created to the Historian application, and configure the database in which your historical data will be stored.

The Historian Application allows you to configure the database connection. Click Save Configuration to save these settings. The Historian Console tab records errors and information. If you select the Show Data in Console checkbox, the Historian Application will output a line for each record that is stored in the database.

Data source-specific options are read in from initialization (.ini) files created in the Display Builder. For information on creating initialization files or command line options for your data source, refer to Application Options or Command Line Options in the Data Sources section of this documentation.

To configure the Historian Application
1. Start the Historian.
 

	Windows From the Windows Start Menu: Select Start-->Programs-->RTView--> Historian NOTE: When you start the Historian from the Windows Start menu, it runs from the demos directory. The Historian will try to read initialization (.ini) files and resolve XML sources containing relative paths from that directory. To start the Historian in another directory, you must run RTView from a command window. NOTE: You can specify a directory for your initialization files.
	From a Command Prompt Window Select Start-->Programs-->RTView-->GMS Command Prompt In the command window type: run_historian
	UNIX In an initialized terminal window type: run_historian

The Historian application opens and begins gathering and placing your (now time-stamped) data into tables based on your Data Configuration file specifications.

2. Click Configuration to edit settings.

3. Make the following Database Options entries as appropriate:

	Historian Database Name	The ODBC Data Source Name for the database the Historian will use to store and query information. NOTE: This name must also match the name of the history database configured in the Display Builder SQL Application Options tab.
	Database User Name	The user name to pass into the history database when making a connection. This parameter is optional. You cannot edit this field while the Historian is storing data.
	Database Password	The password to pass into the history database when making a connection. This parameter is optional. You cannot edit this field while the Historian is storing data. If you need to provide an encrypted password (rather than expose server password names in a clear text file, use the encode_string command line option with the following syntax: encode_string mypassword where mypassword is your plain text password. For example, enter the following in an initialized command window: encode_string mypassword and you will receive an encrypted password: encrypted value: 013430135501346013310134901353013450134801334 Copy the encrypted value, paste it into the password field and click Save to save this value to the initialization (*.ini) file. Or, if necessary, manually edit the (*.ini) file to include the encrypted value. NOTE: If you need to manually edit a configuration (*.ini) file, contact SL Technical Support at support@sl.com for information about supported syntax.
	Use ODBC Driver	If selected, use an ODBC-JDBC bridge to connect to the history database. An ODBC data source must be setup for this database to connect using an ODBC driver. You cannot edit this field while the Historian is storing data.
	JDBC Driver Class Name	The fully qualified name of the JDBC driver class to use when connecting to the history database. The path to this driver must be included in the RTV_USERPATH environment variable. You cannot edit this field while the Historian is storing data.
	JDBC Database URL	The full database URL to use when connecting to the history database using the specified JDBC driver. Consult your JDBC driver documentation if you do not know the database URL syntax for your driver. You cannot edit this field while the Historian is storing data.
	Append Timestamp Type	Specify the type of timestamp.	None	No TIMESTAMP column is stored.
			SQL Timestamp	A single TIMESTAMP column is stored using a standard SQL TIMESTAMP data type.
			String Timestamps (2)	Two TIMESTAMP columns are stored with each record as strings. This is the default.

4. Make the following Record Retention Options entries as appropriate:

	Delete Records Periodically	If selected, the Historian will periodically delete records from the numeric table (HISTORY or the table name you specified) and the string table (HISTORY_S or the table name you specified) according to the rate set.
	Rate to Delete Records	The length of time (in minutes, hours or days) a record can exist before it marked for deletion. For example if you set the rate to 5 minutes, then the next time you start RTView all records older than 5 minutes will be deleted. For the remainder of your work session, RTView will search every 2.5 minutes (half the rate) for records that exceed the rate.
	Purge Database on Start	If selected, the Historian will clear out the numeric table (HISTORY or the table name you specified) and the string table (HISTORY_S or the table name you specified) before storing new data.
	Purge Database	Clears out the numeric table (HISTORY or the table name you specified) and the string table (HISTORY_S or the table name you specified) immediately.

5. Make the following Data Cache Options entries as appropriate:

	Cache Data	If selected, the Historian will cache data according to the Cache Duration and Cache Size specifications.  If both Cache Duration and Cache Size are set, then the data records will be committed as soon as the first limit is reached.
	Cache Duration	Length of time (in seconds) to cache before committing records to the database. If the value is set to 0 the Historian will not commit records in the database immediately, but rather will store them in the cache to be committed later.
	Cache Size	Number of records to cache before committing them to the database.
	Flush Cached Records	Flush all cached records to the database immediately.
	Store Last Values Only	If selected, the Historian will store only the last (most recent) values in the cache for each unique data attachment. By default, the Historian stores all records in the cache each time the Cache Duration or Cache Size limit is reached. This option allows the Historian to store less data than it receives, which can be useful in a configuration where the Historian receives data from the Data Server at a higher rate than necessary for historical storage. For example, suppose the Data Server sends tables from two SQL attachments to the Historian: Query1: select * from table1 Query2: select * from table2 If the Data Server executes those queries every 10 seconds and the Historian has Cache Duration of 60 seconds, then every 60 seconds the Historian's data cache will contain six result tables from Query1 and six result tables from Query2. By default, the Historian will commit all twelve tables to the database. However if Store Last Values is selected, the Historian will commit only the sixth (most recent) table from Query1 and Query2 and discard all other tables in the cache. NOTE: This option is available only if Cache Data is selected and the value of Cache Duration is greater than 0.

6. Make the following Alert Persistence entries as appropriate:

NOTE: Alerts are sent from the application running the alert engine to the Historian via the RTVAgent. Therefore, you must enable connections from remote agent applications on the RTVAgent Options tab and then copy the RTVAGENTOPTIONS.ini file to the directory where you will be running the Historian.
 

	Alert Persistence Enabled	Select to enable the persistence of alerts during fail over of an alert engine. All fields and current state of all active alerts, as well as all cleared alerts that have not been removed from the system will be stored.
	Alert Persistence Table Name	Name of the table where the alerts will be persisted. NOTE: This must be the same table name specified in Alert Persistence tab of the Application Options>Alerts dialog.

1.     NOTE: The Historian must run the RTVAgent data source locally (not via a Data Server) to persist the alerts. If you are running the Historian against a Data Server you can run the RTVAgent data source locally using the following command line option:

run_historian -dsenable:RTVAGENT

7. In Data Configuration Files, click Add, enter the name of the Data Configuration (.rtv) file you just created and, optionally, any corresponding substitutions. Substitutions allow the same file to be used multiple times by different sets of substitutions. NOTE: Each cache that is defined in the file should contain a substitution in the cacheName property, since cache names must be unique.

8. Click Apply to execute. Data Configuration files are added or removed after you click OK, Apply, or Save.

NOTE: To edit the Data Configuration (.rtv) file and apply changes without restarting the Display Builder, select a file from the list and click Refresh Selection to reload definition settings. The Refresh Selection option is enabled when you select a Data Definition (.rtv) file that has been both added and applied.

The Data Configuration (.rtv) file is added to the data source and data for these caches is collected. See the Attach to Cache Data section for details about attaching to cache data variables.

NOTE: After a Data Configuration (.rtv) file has been added to the data source, data is collected for that cache regardless of whether any currently open display (.rtv) files are showing that data.

9. Select Show Data in Console so that the Historian prints out a line for each record that is being stored in the database.

10. Select Start Storing Data.

11. Select Save Configuration.

12. Verify your configuration by clicking Console to view the Show Data in Console output.

Your setup is complete. After the Historian has stored data for a period of time, proceed to Build a Display Using History Data.

Optionally, you can configure failover for the Historian. For information, see Configuring Failover on the Historian.