Codesys的文件操作功能块应用

电气自动化控制中，数据的持久化存储是必备功能，例如记录配方、保存故障日志或存储生产数据。Codesys 提供的 SysFile 库包含了一系列用于文件操作的功能块，能够像在电脑上操作文本文档一样处理控制器内部存储或外部 SD 卡中的文件。

准备工作：添加标准库

在使用任何文件操作功能块之前，必须先将标准库添加到项目中。

1. 打开 Codesys 项目，在左侧设备树中 找到 “库管理器”。
2. 右键点击 “库管理器”， 选择 “添加库”。
3. 在 搜索框中 输入 SysFile。
4. 选中 SysFile 库， 点击 “添加” 按钮。
5. 确认 库出现在列表中， 关闭 窗口。

核心概念与变量定义

文件操作遵循标准的“打开-操作-关闭”流程。核心变量通常包括文件句柄、文件路径和操作结果。

在程序的变量声明区（例如 VAR）， 定义 以下关键变量：

VAR
    // 文件句柄，相当于文件的身份证，值为0表示未打开
    hFile      : RTS_HANDLE;

    // 文件路径，注意路径格式取决于控制器操作系统
    sFileName  : STRING := 'C:\Log\data.txt';

    // 要写入的数据内容
    sDataWrite : STRING := 'Hello Codesys World';

    // 读取到的数据缓冲区
    sDataRead  : STRING(255);

    // 操作状态反馈
    nResult    : INT;

    // 执行触发信号
    bWrite     : BOOL := FALSE;
    bRead      : BOOL := FALSE;
END_VAR

步骤一：创建文件并写入数据

写入数据需要按顺序调用 FileOpen、FilePuts（或 FileWrite）和 FileClose。这里使用 FilePuts 写入字符串，因为它会自动处理换行符。

1. 编写 以下逻辑代码到程序体中：

// 写入触发逻辑
IF bWrite THEN
    // 1. 打开文件
    // 参数：文件名, 访问模式(4=WRITE)
    hFile := SysFile.FileOpen(sFileName := sFileName, am := SysFile.FILE_OPEN.WRIT);

    // 2. 检查句柄，如果大于0表示打开成功
    IF hFile > 0 THEN
        // 3. 写入一行字符串
        nResult := SysFile.FilePuts(hFile := hFile, str := sDataWrite);

        // 4. 关闭文件（非常重要，不关闭会导致数据丢失或文件被占用）
        SysFile.FileClose(hFile := hFile);

        // 操作完成后复位触发信号
        bWrite := FALSE;
    ELSE
        // 打开失败处理
        bWrite := FALSE;
    END_IF
END_IF

2. 观察 代码逻辑：
   • SysFile.FILE_OPEN.WRIT 表示写入模式。如果文件不存在，系统会 自动创建 它；如果文件已存在，内容会被 清空。
   • hFile 是后续所有操作的前提，必须 校验 其有效性。

步骤二：读取文件内容

读取文件使用 FileGets 按行读取，或者使用 FileRead 按字节读取。此处演示读取文本文件的第一行内容。

1. 追加 以下读取逻辑代码：

// 读取触发逻辑
IF bRead THEN
    // 1. 打开文件
    // 参数：文件名, 访问模式(1=READ)
    hFile := SysFile.FileOpen(sFileName := sFileName, am := SysFile.FILE_OPEN.READ);

    // 2. 检查句柄有效性
    IF hFile > 0 THEN
        // 3. 读取一行内容到缓冲区 sDataRead
        // 参数：文件句柄, 存储缓冲区, 缓冲区最大长度
        nResult := SysFile.FileGets(hFile := hFile, str := sDataRead, size := 255);

        // 4. 关闭文件
        SysFile.FileClose(hFile := hFile);

        // 复位触发信号
        bRead := FALSE;
    ELSE
        // 文件打开失败
        bRead := FALSE;
    END_IF
END_IF

2. 注意 size 参数必须小于或等于 sDataRead 声明的字符串长度（此处为 255），防止缓冲区溢出。

常用文件访问模式对照表

SysFile.FileOpen 的 am 参数决定了文件打开的方式。

实用技巧：追加写入日志

在实际工程中，通常需要保留历史记录，因此“追加模式”最为常用。

1. 修改 步骤一中的打开语句，将 am 参数 替换 为 SysFile.FILE_OPEN.APPEND。
2. 结合 系统时间生成文件名，避免单一文件过大：

// 变量定义需增加
VAR
    dtNow : DT;
    sLogFileName : STRING;
END_VAR

// 代码逻辑
dtNow := NOW(); // 获取当前时间
// 格式化为文件名，例如 Log_2023-10-27_10-00-00.txt
sLogFileName := CONCAT('C:\Log\Log_', DT_TO_STRING(dtNow, format:=DT_FORMAT.DD_MM_YYYY));

// 打开文件时使用追加模式
hFile := SysFile.FileOpen(sFileName := sLogFileName, am := SysFile.FILE_OPEN.APPEND);

错误处理与调试

文件操作常因路径错误或权限问题失败，必须进行完善的错误处理。

1. 利用 SysFile.FileError 获取详细的错误代码。
2. 编写 错误诊断逻辑：

IF hFile = 0 THEN
    // 获取最后一次操作的错误码
    nResult := SysFile.FileError();

    // 常见错误码判断
    CASE nResult OF
        SysFile.FILE_ERROR.ERR_PATHNOTFOUND: 
            // 路径不存在，需检查文件夹是否创建
            ; 
        SysFile.FILE_ERROR.ERR_FILENOTFOUND: 
            // 文件不存在（读取模式下）
            ;
        SysFile.FILE_ERROR.ERR_ACCESSDENIED: 
            // 权限不足或SD卡只读
            ;
    END_CASE;
END_IF

注意事项总结

1. 路径规范：
   Windows 控制器路径通常使用 C:\Dir\File.txt。
   Linux 控制器（如 Raspberry Pi）路径使用 /home/codesys/File.txt。
   请务必查阅控制器手册确认存储介质路径。

2. 资源释放：
   每次调用 FileOpen 后，无论读写成功与否，必须 执行 FileClose。未关闭的句柄会占用系统资源，最终导致无法打开新文件。

3. SD 卡使用：
   如果使用外部 SD 卡，确保 Codesys 系统配置中已正确挂载该路径，并检查卡是否写保护。

4. 文件并发：
   Codesys 的 SysFile 库不支持多任务同时写入同一个文件。如果多个程序块需要写日志，应使用互斥锁或统一由一个管理器处理。