This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

Control Message Activity in Stateflow Charts

A message is a Stateflow® object that communicates data locally or between charts in a Simulink® model. From a sender chart, you can send or forward a message. In the receiving chart, a queue receives the message and holds it until the chart can evaluate it.

Using Stateflow operators, you can access message data, and send, receive, discard, or forward a message. You can also determine whether a message is valid and find the number of messages in a queue. For more information, see Communicate with Stateflow Charts by Sending Messages.

Access Message Data

Stateflow messages have a data field. To read or write to the message data field of a valid message, use dot notation syntax:

message_name.data
If you send a message without first assigning a value to the message data, the default value for numeric data is 0. For enumerated data, the default is the first value listed in the enumeration section of the definition, unless you specify otherwise in the methods section of the definition.

You cannot access message data for messages that are still in the queue or that have already been discarded.

Send a Message

To send a message, use the send operator:

send(message_name)
For example, in this chart, the entry action in state A sends a message M with a data value of 3. If the message is Local, then the message goes in the local message queue. If the message scope is Output, then the chart sends the message through the output port to the input message queue of the receiving chart.

In a single time step, you can send multiple messages through an output port or to a local queue.

Guard Transitions and Actions

Messages can guard transitions or state actions of type on. During a time step, when the guarding message is evaluated for the first time, the chart removes the message from the queue and makes the message valid. While the message is valid, other transitions or actions can access the message data but they do not remove another message from the queue.

Guard a Transition with a Message

In this chart, a message M guards the transition from state A to state B. The transition occurs when both of these conditions are true:

  • A message is present in the queue.

  • The data value of the message is equal to 3.

If a message is not present or if the data value is not equal to 3, then the transition does not occur. If a message is present, it is removed from the queue regardless of whether the transition occurs.

Guard a State on Action with a Message

In this chart, a message M guards the on action in state A. When state A becomes active, it increments the value of x if both of these conditions are true:

  • A message is present in the queue.

  • The data value of the message is equal to 3.

If a message is not present or if the data value is not equal to 3, then the value of x does not change. If a message is present, it is removed from the queue regardless of whether x is modified.

Receive a Message

To receive a message, use the receive operator:

receive(message_name)
If a valid message M exists, receive(M) returns true. If a valid message does not exist but there is a message in the queue, then the chart removes the message from the queue and receive(M) returns true. If a valid message does not exist and there are no messages in the queue, receive(M) returns false.

For example, in this chart, the during action in state A checks the queue for message M and increments the value of x if both of these conditions are true:

  • A message is present in the queue.

  • The data value of the message is equal to 3.

If a message is not present or if the data value is not equal to 3, then the value of x does not change. If a message is present, it is removed from the queue regardless of whether x is modified.

Discard a Message

To discard a valid message, use the discard operator:

discard(message_name)
After a chart discards a message, it can remove another message from the queue in the same time step. A chart cannot access the data of a discarded message.

For example, in this chart, the during action in state A checks the queue for message M. If a message is present, the chart removes it from the queue. If the message has a data value equal to 3, the chart discards the message.

Forward a Message

To forward a message from an input queue to an output port, or to and from local message queues, use the forward operator:

forward(input_message_name, output_message_name)
After a chart forwards a message, it can remove another message from the queue in the same time step.

Forward an Input Message

In this chart, state A checks the input queue for message M_in. If a message is present, the chart removes the message from the queue and forwards it to the output port M_out. After the chart forwards the message, the message is no longer valid in state A.

Forward a Local Message

In this chart, state A checks the input queue for message M_in. If a message is present, the chart forwards the message to the local message queue M_local. After a delay of 0.3 seconds, the transition from state A to state B removes the message from the M_local message queue and forwards it to the output port M_out.

Determine if a Message Is Valid

To check if a message is valid, use the isvalid operator:

isvalid(message_name)
A message is valid if the chart has removed it from the queue and has not forwarded or discarded it. Use the isvalid operator to check if a message is valid in a Simulink model that contains more than one Stateflow chart.

For example, this chart first executes state A, as described in Discard a Message. When the chart executes state B, the during action checks whether the message M is valid. If the message is valid and has a data value equal to 6, the chart discards the message.

Determine the Length of the Queue

To check the number of messages in a message queue, use the length operator:

length(message_name)
For example, in this chart, the during action in state A checks the queue for message M. If a message is present, the chart removes it from the queue. If exactly seven messages remain in the queue, the chart increments the value of x.

Determine When a Queue Overflows

To check whether a message is lost because it was sent to a queue that was already full, use the overflowed operator:

overflowed(message_name)
In each time step, the value of this operator is set when a chart adds a message to, or removes a message from, a queue. It is invalid to use the overflowed operator before sending or retrieving a message in the same time step.

By default, when a message queue overflows, simulation stops with an error. To prevent a run-time error and allow the overflowed operator to dynamically react to dropped messages, set the value of the Queue Overflow Diagnostic property to Warning or None. For more information, see Queue Overflow Diagnostic.

Check for Input Message Overflow

To check the overflow status of an input message queue, first remove a message from the queue. You can:

  • Guard a transition with the message and the overflowed operator.

  • Guard a transition with the message and call the overflowed operator in the entry action of the destination state.

  • Guard a state on action with the message and call the overflowed operator in the action.

  • In a state action, use the receive operator followed by the overflowed operator.

Calling the overflowed operator before retrieving an input message in the same time step results in a run-time error.

Check for Output Message Overflow

To check the overflow status of an output message queue, first add a message to the queue. You can:

  • Use the send operator followed by the overflowed operator.

  • Use the forward operator followed by the overflowed operator.

Calling the overflowed operator before sending or forwarding an output message in the same time step results in a run-time error.

Check for Local Message Overflow

To check the overflow status of a local message queue, either add a message to the queue or remove a message from the queue before calling the overflowed operator. Calling the overflowed operator before sending or retrieving a local message in the same time step results in a run-time error.

See Also

| | | | | |

Related Topics