FB_CsvRead功能描述

概述

类型：	功能块
最低适用版本：	V1.0.8.0
继承：	-
执行：	-

功能描述

功能块 FB_CsvRead 用于读取控制器文件系统上的或者扩展存储器（例如，SD 存储卡）上的 CSV 文件。有关文件系统的更多信息，请参阅您控制器编程指南中的章节闪存组织。

要读取的 CSV 文件包含安排在单个记录（行）中的多个值（列）。值由特定的定界符分隔。记录由换行符分隔。

基于定界符的指定字符代码，功能块在读取文件内容的同时识别具体的值。换行符的字符代码取决于已创建有文件的操作系统。此功能块支持三种最常用的换行符字符代码 (ASCII)。它在读取文件内容的同时检测所使用的换行符字符。

支持的换行符字符 (ASCII) 如下：

oCRLF (0D0A hex)：用于诸如 Windows 和 MS-DOS 的操作系统。

oLF (0A hex)：用于诸如 Unix, Linux, Mac OS X 和 Android 的操作系统。

oCR (0D hex)：用于诸如 Mac OS X（第 9 版或更早的版本）的操作系统。

从指定文件读取的值以 STRING 类型变量的形式存储在应用程序提供的读取缓冲区中。将应用程序中的读取缓冲区声明为 ARRAY 类型的二维 STRING。使用输入 i_stTableReadValues 来提供数组的维度并向功能块提供指向该数组的指针。有关更多信息，请参阅结构 ST_CsvTable。

执行功能块时，输入i_stTableReadValues.pbyTable存储在内部以供日后使用。如果在执行功能块时检测到在线更改事件 (q_xBusy= TRUE)，则会以输入的当前值来更新内部使用的变量。

注意：执行功能块时，不得将 i_stTableReadValues.pbyTable重新分配给另一个存储区。

要读取的文件必须仅包含 ASCII 字符，以有助于确保应用程序中的文件内容被正确提供。文件在开头处可包含字节顺序标记 (BOM)，用于指示已处理的文件的编码。ASCII 编码的文件不包含 BOM。功能块检查指定的文件是否包含特定 BOM。

如果文件包含以下其中一个 BOM，则会取消功能块的执行，并显示错误：

FE FF hex、FF EF hex 或 EF BB BF hex

使用输入 i_stReadParameter 来确定要读取的数据量。您可以读取文件的全部内容。您也可以选择单个记录（行）、单个列或单个值来读取。另外，您还可以仅读取由输出 q_stFileInformation 提供的文件信息。

注意：此功能在执行读取操作之前擦除数组。

接口

输入	数据类型	描述
i_xExecute	BOOL	功能块在该输入的上升沿对指定的 CSV 文件执行读取操作。另请参阅章节功能块在输入 i_xExecute 下的行为。
i_sFilePath	STRING[255]	CSV 文件的文件路径。如果指定的文件名不包含扩展名，则功能块会添加扩展名 .csv。
i_stReadParameter	ST_CsvReadParameter	指定要从文件中读取的内容。请参阅 ST_CsvReadParameter。
i_timTimeout	TIME	在经过了这个时间之后，会取消执行。如果值为 T#0s，则应用缺省值 T#2s。
i_stTableReadValues	ST_CsvTable	用于将应用程序提供的缓冲区传送到功能块的结构（请参阅 ST_CsvTable 结构）。

输出	数据类型	描述
q_xDone	BOOL	如果此输出设置为 TRUE，则执行已成功完成。
q_xBusy	BOOL	如果此输出设置为 TRUE，则正在执行功能块。
q_xError	BOOL	如果此输出设置为 TRUE，则检测到错误。有关详细信息，请参阅 q_etResult和 q_etResultMsg。
q_etResult	ET_Result	以数字值的形式提供诊断和状态信息。如果 q_xBusy= TRUE，该值指示状态。如果 q_xDone或 q_xError = TRUE，该值指示结果。
q_sResultMsg	STRING[80]	以文本消息的形式提供附加的诊断和状态信息。
q_stFileInformation	ST_CsvFileInfo	结构包含与已处理的最后一个文件有关的信息。
q_stWarnValueTruncated	ST_CsvWarnValueTruncated	提供与已删节的第一个值（如果可用）有关的信息。注意：输出与 q_xDone 一起更新。

有关基本输入和输出的更多信息，请参阅章节功能块在输入 i_xExecute 下的行为。

POINTER TO … 或 REFERENCE TO … 类型的变量的使用

此功能块提供类型为 POINTER TO…或REFENCE TO… 的输入和/或输入/输出。在使用这种指针或引用的情况下，功能块访问被寻址的存储区。如果是在线更改事件，存储区可能转移到新地址，从而导致指针或引用无效。为了防止与无效指针相关的错误，必须循环更新或者至少在其使用循环开始时更新 POINTER TO…或 REFERENCE TO… 类型的变量。