My Journey of Reflection: CAPL 编程系列教程 - 第三十二期时间处理函数

CAPL 编程 - 第 32 期：时间处理函数

目标: 本期介绍 CAPL 中用于获取和处理时间信息的常用函数，主要分为两大类：获取相对于测量开始的时间和获取系统当前的绝对时间。

1. 获取测量时间 (Relative Timestamps)

目的: 获取从 CANoe/CANalyzer 测量开始（点击“Start”按钮）到函数调用时刻所经过的时长。这对于精确测量事件间隔或记录相对于测试开始的时间戳非常有用。

函数:

timeNow()

功能: 返回自测量开始以来经过的时间。
单位: 10 微秒 (10 µs)。
返回类型: dword (无符号 32 位整数)。

示例:

Code snippet

dword elapsed_time_10us;
double elapsed_time_s;
elapsed_time_10us = timeNow();
// Convert to seconds (float division needed)
elapsed_time_s = elapsed_time_10us / 100000.0;
write("Elapsed time: %lu (10us) = %.3f s", elapsed_time_10us, elapsed_time_s);

timeNowNS()

功能: 返回自测量开始以来经过的时间，精度更高。
单位: 纳秒 (ns)。
返回类型: double (或 float, CAPL 中通常均为 8 字节浮点数)。

示例:

Code snippet

double elapsed_time_ns;
double elapsed_time_s;
elapsed_time_ns = timeNowNS();
// Convert to seconds
elapsed_time_s = elapsed_time_ns / 1000000000.0;
write("Elapsed time: %.0f ns = %.3f s", elapsed_time_ns, elapsed_time_s);

注意:
- 这些函数返回的是一个相对时间戳，起点是测量的开始时刻。
- 时间的精度和准确性依赖于所使用的 CAN 接口硬件（如 Vector VN 系列接口）。

2. 获取系统本地时间 (Absolute/Wall-Clock Time)

目的: 获取运行 CAPL 脚本的计算机当前的日期和时间（年、月、日、时、分、秒等）。这对于在日志或报告中记录事件发生的实际时间非常有用。
函数: getLocalTime()
- 功能: 获取操作系统的当前本地时间信息。
- 机制: 此函数没有返回值。它将时间的各个组成部分填充到一个作为参数传递给它的 long 类型数组中。
- 用法:
  1. 声明数组: long tm[9]; (数组大小至少为 9)。
  2. 调用函数: getLocalTime(tm);
  3. 访问结果: 调用后，时间信息存储在 tm 数组的不同索引位置。
数据结构 (long tm[9]): 数组 tm 的索引及其对应的含义如下（这与标准 C 语言中的 struct tm 结构体成员顺序和含义一致）：
- tm[0] (tm_sec): 秒 (0 - 59)
- tm[1] (tm_min): 分钟 (0 - 59)
- tm[2] (tm_hour): 小时 (0 - 23)
- tm[3] (tm_mday): 一个月中的第几天 (1 - 31)
- tm[4] (tm_mon): 月份 (0 - 11，其中 0 代表 1 月) - 需要加 1 才能得到实际月份。
- tm[5] (tm_year): 自 1900 年以来的年数 - 需要加 1900 才能得到实际年份。
- tm[6] (tm_wday): 一周中的第几天 (0 - 6，其中 0 代表星期日)。
- tm[7] (tm_yday): 一年中的第几天 (0 - 365)。
- tm[8] (tm_isdst): 夏令时标志 (通常 0 表示非夏令时，1 表示夏令时，具体依赖系统)。

示例:

Code snippet

long tm[9];
int year, month, day, hour, min, sec, weekday;

getLocalTime(tm); // Populate the tm array

// Extract and adjust values for display
year = tm[5] + 1900;
month = tm[4] + 1; // Adjust month (0-11 -> 1-12)
day = tm[3];
hour = tm[2];
min = tm[1];
sec = tm[0];
weekday = tm[6]; // 0=Sun, 1=Mon, ...

write("Current Time: %d-%02d-%02d %02d:%02d:%02d Weekday: %d",
      year, month, day, hour, min, sec, weekday);

注意: 必须对从数组中获取的月份 (tm[4]) 和年份 (tm[5]) 进行调整，才能得到符合日常习惯的显示格式。

总结: 本期学习了 CAPL 中两种主要的时间获取方式：timeNow/timeNowNS 用于获取高精度的、相对于测量开始的相对时间，常用于性能分析和事件计时；getLocalTime 用于获取操作系统当前的绝对时间（年月日时分秒），常用于日志记录和生成报告。理解它们的区别、单位、返回类型/机制以及如何正确使用和转换这些时间信息对于编写测试脚本非常重要。

CAPL 编程系列教程 - 第三十二期 时间处理函数

CAPL 编程系列教程 - 第三十二期时间处理函数