CSV Data Driver
The CSV Data Driver imports values from a comma-separated file(s). Originally developed for use with the Oil & Gas Solutions layer, this driver can be configured for use with any comma-separated values file.
(The driver can only import values. It will not write to a CSV file.)
I/O Tags configured to use the CSV Data Driver use a custom addressing scheme to assist the driver in assigning these values to the proper VTScada IO tag.
Data Processing
The CSV Data Driver will periodically check a specified folder for comma-separated files. When a file is found, and I/O tags are configured to use the CSV Data Driver, values from the file will be imported into VTScada, assigned to I/O tags and stored in the VTScada Historian. All files within the folder must have the same structure or format, including how date and time values are stored. If there is variation, use a separate CSV Data Driver for each version, and store those files either in separate folders or using separate extensions.
Archiving
When a file is processed successfully, it will be moved to an archival folder under the scanned folder using the following naming format:
C:\VTScada\<your application>\<scanned directory>\Archive\Year\Month
The CSV file name will have the date and short time appended to the file name:
<original filename>-2019-06-21-11-25.csv
Fault Handling
If configuration issues are encountered with the CSV Data Driver or with the IO tag addressing, the file will be moved to a Faults folder under the scanned folder as follows:
C:\VTScada\<your application>\<scanned directory>\Faults\Year\Month
The file will be renamed by appending the current date and time to the filename and the file extension will be changed to the error number of the configuration error. For example:
<original filename>.csv
Will be renamed to:
<original filename>-2019-06-21-11-25.csv101
CSV Data Driver properties ID tab
The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.
Name:
Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.
You may right-click on the tag's name to add or remove a conditional start expression.
Area
The area field is used to group similar tags together. By defining an area, you make it possible to:
- Filter for particular tag groups when searching in the tag browser
- Link dial-out alarm rosters to Alarm tags having a particular area
- Limit the number of tags loaded upon startup.
- Filter the alarm display to show only certain areas.
- Filter tag selection by area when building reports
When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)
To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.
You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).
To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.
There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).
Description
Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.
Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.
The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.
This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.
Help Search Key
Used only by those who have created their own CHM-format context sensitive help files to accompany their application.
Server List
Select (or create) a named server list.
CSV Data Driver: File/DIR properties tab
Directory to Scan
Use to select the folder where the CSV files to be imported will be placed. The default location is a folder named "CSV Files" below your application's Data folder but, you may select any folder you wish.
Archive and Fault folders are created below the one specified here.
File Spec
Only files with the specified extension are read. Defaults to *.csv (The file extension is not case-sensitive.)
Select if the data in your files is structured according to the California Metering Exchange Protocol standard. Must not be selected otherwise.
Header Row in File
Select if the first row in your CSV contains column headers rather than data.
File Uses Unique Keys
Select if rows contain unique identifiers specifying which location (and therefore tag) a value belongs to. Unique keys are optional but must be used if the CSV file contains data for more than one tag..
For example, the data file may contain temperature readings, all stored in a column identified as "Temperature". Those readings may come from several sites (Site 1, Site 2, ...) which are stored in a column identified as "Site". The unique keys are therefore "Site1, Site 2, ...". Addressing within your I/O tags will ensure that each site's temperature reading is written to the correct tag.
Key Column (0-based)
Identifies which column contains the Unique Key. Columns are counted from the left of each row, starting with zero.
Parameters in One Column
This is a choice between two possible formats of CSV file.
In format 1, there is a separate column for each type of parameter value. For example all temperature values in one column and all pressure values in another. If your CSV file follows this format, select this option.
In format 2, there are two columns (in addition to those for date and the optional unique identifier), where the first identifies the parameter, ("Temperature", "Pressure") and the second holds the value for that parameter. If your CSV file follows this format, select this option.
Parm Column (0-based)
If the option, Parameters in One Column is selected, use this to identify which column contains the parameter names. Columns are counted from the left of each row, starting with zero. The column holding the matching data values is specified as part of the I/O tag's address.
File Time Zone
If the data was collected in a time zone other than where the files are being processed, use this selector to identify that time zone.
Directory Scan Rate (secs)
Specifies how often VTScada will scan for new CSV files in the identified folder. Defaults to 3600, meaning hourly.
File Process Rate (secs)
Specifies a delay between processing of files, if more than one is found during a director scan. Defaults to zero, meaning no delay.
Trigger
May be linked to any tag or expression in order to initiate a directory scan as needed.
CSV Data Driver: Date/Time Mappings tab
Both date and time can be represented in many ways. Use this to configure the CSV Data Driver to read date and time values correctly according to how they are stored. All of the CSV files being read by this driver must use the same format.
Date values are mandatory and must be included in your CSV file. Time values are optional and will default as specified in this panel if not present.
The format of dates and times is described using "percent-specifiers", which are defined as follows.
| %d- | Reads a value in the date up to a "-" as an integer |
| %d/ | Reads a value in the date up to a "/" as an integer |
| %d: | Reads a value in the date up to a ":" as an integer |
| %s | Reads a value as a string of characters until a space, or the end of the string, is reached. Typically used to read "AM" or "PM" in a time. ** Note: This can be used the same as %d above. For example, %s- will read a string of characters up until a “-“ is encountered in the date |
"d" is used for all parts of the date and time; year, month and day / hours, minutes and seconds. Other configuration options specify the order of the parts where there may be ambiguity.
Following are several optional specifiers, useful for reading the date and time fields of the CSV Data Driver. Advanced users should also note that any specifier described in the VTScada Help for the BuffRead() function can be used.
| %[^-]- |
Reads a string of characters until the character after the “^” is encountered. Use if months in the date are textual (i.e. Jan or January) |
|
“-“ “/” “:” <space> |
Possible separators between each portion of the date. Examples follow: 01-17-2019 12:00:00 PM Or 01/17/2019 12:00:00 PM |
Time & Date Separate Columns
Select if your CSV file contains a separate column for time data. When not selected, configuration options related to a separate time column are disabled.
Date Column (0-based)
Identifies which column contains the Date. Columns are counted from the left of each row, starting with zero. Enabled only if you have specified that date and time are contained in separate columns.
Time Column (0-based)
Identifies which column (if any) contains the Time. Columns are counted from the left of each row, starting with zero.
Date Column Format
Use percent-specifier codes as described earlier to describe how dates (and times if both are in a single column) are formatted in your CSV files. All files read by this driver must use the same format.
Year Offset
If the year value in a date is written with four digits, there is no need for an offset.
If the year value is written with two digits, this number is added to the two-digit value. CSV files that contain dates that span the year 2000 must use four-digit dates.
Year Position
Identifies which number in a date string contains the year value. Counts from the left starting at one.
Month Position
Identifies which number in a date string contains the month value. Counts from the left starting at one.
Day Position
Identifies which number in a date string contains the day value. Counts from the left starting at one.
Default Time
All values are stored as UTC time stamps with both date and time. If a time value is not provided with the record, it is stored using the value specified here.
Time Format
Use percent-specifier codes as described earlier to describe how time values are formatted in your CSV files. . The CSV Data Driver assumes the timestamp uses the 12-hour clock and AM/PM is included in the CSV file data. The time suffixes, AM and PM, are not required if the timestamps use the 24-hour clock.
The Time Format string should always be modified to match the expected format of the timestamp format used in the CSV file. For example, if the timestamp does not include seconds, (for example, 02:00 PM), the Time Format string should be modified as follows:
%d:%d %s
Enabled only if you have specified that date and time are contained in separate columns.
CSV Data Driver Widgets
The following widgets are available to display information about your tags:
CSV Data Driver Statistics Dialog
