CAPL 编程系列教程 - 第二十六期：常用内置函数之写入文本文件

CAPL 编程系列教程的第二十六期内容 ，主要讲解如何在 CAPL 中向文本文件写入内容。

CAPL 编程系列教程 - 第二十六期：常用内置函数之写入文本文件

一、 课程回顾与本期目标

  • 回顾: 上一期（第二十五期）学习了如何从文本文件中读取内容。
  • 本期目标: 学习使用 CAPL 内置的文件操作函数向文本文件 (.txt) 写入字符串内容。
  • 应用场景: 在自动化测试脚本中，将测试过程中的关键数据、统计结果、日志信息、生成的报告等保存到文件中。

二、 写入文本文件的基本步骤 (三部曲)

  1. 打开文件 (用于写入): 使用特定函数打开或创建一个用于写入的文件，获取文件句柄。
  2. 写入内容: 使用特定函数将字符串内容写入到打开的文件中。可以多次写入。
  3. 关闭文件: 写入完成后，使用特定函数关闭文件，确保内容被刷新到磁盘并释放资源。

三、 涉及的 CAPL 函数

  1. openFileWrite(char filePath[], int mode)

    • 作用: 打开指定路径的文件，用于写入。
    • 参数:
      • filePath: 包含文件路径和名称的字符串。
        • 可以是相对路径（相对于 .cfg 工程文件目录）或绝对路径。
        • 如果文件不存在，该函数会自动创建一个新文件。
        • 如果目录不存在，可能导致失败 (需要确保路径中的目录已存在)。
      • mode: 打开模式（用于写入）。
        • 0: 文本模式 (Text Mode)，覆盖写入 (Overwrite)。如果文件已存在，其原有内容会被清空，然后从头开始写入新内容。
        • 1: 二进制模式 (Binary Mode)，覆盖写入 (Overwrite)。同上，但按字节写入。
        • 2: 文本模式 (Text Mode)，追加写入 (Append)。如果文件已存在，在文件末尾追加新内容，原有内容保留。
        • 3: 二进制模式 (Binary Mode)，追加写入 (Append)。同上，但按字节追加。
        • 常用模式: 写入文本文件常用 0 (覆盖) 或 2 (追加)。
    • 返回值 (dword):
      • 返回一个文件句柄 (File Handle) (非零整数) 代表成功打开/创建的文件。
      • 如果打开/创建失败，返回 0。

  2. filePutString(char buffer[], long bufferSize, dword fileHandle)

    • 作用: 将字符数组 buffer 中的字符串内容写入到由 fileHandle 指定的文件中。
    • 参数:
      • buffer: 包含要写入的字符串的字符数组。
      • bufferSize: 要写入的最大字节数。通常使用 elcount(buffer) (获取数组大小) 或 strlen(buffer) (获取实际字符串字节长度)。使用 strlen 可能更精确，避免写入多余的空字符，但需确保 buffer 本身是以 \0 结尾的有效字符串。注：char astr[10] = {'A','B','B','\0'} 才是字符串正确定义。
      • fileHandle: 由 openFileWrite 返回的文件句柄。
    • 返回值 (long):
      • 1: 表示写入成功。
      • 0: 表示发生写入错误。
    • 注意: 该函数不会自动添加换行符。如果需要换行，必须在要写入的字符串 buffer 中包含换行符 \n。

  3. fileClose(dword fileHandle)

    • 作用: 关闭由 fileHandle 指定的已打开文件。非常重要，调用此函数会确保所有缓冲数据被写入磁盘，并释放文件句柄资源。
    • 参数: fileHandle: 要关闭的文件的句柄。
    • 返回值: 可以忽略，或检查是否成功关闭。

四、 写入文件的实现逻辑

  • 基本写入:
    Code snippet
    variables {
  char dataToWrite[] = "Vehicle Speed is 90 km/h\n"; // 准备带换行符的数据
  dword fh;
  long writeResult;
}

on key 'a' {
  // 1. 打开文件 (覆盖模式)
  fh = openFileWrite("Files\\result.txt", 0); 
  if (fh == 0) { write("错误: 无法打开/创建文件!"); return; }

  // 2. 写入字符串
  writeResult = filePutString(dataToWrite, strlen(dataToWrite), fh); // 使用 strlen 获取实际长度
  write("写入结果 (1=成功, 0=失败): %d", writeResult);

  // 可以继续调用 filePutString 写入更多行...
  // filePutString("Another line\n", strlen("Another line\n"), fh);

  // 3. 关闭文件
  fileClose(fh);
  write("文件写入完成并关闭。");
}
  • 追加写入:
    • 只需将 openFileWrite 的 mode 参数改为 2 即可。
    • 每次执行脚本时，新的内容会添加到 result.txt 文件的末尾，而不是覆盖原有内容。

五、 注意事项

  • 文件路径: 确保 openFileWrite 中的路径正确，特别是相对路径的基准点是 .cfg 工程文件所在目录。推荐将数据文件放在工程子目录中。
  • 缓冲区与写入长度: filePutString 的第二个参数 bufferSize 通常应传递要写入字符串的实际字节长度 (strlen)，以避免写入不必要的空字符或导致截断。
  • 换行符: filePutString 不会自动添加换行，需要在写入的字符串中显式包含 \n。
  • 关闭文件: 必须调用 fileClose 来确保数据写入磁盘并释放资源，尤其是在长时间运行或循环写入的场景中。
  • 错误处理: 实际应用中应检查 openFileWrite 和 filePutString 的返回值，处理可能发生的错误。

六、 总结与后续

  • 本期学习了在 CAPL 中向文本文件写入数据的标准三步流程：打开 (openFileWrite，注意选择写入模式）、写入 (filePutString)、关闭 (fileClose)。
  • 理解了覆盖写入 (mode=0) 和追加写入 (mode=2) 的区别。
  • 掌握了如何将字符串（包括换行符）写入文件。
  • 文件写入是 CAPL 脚本输出结果、记录日志、生成报告的重要手段。
-