CSV Override Files for Flow Computers

In addition to the Flow Computer Tags child tags, which read in all of the history and process data, the flow computer also collects configuration records. These configuration records, which include gas composition and pipe orifice details, are logged to the VTScada historian as a single entry by the Meter Run tag.

Every flow computer device type selection has its own specific address mapping that tells the flow computer tag how to read that device. This usually happens automatically when configuring a flow computer tag. However, if you have a custom program in your flow computer or if you are using a device that is not officially supported by the flow computer tag (for example, one that uses a generic protocol like Enron Modbus) you may need to make changes, as follows.

Types of Override Files

There are three types of override files, which must be used in conjunction with one another. The configuration override file, the read definition file and the write definition file.

The configuration override file is the master map of all configuration addresses within the RTU. It details the address of each piece of information for every potential meter run number, as well as the units that should be used in association with that information. In addition, you can add in alarm messages associated with error codes that are read from the alarm and event logs.

The addresses provided in the configuration file completely replace the addresses in a standard flow computer tag with no configuration file defined. In addition to the configuration itself, this also means that any alarms or events received will be checked against only these addresses – if an alarm comes in for an address that is not part of the configuration file it will still be recorded, but the associated message will simply read “Unknown”.

The read override file contains instructions for how the individual read messages should be configured, as defined by a starting address and by the number of registers to read starting from that address. These blocks of addresses must encompass every meter run address that is defined in the configuration file.

The write override file is structured similarly to the read file; however, it does not have the same requirement that every meter run address from the configuration file be accounted for.

Adding an Override File to your Application

Override files are imported on the I/O Device tab of the Flow Computer tag’s configuration folder, by selecting the appropriate ‘Browse’ button. When selecting an override file, it does not matter which directory your file is in. As soon as you select the file, a copy is made and placed in a directory under your application called CSV_Overrides (e.g. C:\VTScada\MyApp\CSV_Overrides\MyFileName.CSV). This file is also added to your application as a permanent part of the repository, meaning it will automatically be shared between servers and will be included in any ChangeSets of the application. Any further updates to these files should be imported like any other application changes so that the changes can be passed around to all of the other potential servers.

Building a Configuration Override File

We recommend that you start your configuration file with the template provided within the Oil & Gas Solutions layer (C:\VTScada\Oil&GasSolutions\BuildInfo\ConfigurationTemplate.CSV). For a completed example, refer to the Bristol Controlwave file that is shipped as part of the Oil & Gas Solutions layer in the CSV_Overrides directory (e.g. C:\VTScada\Oil&GasSolutions\CSV_Overrides\Bristol_CWave_Config.CSV). The following descriptions refer to both the template and to the completed file.

Configuration Template Columns

MeterRunVarNum

This is an internal variable used by VTScada code and must be unique for each entry. This value should not be changed for any of the 372 rows that are included in the template. When adding additional rows for the purposes of adding alarm messages (more details in the alarm messages section below) the number in this column can be anything, provided it is unique.

MeterRunVarName

Another internal variable used when logging history records, this field should not be changed. When adding additional rows for alarm messages this can be left blank.

Description

A basic text description used to help identify the variable. This is purely for the benefit of the person editing this file and is not used by VTScada.

AlarmEventText

When alarms or events are reported by the RTU they are associated with a single address. The flow computer tag will look for that address in this configuration file, and if it is found then the text in the associated Alarm-EventText field is what will be saved as the alarm description.

UsedOnMeterConfigTab

All entries that have a 1 in this column will be user-editable on the meter configuration tab, assuming that an address is provided for that meter run. This field is not read by VTScada and is strictly for the information of the person building this configuration file.

UsedInCFX

All entries that have a 1 in this column will be included in any CFX reports that are generated based on this flow computer. This field is not read by VTScada and is strictly for the information of the person building this configuration file.

RunXAddress

The address of this entry for the given meter run. This address should be provided in the same format that you would use if you were entering it into the address field of an analog status tag.

GeneralAddress

The address of this entry if it is not associated with a particular meter run. These are most often used for general alarms and events; for example, there may be an alarm that gets generated by the RTU when it shuts down or boots up.

Droplist

This column is currently only used by two entries: 028_PipeMaterial and 031_OrificeMaterial. It maps the values sent back from the RTU to the droplist selections for those variables on the meter configuration tab. The con-tents of the field should be the droplist selections, separated by a semicolon, ordered based on their numerical value (starting from zero). For example, in RealFlo the three possible pipe materials are Stainless Steel (0), Monel (1), and Carbon Steel (2). The droplist field for such an entry should read:

Stainless Steel;Monel;Carbon Steel

In some cases, the values for the drop list entries may not be the standard 0, 1, 2, etc. In these cases the value associated with each entry may be entered alongside the label, seperated by a "|" character, as shown below:

Stainless Steel|9.61;Monel|7.72;Carbon Steel|6.2

Units

The units in this column will be shown on the meter configuration tab.

Customizing Alarm Messages

When an event is read from the RTU’s alarm and event log, the RTU provides the register, or address, that is associated with that event. When VTScada logs this data for screen display and reporting, it takes that address and looks it up in an internal mapping table to see whether we know what that alarm/event represents. If the address can’t be found in the table, the alarm/event is still logged but the associated message is set to “Unknown”.

If you are entering a custom set of configuration addresses you will also need to provide the alarm/event message mapping. Many of the messages will be covered by the variables in the template; for example, if the orifice material is changed in one of the meter runs then the address passed back from the RTU will usually be one listed next to the 031_OrificeMaterial entry. However, some alarms/events are not associated with a particular meter run variable. These messages will need to be added explicitly, at the end of the configuration CSV. Some examples are shown in the following figure.

Note that for these alarm messages only three fields are important.

MeterRunVarNum can be set to any value, but must be unique. In this example we started numbering the events at 10001, but this was an arbitrary choice.
AlarmEventMessage contains the text that should go into the alarm record.
The GeneralAddress column contains the address that should be associated with this text. An address (or ad-dresses) could also be placed in any of the other RunXAddress columns in addition to or in place of the GeneralAddress column.

Building a Read Override File

The Read Override File, based on ReadParmTemplate.CSV, is used to define the read messages that VTScada will use to retrieve all of the variables defined in the Configuration Override File. Please note that every address that is defined in the configuration file must be captured as part of the messages in this read file.

Read Template Columns

RunXStart – The first address in the request message.
RunXQuantity – The number of addresses to ask for in the request message.

If your addresses are numeric, like the Enron Modbus addresses in the RealFlo example below, then it is usually more efficient to ask for larger blocks of addresses at a time. Be careful not to exceed the maximum number of addresses that can be returned in a single message. Some knowledge of the message protocol may be required.

Some protocols may use text addressing, and in these cases VTScada is unable to define a numeric block in the usual way. In these cases, such as in the Bristol ControlWave example that follows, the quantity field must be set to 1 for each of the reads. This is not efficient, but this information is read infrequently and this is the only way to include all of the addresses.

Building a Write Override File

The Write Override File, based on WriteParmTemplate.CSV, is structured identically to the Read Override File. Unlike the read file, however, the write file need not include every address from the configuration file. Instead, this file need only include the parameters that may be changed by the user on the meter configuration tab, shown following:

RunXStart

The first address in the request message.

RunXQuantity

The number of addresses to ask for in the request message.