📚 课程目录第3章错误与异常的数据结构

3. 错误与异常的数据结构

在 TestStand 中，错误信息并不是一段简单的字符串，而是一套结构化数据。理解这套数据结构，是后续编写错误处理回调、记录错误日志、实现测试恢复的前提。TestStand 的错误信息主要涉及两个层面：一是 LabVIEW 风格的 Error Cluster，二是 TestStand 自身的 Error 对象。两者在步骤间传递、在回调中访问、在日志中记录时各有不同的形态和用法。

Error Cluster：步骤间传递错误的标准载体

Error Cluster 是 LabVIEW 及 TestStand 中广泛使用的错误传递结构，它由三个核心字段组成：

status（布尔量）：表示是否发生错误。True 表示有错误，False 表示无错误。这是判断步骤是否失败的最直接依据。
code（32 位整数）：错误代码。0 表示无错误；非零值表示具体错误类型。正负号有约定：负数通常表示标准错误（如 LabVIEW 内置错误），正数通常表示自定义错误或警告。
source（字符串）：错误源，描述错误发生的位置或来源，例如“Step: MainSequence, Step: Test Voltage”或“LabVIEW: DAQmx Read.vi”。

在 TestStand 中，Error Cluster 通常作为步骤的输入/输出参数在序列中流动。一个典型的测试步骤执行后，如果发生错误，Error Cluster 的 status 变为 True，code 被赋值为具体错误码，source 记录步骤路径。后续步骤可以通过检查 Error Cluster 来决定是否继续执行、跳转或进入清理流程。

示例：假设某电压测试步骤调用 LabVIEW VI 读取 DAQ 数据，返回 Error Cluster 如下：

status = True
code   = -200279
source = "DAQmx Read.vi: 尝试读取的采样数超过可用采样数"

此时 TestStand 会将该步骤标记为失败，并将 Error Cluster 传递给后续步骤和回调。

TestStand Error 对象：更丰富的错误描述

除了 Error Cluster，TestStand 还提供了更完整的 Error 对象。它通常在回调（如 ProcessModelPostResultListEntry、SequenceFilePostStepFailure）中通过 RunState.Error 或 Parameters.Error 访问。Error 对象包含以下关键属性：

属性	类型	说明
Code	整数	错误代码，与 Error Cluster 的 code 对应
Msg	字符串	错误消息，描述错误的具体内容
Source	字符串	错误源，标识错误发生的步骤或模块
AdditionalData	容器/字符串	附加数据，可存放自定义诊断信息，如测量值、通道号、时间戳等
Severity	枚举	严重程度，如 Error、Warning、Information

Error 对象比 Error Cluster 多出了 Msg、AdditionalData 和 Severity 等字段，因此在错误记录和用户提示中更为常用。例如，在 ProcessModelPostResultListEntry 回调中，可以读取 Parameters.Error.Msg 获取可读的错误描述，读取 Parameters.Error.AdditionalData 获取自定义诊断信息。

错误代码、错误消息与错误源的协同关系

错误代码、错误消息和错误源三者共同构成错误的完整标识：

错误代码用于程序判断和分类。例如，代码 -200279 表示 DAQmx 读取超时，代码 1001 可能表示自定义的“电压超出范围”。
错误消息用于人阅读和日志记录。它通常由错误代码对应的描述文本生成，也可以自定义。
错误源用于定位问题。它记录错误发生的步骤名、VI 名或模块路径，帮助工程师快速找到故障点。

在 TestStand 中，当步骤发生错误时，引擎会自动填充 Error Cluster 的 code 和 source，但 Msg 可能为空或由底层驱动提供。若需要更友好的消息，可以在回调中根据 code 映射自定义消息，或直接在步骤中设置 Error 对象的 Msg 属性。

附加数据：携带诊断上下文

附加数据（AdditionalData）是 Error 对象中一个非常实用的字段。它允许在错误发生时携带额外的上下文信息，例如：

当前测试的通道号或引脚号
测量得到的实际值（如 5.12 V）与期望范围（4.75 V ~ 5.25 V）
时间戳或测试循环次数
设备序列号或工位号

附加数据通常以字符串或容器形式存储。在记录错误时，可以将 AdditionalData 一并写入测试报告或日志文件，便于后续分析。例如，在步骤失败时，通过 RunState.Error.AdditionalData 写入“Channel=3; Measured=5.12V; Expected=4.75~5.25V”，这样在日志中就能看到完整的诊断信息。

错误信息在步骤间的传递与记录

TestStand 中错误信息的传递遵循“沿序列流动、由回调捕获”的机制。具体来说：

步骤执行时，若发生错误，Error Cluster 的 status 置为 True，code、source 被填充。
该 Error Cluster 作为步骤的输出，传递给后续步骤。后续步骤可以选择检查 status 并决定是否继续。
在序列执行过程中，TestStand 引擎会在特定节点调用回调，如 ProcessModelPostResultListEntry，此时可以通过 Parameters.Error 访问 Error 对象。
在回调中，可以将 Error 对象的 Code、Msg、Source、AdditionalData 写入日志文件、数据库或测试报告。
若需要清除错误并继续执行，可以在回调中设置 Parameters.Error.Code = 0 或使用 RunState.Error.Clear() 方法。

提示：在 TestStand 中，Error Cluster 和 Error 对象可以相互转换。例如，在 LabVIEW 步骤中，Error Cluster 会自动映射到 TestStand 的 Error 对象；在自定义回调中，可以通过 RunState.Error 获取当前错误对象，再将其字段写入 Error Cluster 传递给后续步骤。

错误信息记录的实际操作示例

假设我们需要在 ProcessModelPostResultListEntry 回调中记录每个失败步骤的错误信息。可以按以下方式实现：

// 伪代码示例：在回调中读取 Error 对象并写入日志
If (Parameters.Error.Code != 0) Then
    LogFile.Write("错误代码: " + Str(Parameters.Error.Code))
    LogFile.Write("错误消息: " + Parameters.Error.Msg)
    LogFile.Write("错误源: " + Parameters.Error.Source)
    LogFile.Write("附加数据: " + Parameters.Error.AdditionalData)
End If

执行后，日志文件中会生成类似以下内容：

错误代码: -200279
错误消息: 尝试读取的采样数超过可用采样数
错误源: Step: MainSequence, Step: Read Voltage
附加数据: Channel=3; Measured=5.12V; Expected=4.75~5.25V

这样，工程师在分析测试失败原因时，不仅能看到错误代码和消息，还能看到具体的通道、测量值和期望范围，大大缩短排障时间。

Error Cluster 与 Error 对象的对比

对比项	Error Cluster	TestStand Error 对象
主要字段	status、code、source	Code、Msg、Source、AdditionalData、Severity
使用场景	步骤间传递、LabVIEW 交互	回调中访问、日志记录、报告生成
附加数据	无独立字段，需自定义	内置 AdditionalData 字段
严重程度	无	有 Severity 枚举

理解这两者的区别和联系，有助于在 TestStand 中正确选择错误处理方式。一般来说，步骤间传递错误使用 Error Cluster，而在回调中记录和分析错误使用 Error 对象。

总结来说，TestStand 的错误数据结构以 Error Cluster 和 Error 对象为核心。Error Cluster 负责步骤间的错误传递，包含 status、code、source 三个基本字段；Error 对象则在回调中提供更丰富的 Code、Msg、Source、AdditionalData、Severity 信息，便于记录和分析。错误代码用于程序判断，错误消息用于人阅读，错误源用于定位，附加数据用于携带诊断上下文。掌握这些字段的含义和传递机制，是编写健壮错误处理逻辑的基础。