Detailed Description

The CSVFileReader makes it possible to map contents from a .csv (or similar) file into Arguments.

The CSV File Format

CSV (Comma-Separated Values) files attempt to represent table-data. A CSV file is a delimiter based file, where each item is delimited (separated) by a character, typically one of ; (semicolon), , (comma), \t (tab), or some other character that is not used in the data that the file holds. The CSV file typically has a header containing the names (and order) of the data items. It can also have comments and empty lines, that the machine parser skips. Here is a short example .csv file content:

# this is a comment
A1;A2;A3
1;10;100
2;11;101
3;12;102

The file above is typically interpreted like this:

• Line1 is a comment, and is skipped.
• Line2 is the header. It lists the names of the values in the file. Typically, A1 is the first column, A2 is the second column, and so on.
• Line3 contains the first set of values: A1=1,A2=10 and A3=100
• Line4 contains the second set of values: A1=2,A2=11 and A3=101
• Line5 contains the last set of values: A1=3,A2=12 and A3=102

CSVFileReader Usage

The CSVFileReader is typically configured with FileName, Delimiter and SkipPrefix. These are internal Arguments that can be set by editing them inside the CSVFileReader instance.

To tell the CSVFileReader which items from the header should be used, add arguments with names matching the CSV header names to the CSVFileReader. The Argument type must match the datatype of the content of the .csv file, or else the content will be truncated or misrepresented. Make sure to update the Line Data member with all the Arguments to emit. Connect the Read from a trigger source, and connect the Line to where you want to process the data.

For the CSV example above, add 3 Argument<unsigned int> named A1, A2 and A3 to the CSVFileReader. Select each argument and uncheck the Input property to make the arguments appear on the output side of the CSVFileReader ServiceBlock. Select Line, then select the Data property and make sure that A1, A2, A3 and Index are checked (The Index argument can be used to keep track of the sequence currently being emitted).

How It Works

The CSVFileReader has two different modes, selectable by HeaderMapping. It is possible to choose between HeaderMapsToColumns (the default) and HeaderMapsToRows.

If HeaderMapping=HeaderMapsToColumns; when the CSVFileReader Read event is triggered, the following happens (pseudo-code):

• The file is opened and read line by line. If error, Error is emitted.
• The first non-empty, non-skipped line is identified as the header, and is mapped against the arguments in Line.Data. If error, Error is emitted.
• For each line in the file, map values from that line into the corresponding arguments. If error, Error is emitted, else a Line EventOut is emitted:
• In the first Line, A1=1, A2=10, A3=100 and Index=0.
• In the second Line, A1=2, A2=11, A3=101 and Index=1.
• In the third Line, A1=3, A2=12, A3=102 and Index=2.
• The file is closed and Done is emitted.

If HeaderMapping=HeaderMapsToRows; when the CSVFileReader Read event is triggered, the following happens (pseudo-code):

• The file is opened and read line by line. If error, Error is emitted.
• The first non-empty, non-skipped line is identified as the header, and is mapped against the arguments in Line.Data. If error, Error is emitted.
• Each line in the file is read, and values from that line is mapped into an array. If error, Error is emitted.
• When the amount of lines read matches the number of items in the header, values from the array are mapped in a left to right manner (column by column) into the correct arguments. Each data-set is emitted using the Line EventOut:
• In the first Line, A1=1, A2=2, A3=3 and Index=0.
• In the second Line, A1=10, A2=11, A3=12 and Index=1.
• In the third Line, A1=100, A2=101, A3=102 and Index=2.
• The file is closed and Done is emitted.

Events and Arguments

The CSVFileReader ServiceBlock has the following events:

The following Arguments can be used to configure the CSVFileReader:

Troubleshooting

During debugging and testing, we recommend connecting the Error EventOut to a Sequencer::DebugPrinter ServiceBlock to quickly identify issues caused by incorrect configuration or corrupt .csv files.