About the RdbmsNetwork device components and extensions

Under the RdbmsNetwork, each "device" component represents a specific type of relational database and should be located under the RdbmsNetwork driver, as shown below.

The following device components and properties are identical to those listed under Types of RdbmsNetwork network-level components and properties and described in the NiagaraAX Drivers Guide.

Status
Enabled
Fault Cause
Health
Alarm Source Info

Properties and components that are common to (or similar among) most Rdbms database devices are visible from the Rdbms driver property sheet view are described in the following list:

Enabled
Select true from the option list.
Host Address
Use this field to set the IP address or ‘hostname’ of the computer platform where the database resides. A Dialup selection option is available, if required. This property does not apply to the MySQL device.
User Name
This property is the user name that is used to login to the database.

NOTE: Your login credentials must provide sufficient database privileges to allow you to perform one or more (depending on database type) of the following commands:CREATE TABLE, CREATE INDEX, CREATE SEQUENCE
Password
This property is the password of the user than is used to login to the database.
Worker
This is a child component of all Rdbms driver devices. The "Rdbms Worker" manages the queue and threads for asynchronous operations on a single parent database. The Worker component provides two properties for setting the maximum number of concurrent threads and for setting the maximum allowable queue size for the database connection. These worker properties are not pooled at the Network level, as with the NiagaraNetwork driver, each database driver has its own thread pool setting. The following two parameters apply to Worker properties:
- Max Threads
  This value allows you to specify the maximum number of multiple concurrently connections (Threads) that the station makes with the external database. The default value is one thread. Each thread uses one JDBC Connection to communicate with the database, so there are as many connections created as there are threads.
  
  This can normally be increased to a value between 20 and 50 to improve performance when handling large volumes of data.
- Max Queue Size
  This value allows you to specify the maximum queue size supported for Rdbms actions specific to the associated database driver (i.e. exports, imports). The default Max Queue Size is 1000.
  
  Max Queue Size needs to be adjusted to reflect the peak number of import or export records per archive that are expected to be processed and will normally be increased when handling large volumes of data.
Export Mode
This property allows you to specify how histories will be exported into the specified database. The two possible options are:
- By History Id
  This choice specifies that histories are exported as one table per History Id. This is the default value setting.
- By History Type
  This choice specifies that histories are exported as one table per History Type. This option may make the data easier to query once it has been exported.
  
  NOTE: For good practice, Export Mode should normally be set to By History Type, as most DBA’s would rather manage a few tables instead of thousands of individual tables.When exporting by By History Type, histories of the same data type (Boolean, Numeric, Enum, String) are exported to the same table. For example, all numeric type histories are exported to a table named HISTORYNUMERICTRENDRECORD. The table contains an additional column named HISTORY_ID which stores the history ID reference (ORD) from the Niagara station for each record in the table.
Use Unicode Encoding Scheme
This boolean property has true and false (default) options that allow you to create history table schemas with Universal character set Transformation Format (UTF-8) or Unicode data types for string valued columns in order to store Asian character sets. This property is available starting in NiagaraAX-3.8 and it defaults to false to maintain backwards compatibility with the existing history export mechanism. When this property is set to true, the resulting history tables created in the database will have the 'NVARCHAR' data type for any columns in the tables that expect string data.

NOTE: An Update Wizard is available to help you easily perform an upgrade of existing databases to support Unicode as described in Upgrading existing Rdbms databases to support Unicode.
Timestamp Storage
This enum property allows you to export or update history timestamps to Coordinated Universal Time (UTC). It enables History records to be exported from different timezones into a common database and be chronologically correct and independent of any specific source timezone characteristics. In other words, exported histories will show the timestamp data from where the history is actually stored, making useable histories with a consistent timestamp.

This property is available starting in NiagaraAX-3.8 and it defaults to Dialect Default to maintain backwards compatibility with the existing history export mechanism. This property does not apply to the MySQL device. The possible options are:
- Dialect Default
  This choice specifies that the timestamp export policy is in legacy mode to maintain backwards compatibility with the existing history export mechanism. This is the default value setting.
  
  NOTE: If you are selecting the Dialect Default option, then you must set both Use Last Timestamp and Use History Config Time Zone properties in the History Device Extension to true to export histories using the History Config Timezone. (If the two properties are set to false, the histories will be exported using the station timezone).
- Local Timestamp
  This choice applies when using Orion databases only and does not apply to history exports.
- Utc Timestamp
  This choice specifies that all subsequent exported histories will be exported with their timestamps adjusted to UTC time.
  
  NOTE: Do not switch back and forth between Dialect Default and Utc Timestamp because the database table will become polluted with inconsistent timestamps and this will affect any query that is run to determine whether or not to export newer records.
  
  NOTE: If you are selecting the Utc Timestamp option, then this takes precedence over any setting of the Use Last Timestamp and Use History Config Time Zone properties in the History Device Extension, rendering them effectively irrelevant.
- Utc Millis
  This choice applies when using Orion databases only and does not apply to history exports.
