FB_CsvRead Functional Description

Overview

 

 

Functional Description

The function block FB_CsvRead is used to read a CSV file located on the file system of the controller or on the extended memory (for example, an SD memory card). For information on the file system, refer to the chapter Flash Memory Organization in the Programming Guide of your controller.

The CSV file to read contains a number of values (columns) which are arranged in single records (rows). The values are separated by a specific delimiter. The records are separated by a line break.

Based on the specified character code for the delimiter, the function block identifies the individual values while reading the content of the file. The character code for the line break depends on the operating system where the file has been created. The function block supports the three most commonly used line break character codes (ASCII). It detects the line break character used while reading the content of the file.

The following line break characters (ASCII) are supported:

oCRLF (0D0A hex): Used on operating systems such as Windows and MS-DOS.

oLF (0A hex): Used on operating systems such as Unix, Linux, Mac OS X, and Android.

oCR (0D hex): Used on operating systems such as Mac OS X version 9 or earlier.

The values read from the specified file are stored in the read buffer provided by the application in variables of type STRING. Declare the read buffer in the application as a two-dimensional ARRAY of type STRING. Use the input i_stTableReadValues to provide the dimensions of the array and the pointer to that array to the function block. For further information, refer to the structure ST_CsvTable.

When executing the function block, the input i_stTableWriteValues.pbyTable is stored internally for further use. In case an online change event is detected while the function block is executed (q_xBusy = TRUE), the internally used variables are updated with the present value of the input.

NOTE: Do not reassign the i_stTableWriteValues.pbyTable to a different memory area while the function block is executed.

The file to be read must contain only ASCII characters to help ensure the correct rendition of the content of the file in the application. Files can contain a byte order mark (BOM) at the beginning which indicates the encoding of the processed file. ASCII-encoded files do not contain a BOM. The function block verifies the specified file for specific BOMs.

In case the file contains one of the following BOMs, the execution of the function block is canceled and an error is indicated:

FE FF hex, FF EF hex, or EF BB BF hex

Use the input i_stReadParameter to determine the amount of data to be read. You can read the entire content of the file. You can also select a single record (row), a single column, or a single value to be read. Further, you can select to read only the file information which is provided by the output q_stFileInformation.

Interface

For more information about the signal behavior of the basic inputs and outputs, refer to the chapter Behavior of Function Blocks with the Input i_xExecute.

Usage of Variables of Type POINTER TO … or REFERENCE TO …

The function block provides inputs and/or in/outputs of type POINTER TO… or REFENCE TO…. With the use of such a pointer or reference, the function block accesses the addressed memory area. In case of an online change event, it may happen that memory areas are moved to new addresses and in consequence a pointer or reference becomes invalid. To prevent errors associated with invalid pointers, variables of type POINTER TO… or REFERENCE TO… must be updated cyclically or at least at the beginning of the cycle in which they are used.