Specifying message parameters

You reference event arguments in a statechart using the pseudo-variable params‑> with the following syntax:

event/params->event_arg1, params->event_arg2

Consider a class Firecracker that processes an event discharge, which has an argument color. The argument color is of an enumerated type Colors, with the possible values red (0), green (1), or blue (2). In the statechart, you would indicate that you want to pass a color to the event when it occurs using the following label on the transition:

discharge/params->color

When you run the application with animation, you can generate a discharge event and pass it the value red by typing the following command in the animation command field:

Firecracker[0]->GEN(discharge(red))

The application understands red as a value being passed to the argument color of event discharge because of the notation params->color. The color red is translated to its integer value (0), and the event is entered on the event queue of the main thread as follows:

Firecracker[0]->discharge((int)color = 0)

Finally, the event queue processes the event discharge with the value red passed byparams->. The Firecracker explodes in red and transitions from the ready to the discharged state.

The way the params-> mechanism works is as follows: When you create an event and give it arguments, the product generates an event class (derived from OMEvent) with the arguments as its attributes. Code for events is generated in the package file.

The following sample code shows the event discharge, which has one argument called color. The code was generated in the header file for the Default package:

//-------------------------------------------------------
// Default.h
//-------------------------------------------------------
class discharge;
class Firecracker;
enum Colors {red, green, blue};
class discharge : public OMEvent {
    DECLARE_META_EVENT
////    User explicit entries     ////
public :
        Colors color;
////    User implicit entries     ////
public :
    // Constructors and destructors:
    discharge();
////    Framework entries     ////
public :
    discharge(Colors  p_color);
    // This constructor is need in code instrumentation
    discharge(int  p_color);
};

When the Firecracker event queue is ready to take the event discharge, it calls SETPARAMS(discharge). SETPARAMS is a macro defined in oxf\state.h as follows:

#define SETPARAMS(type) type *params; params=(type*)event

Calling SETPARAMS(discharge) allocates a variable params of type pointer to an event of type discharge. Use params->color in the action part of the transition as a short-hand notation for discharge‑>color.