on message

Handle a received message event

Within an on message procedure, this refers to the triggering message. A numeric ID and channel can narrow the event selector; further checks such as direction, remote-frame status and DLC make the assumptions visible.

Example: observe one data frame

on message CAN1.0x200
{
  if (this.DIR != Rx || this.RTR != 0) return;
  if (this.DLC < 1)
  {
    write("0x200 has no first payload byte");
    return;
  }
  write("CAN1 0x200 byte 0: 0x%02X", this.byte(0));
}

Use a configured CAN1 classical CAN stream for this example. It is an observation handler, not a gateway, and it does not forward or retransmit the message. The periodic message tutorial supplies a controlled sender and explains checking payload length.

Node placement changes the forwarding question

The authorized reference distinguishes CAPL nodes in a measurement evaluation branch from nodes in a simulation setup. An evaluation-branch CAPL node can block data from reaching downstream consumers unless forwarding is implemented. In a simulation setup, blindly outputting every received message can instead resend traffic onto the bus.

Do not copy a generic output(this) handler until you have decided which setup is in use and what should be forwarded. An observer and a gateway are different programs. For a gateway, define source/destination channels, allowed IDs, directions and loop prevention before implementing forwarding.

Checks before trusting the output

• Confirm that CAN1 is the intended channel and that the sender uses the same ID and frame format.
• Interpret Rx at the actual node placement; do not use a label alone as proof of the physical source.
• Check DLC before accessing payload bytes. Reading a zero-length or remote frame as application data is not a valid test.
• For timing, compare the timestamp attached to this event with a previous matching event. See message period measurement.

The example is classical CAN-specific; do not assume its DLC interpretation handles CAN FD payloads.

Separate event selection from application acceptance

An event selector narrows which events reach a handler; it does not validate a payload contract. For the example, CAN1 and 0x200 identify the intended observation stream, DIR and RTR reject other event kinds, and DLC protects the byte access. None of these checks establishes that byte 0 contains a permitted command or that an ECU acted on it.

Use separate counters for eligible events and accepted payloads when investigating a mismatch. If Trace shows ten eligible frames but only eight payloads pass an application check, reporting “two missing frames” confuses rejection with absence. Preserve the two rejected rows and the reason for rejecting each one. If the handler sees only eight events in the first place, inspect upstream filtering and node placement before the application decoder.

Run these as separate trials in the intended configuration, not as claimed results from this page. In an FD-capable setup, explicitly select or exclude FD frames before reusing this classical-CAN example. A channel name alone does not prove that every observed frame uses one format. For a repeatable filtering contract and a worked counterexample, see identify one CAN message stream.

Source and validation

API signatures and behavior follow the authorized Vector reference. The explanations and inspection examples are site guidance, not recorded CANoe test results. Check the installed help for your tool version and node type. See sources and validation limits.