今天继续我们的小白教程，老鸟就不要在这浪费时间了😊。
前面一期我们介绍了CODESYS的文件操作库CAA File。这一期主要介绍CODESYS的SysFile库所包含的文件读写功能块，主要包括文件路径、名称、大小的获取以及文件的创建、打开、读、写、拷贝和删除功能等。
一、SysFile库简介
与上一期介绍的目录和文件操作库CAA File不同，SysFile属于CODESYS比较底层的库，其中结构和功能块的定义与C语言非常接近。使用该库需要在“库管理器”中添加SysFile库，这里使用的是3.5.15版本。
需要注意的是，SysFile库中所有功能均为函数（FUNCTION），与CAA File库中的功能块（FUNCTION_BLOCK）是不同。函数可以直接使用，而功能块需要先声明后使用。因为CODESYS的函数内部的变量在运行后是不会保留的，这个与功能块是不同。使用的时候要分清楚，避免因为初始状态不同导致的问题。
二、SysFile库的主要功能块
提供对运行时系统的文件功能的访问。仅能进行文件相关的操作。
1.基本定义
（1）文件访问模式ACCESS_MODE
定义文件打开的模式。
| 名称 | 初始值 | 说明 |
| AM_READ | 0 | 使用读取权限打开现有文件。如果文件不存在，则报打开失败错误。 |
| AM_WRITE | 1 | 创建具有写入权限的新文件。如果文件确实存在，则丢弃内容。 |
| AM_APPEND | 2 | 使用附加（仅写）权限打开现有文件。如果文件不存在，则打开失败。 |
| AM_READ_PLUS | 3 | 打开具有读/写权限的现有文件。如果文件不存在，则打开失败。 |
| AM_WRITE_PLUS | 4 | 创建具有读/写权限的新文件。如果文件确实存在，则丢弃内容。 |
| AM_APPEND_PLUS | 5 | 使用附加（读/写）访问权限打开现有文件。如果文件不存在，“打开”将创建一个新文件。 |
注意：对于所有*_PLUS模式，读取文件后，只能在调用SysFileGetPos或SysFileSetPos后才能进行写入！如果在SysFileRead之后立即调用SysFileWrite，则文件指针可能位于无效位置！正确的使用方式如下：
SysFileRead();
SysFileGetPos();
SysFileWrite();
（2）文件的时间戳SYS_FILETIME
定义文件的时间戳结构。
tCreation：文件创建时间。
tLastAccess：访问文件的时间。
tLastModification：上次修改的时间。
（3）文件状态SYS_FILE_STATUS
定义指定文件的实际文件状态。
| 名称 | 初始值 | 说明 |
| FS_OK | 0 | 文件已被打开。 |
| FS_NO_FILE | 1 | 没有可用文件。 |
| FS_ILLEGAL_POS | 2 | 文件中的非法位置。 |
| FS_FULL | 3 | 文件系统上没有多余空间。 |
| FS_EOF | 4 | 已达到文件结尾。 |
（4）错误码定义Errors
此错误码定义位于CmpErrors库中，文件读写中常用的如下表所示：
| 名称 | 初始值 | 说明 |
| ERR_OK | 16#0 | 操作成功 |
| ERR_FAILED | 16#1 | 操作失败 |
| ERR_PARAMETER | 16#2 | 参数错误 |
| ERR_NO_OBJECT | 16#10 | 指定的文件不存在 |
| ERR_NOTIMPLEMENTED | 16#C | 操作么有执行 |
| ERR_NOT_SUPPORTED | 16#18 | 操作不支持 |
由于错误定义较多，这里只列了比较常用的几个，上表中没有列出的可以参考官方文档。
2.文件操作函数
文件操作函数如下表：
| 函数名称 | 功能 | 备注 |
| SysFileOpen | 打开文件 | 成功则返回文件句柄 |
| SysFileRead | 读取文件内容 | 返回读取的字节数 |
| SysFileWrite | 写入文件 | 返回写入的字节数 |
| SysFileFlush | 缓冲内容写入文件 | 返回运行系统错误码 |
| SysFileClose | 关闭文件 | 返回运行系统错误码 |
| SysFileCopy | 拷贝文件 | |
| SysFileRename | 文件重命名 | |
| SysFileDelete | 删除文件 | |
| SysFileEOF | 检查文件是否到达结尾 | |
| SysFileGetPos | 获取文件指针当前位置 | |
| SysFileGetSize | 获取文件尺寸 | 返回值为文件尺寸 |
| SysFileGetTime | 获取文件最后修改时间 | |
| SysFileSetPos | 设置文件指针位置 | |
| SysFileGetName | 获取文件名称 | |
| SysFileGetPath | 获取文件路径 | |
| SysFileGetStatus | 获取文件状态？ | |
| SysFileTruncate | 重新设置文件尺寸 | |
| SysFileDeleteByHandle | 根据handle删除文件 | |
| SysFileGetSizeByHandle | 根据handle获取文件大小 | |
| SysFileGetName2 | 根据handle获取文件名称 | |
| SysFileGetStatus2 | 根据handle获取文件状态 |
3.常用的函数介绍
SysFile库文件操作函数的参数比较类似，下面对几个常用的函数进行介绍。
（1）SysFileOpen
szFile：文件名称。可以包含绝对或相对路径，注意路径需要用斜杠“/”表示，不能用反斜杠“\”。
am：打开模式，类型为SysFile.ACCESS_MODE。
pResult：返回运行系统错误代码，类型为POINTER TO RTS_IEC_RESULT，含义在CMPErrors库中定义，见第一部分介绍。
返回值：成功则返回文件句柄，类型为SysFile.RTS_IEC_HANDLE，失败则返回RTS_INVALID_HANDLE。
（2）SysFileClose、SysFileFlush
hFile：文件句柄，类型为SysFile.RTS_IEC_HANDLE。
返回值：返回运行系统错误代码，类型为RTS_IEC_RESULT。
（3）SysFileRead和SysFileWrite
hFile：文件句柄。
pbyBuffer：指向读或者写缓冲区首地址，类型为POINTER TO BYTE。
ulSize：需要读取或写入的字节数。注意必须小于等于缓冲区尺寸。
pResult：返回运行系统错误代码。
返回值：成功则返回读取或写入的字节，失败则返回0。数据类型为_XWORD，实际与DWORD等价。
（4）SysFileGetSize
szFileName：文件名称
pResult：返回运行系统错误代码。
返回值：文件尺寸。
（5）SysFileGetTime
szFileName：文件名称
ptFileTime：文件时间，类型为POINTER TO SYS_FILETIME。
返回值：返回运行系统错误代码，类型为SysFile.RTS_IEC_RESULT。
注意：以上函数中凡是类型为RTS_IEC_RESULT的返回值，如果是在函数中作为输入，则需要定义为指针POINTER TO RTS_IEC_RESULT或者使用ADR()来获取错误码；如果作为函数返回值，则为SysFile.RTS_IEC_RESULT。
三、SysFile库使用示例
SysFile库的函数可以直接一起顺序使用，也可以像CAA File库中的功能块一样按状态机的方式进行操作。以下示例为文件写入的分步操作。本次测试使用的控制器是禾川的Q0，使用其它控制器时需要正确指定可进行读写操作的目录位置。
程序变量定义如下：
PROGRAM testSysFile
VAR
bExecute : BOOL;
szFileName : STRING:='/testfile.txt';
pbyBuffer : POINTER TO BYTE;
ulSize : DWORD;
ErrorCode : INT;
Done : BOOL;
stContent : STRING:='hello everyone!';
Mode : SysFile.ACCESS_MODE := 1; //0-AM_READ; 1-AM_WRITE; 2-AM_APPEND; 3-AM_READ_PLUS; 4-AM_WRITE_PLUS; 5-AM_APPEND_PLUS
iStep : INT := 0; //运转流程
OP_TRIG : R_TRIG;
bError : BOOL;
hFile : SysFile.RTS_IEC_HANDLE;
pRes : SysFile.RTS_IEC_RESULT;
iRet : DWORD;
END_VAR
程序如下：
bExecute:=TRUE;
OP_TRIG(CLK := bExecute);
pbyBuffer:=ADR(stContent);
ulSize:=SIZEOF(stContent);
IF OP_TRIG.Q AND iStep=0 THEN
iStep := 1;
END_IF
CASE iStep OF
0:
IF bExecute=FALSE THEN
Done := FALSE;
ErrorCode := 0;
bError := FALSE;
END_IF
1:
hFile := SysFileOpen(szFileName, Mode, ADR(pRes)); //打开文件
IF (pRes<>0 OR hFile=SysFile.RTS_INVALID_HANDLE) THEN
bError := TRUE;
ELSE
iStep := 2;
END_IF
2:
iRet:=SysFileWrite(hFile, pbyBuffer, ulSize, ADR(pRes)); //内容写入文件
IF (iRet=0) THEN
SysFileClose(hFile);
bError := TRUE;
ELSE
iStep := 3;
END_IF
3:
pRes:=SysFileFlush(hFile); //缓存内容写入文件
IF (pRes=0) THEN
iStep := 4;
ELSE
SysFileClose(hFile);
bError := TRUE;
END_IF
4:
pRes:=SysFileClose(hFile); //关闭文件
IF pRes=0 THEN
Done := TRUE;
iStep := 0;
ELSE
bError := TRUE;
END_IF
END_CASE
//错误检查
IF bError THEN
iStep := 0;
ErrorCode := 1;
END_IF
注意：SysFile库的文件读写操作是不能被其它周期任务中断的。当需要读写的文件较大时，需要的时间会比较长。这时候需要把运行读写程序的任务周期调长，保证读写操作能够顺利完成。如果任务时间不够，可能会出现文件没有读完或者写完的情况。
四、结论
SysFile库实际上属于运行系统的文件操作函数，不管是操作方式还是参数定义都与C语言的对应函数类似，对C语言比较熟悉的朋友应该很容易上手。另外需要注意的是底层操作函数与平台相关性较大，比如读写时间与所使用的的控制器平台关系很大，最好是在自己使用的平台上做一些读写测试后设置合理的任务周期，避免出现文件读写不完整问题。
关于SysFile库读写大文件的问题，还有一种思路是把以上代码封装成功能块，在读或者写过程中把大文件拆分成尺寸较小的块，通过分步多次读写，每次进入读写流程时读或者写一块，直至所有内容读写完成。当然这个流程会复杂一些，嫌麻烦的还是直接用CAA File库来实现吧~~~^-^。
------------------
原创不易，感兴趣的多支持！