NOTE: Associated with Timestamp Storage and available from NiagaraAX-3.8 is the addition of a new column called 'DB_TIMEZONE' to the HISTORY_CONFIG and HISTORY_TYPE meta tables that are created the first time histories are exported. The DB_TIMEZONE column stores the actual timezone that the database is currently using to store timestamps (this is different from the pre-existing TIMEZONE column, which reflects the timezone in which the history was created but not the one in which it's being stored). When records are being exported in UTC mode, the DB_TIMEZONE column will update accordingly.

NOTE: An Update Wizard is available to help you easily perform an upgrade of existing databases to support UTC as described in Upgrading existing Rdbms databases to support UTC.
Points
This component is available starting in NiagaraAX-3.4 and is a child of all Rdbms driver devices. The "Rdbms Point Device Extension" provides point import capability for the various relational database drivers using methods and views that are similar to other proxy point driver views. Using this feature, you can represent relational database cell values as proxy points. No configuration is required for RdbmsNetwork Driver configuration. See “Using the Rdbms Point Device Extension”, and "About the Points Extension" in the NiagaraAX Drivers Guide.
Sql Scheme Enabled
This property has true and false (default) options that allow you to specify that Sql Scheme is to be enabled.

You must set this property to true if you are going to execute queries against the relevant database. It also needs to be enabled as a prerequisite of using the Rdbms Point Device Extension.

You must also set this property to true if you are going to chart or load data back in from an Oracle database into Niagara. This is also useful for debugging as you can run limited queries against the database from Niagara.

If you are not executing queries, using the Rdbms Point Device Extension, or loading data from Oracle, for good security practice you should set the property to false.
Base Directory, Database Name, Instance Name, Service Name
Type in the name of the database that you are connecting to (see the following notes).

NOTE: For HsqlDb device only:- The “Base Directory” property is the path that points to the location of the Hsql database. A typical configuration is to create a folder directly under the station (in the “file space”). For example, if the folder is named “hsqldb”, then a path to the folder is specified as “file:^hsqldb”.

NOTE: For Db2, HsqlDb and MySQL Database devices only: The "Database Name" property allows you to configure a connection to the Database.

NOTE: For SqlServerDatabase device only: The "Instance Name" property allows you to configure a connection to a SqlServer Database if the user has not been previously set up in the SqlServer with a ‘default’ Database Name or Instance Name or if you wish to connect to a name which is not the default. If a default name has been set up and you need to connect to it then you can leave this property blank.

NOTE: For OracleDatabase device only: The "Service Name" property refers to the Oracle SID or System IDentifier which uniquely identifies a database instance. It allows you to configure a connection to an Oracle Database if the user has not been previously set up in the Oracle Database with a ‘default’ SID, or if you wish to connect to an SID which is not the default. If a default SID has been set up and you need to connect to it then you can leave this property blank.
Port
The value of this property specifies the port number to use when connecting with the database. Default values are:
- Db2Database - Port 6789
- HsqlDbDatabase - no port is specified because this rdb is for local database use only.
- MySQLDatabase - Port 3306
- OracleDatabase - Port 1521
- SqlServerDatabase - Port 1433
Histories
This is the History Device Extension which is fully described in the NiagaraAX Drivers Guide. It is not available on the HsqlDbDatabase device since this database may not be used to import or export histories.

In addition to the normal default “Retry Trigger” component, the History Device Extension contains the following two parameters which are specific to this driver:
- Use Last Timestamp
  This property has true and false (default) options.
  
  When this property is set false, every time an export descriptor processes, the Niagara station must query the database to determine the value of the last timestamp in the database. Depending on the size of the database table and the number of export descriptors being processed, this can be a time consuming activity.
  
  When this property is set true, instead of querying the database each time for the last record in the database, the Niagara station stores the last timestamp as a property on the export descriptor each time it processes the export. This is an efficiency related setting that helps with overall system performance when exporting data. You may consider therefore, to set the option true.
- Use History Config Time Zone
  This property has true and false (default) options.
  
  This property was originally added to configure how the timestamp is normalized before it is to written to the external database. Prior to NiagaraAX-3.8, timestamps stored in the external database did not include time zone information, rather they were simply date and time.
  
  When this property is set false, timestamp values are normalized to the supervisor station’s time zone before being written to the external database.
  
  When this property is set true, the original timestamp value is retained by the supervisor and written to the external database. Unfortunately, there is no timezone information in this data and difficulties have arisen with local timezones especially in relation to daylight savings time. It is for this reason that the NiagaraAX-3.8 release introduced the Timestamp Storage property allowing you to export or update history timestamps to Coordinated Universal Time (UTC).
NOTE: The effect of these History properties may be renderered irrelevant depending upon the setting of the Timestamp Storage property.
Extra Connection Properties
This would normally be left blank but it would typically be used for advanced diagnostics or tuning under the guidance of a support channel. It is not required for a normal connection to the database. Extra connection properties are additional parameters which are passed in plain text by the driver when connecting to a database. It is beyond the scope of this document however, to define the parameters that could be used but they are typically entered in the format: ;parameter1=value1;parameter2=value2;...etc. This property applies to the MySQL and SqlServer devices.
Version
This is used to determine whether the Sql Server database supports the SQL ‘DATE’ type. The ‘DATE’ Sql type is supported from Sql server 2008 onwards and the database device needs to know how to translate timestamps when retrieving records. You must set this property to match the version of the database you are connecting to. This property only applies to the SqlServer device. The possible options are:
- Sql Server 2008
  This choice specifies that the Version of Sql Server you are connecting to is Sql Server 2008. This is the default value setting.
  
  NOTE: Use this Sql Server 2008 option if you are connecting to a Sql version that is more recent than Sql Server 2008, such as Sql Server 2012.
- Sql Server 2005
  This choice specifies that the Version of Sql Server you are connecting to is Sql Server 2005.
- Sql Server 2000
  This choice specifies that the Version of Sql Server you are connecting to is Sql Server 2000.