Monitor template code

All monitors contain monitoring functions. Some of the monitoring functions are hidden from the user, while other monitoring functions are accessible for the user. If a monitoring function is accessible for a user, then the function can also be modified by the user.

A user is never required to write a monitoring function from scratch, because it is always possible to generate template code for the various different kinds of monitoring functions.

Automatic generation of template code

Template code for monitoring functions is automatically generated when the following tools are applied:

• Create breakpoint monitor
• Create write-in-file monitor
• Create data collector monitor
• Create user-defined monitor

If there are no problems with the nodes that are to be monitored, then the template code will be generated as soon as the above tools are applied to appropriate targets, and the template code will be accessible in the monitor index entries. In many cases the template code will be syntactically correct but rather unuseful. For example, the template code for the initialization, observation, and stop functions for write-in-file monitors will be syntactically correct, but they will always return an empty string.

Write-in-file monitor

The template code for monitoring functions will generally have to be modified in order to obtain the desired behavior.

Errors in template code

In some cases, errors will occur when an attempt is made to generate template code. These errors will often be caused by problems with the names of nodes, pages, or the monitor itself. If an error occurs when generating template code, then a red highlight will be added to the monitor, and speech bubbles will indicate the cause of the problem.

Error generating template code

For more information about red highlights and speech bubbles see Graphical Feedback.

See also Errors in monitors.

Understanding template code

Monitor template code is very dependent on the nodes that are associated with the monitor. The template code depends on the names of many different kinds of elements, such pages, places, transitions, color sets, and variables.

Here is a subnet, i.e. a group of nodes, that could be associated with a monitor. The subnet is on the page named Top.

Monitored subnet

Here the template code that would be generated for a predicate function for this particular subnet.

Template code for predicate function

The first line of the template code indicates that the name of the predicate function is pred. The name of the function must not be changed.

The function takes two arguments: bindelem and Top'A_1_mark. The first argument bindelem is a binding element, i.e. a specification of a transition instance together with a binding for the variables of the transition. A description of the legal binding elements for this monitor can be found below.

The second argument of the function (as seen on the second line of the template code) has the name Top'A_1_mark and type INTxDATA ms. This argument is the marking of the first instance of place A on the page Top. The color set of place A is INTxDATA, which means that a marking of the place will always be a multiset of INTxDATA, i.e. INTxDATA ms.

The local function named predBindElem is a function that can be used to examine the binding elements for the monitor. The first line of the declaration of predBindElem, indicates that one of the legal binding elements for the monitor represents the first instance of the transition Send_Packet on page Top, where the variables of the transition are p and n. Similarly, the second line of the declaration of predBindElem indicates that another legal binding element for the monitor represents the first instance of the transition Transmit_Packet also on page Top, where the variables of the transitions are n, p, s and r.

When either one of these two transition instances occurs, then the predBindElem function will return the value true. Note that in the template code, the predBindElem function ignores the values bound to the variables of the two transitions.

The last line of the declaration of predBindElem indicates that when any other binding element occurs, then the function will return the value false. This could happen if, for example, the second instance of transition Send_Packet occurred.

The second to last line of the template code indicates that whenever the predicate function (pred) is called, then the local predBindElem function will be called with the parameter bindelem. In this template code, the marking of the place A is ignored even though it is passed as an argument to the pred function whenever the predicate function is called.

Remember that template code must generally be modified in order to obtain the desired behavior.

Note that different kinds of monitoring functions will take different arguments. For example, an initialization function will never have a binding element as an argument, because initialization functions are invoked before the first step in a transition. The arguments for monitoring functions are also very dependent on the nodes that are associated with the monitor. For more information arguments for monitoring functions, see monitoring functions and data types for monitored subnets.

Changing monitored nodes

As illustrated above, template code is very dependent on the information associated with the nodes that are examined by a particular monitor. If changes are made to a monitored node, then the changes are not propagated to the visible monitoring functions for the node. In many cases, changing a monitored node will result in syntax errors in monitoring functions that previously were correct. For more information about such errors; see errors in monitors.

Here is an example of an error that appears if the name of the transition Send_Packet is changed to Send_A_Packet.

Error after editing a node

The error is caused by the fact that the binding element for transition Send_Packet is no longer legal for this monitor, and this is due to the fact that the monitor examines the transition Send_A_Packet rather than the transition Send_Packet (which, in fact, no longer exists).

Generating template code

Template code is generated automatically when new monitors are created by applying the tools mentioned above. In some cases it is useful to be able to generate new template code for a monitor, e.g.

• After cloning a monitor
• After applying the Remove or Add Surrounding Nodes tools to the monitor
• After changing the names of monitored nodes or pages
• After correcting syntax errors in monitored nodes
• After modifying the variables of a monitored transition
• After modifying the color set of a monitored place

The Generate template code tool can be applied to the name of a monitor to generate new template code.

Generate new template code

Note: when new template code is generated, the existing monitoring functions for the monitor will be replaced by the template code. The effects of applying the Generate template code tool can be reversed by applying the Undo.

Here is the result of generating new template code after changing the name of the transition in the example from Send_Packet to Send_A_Packet

After generating new code

Related pages

Monitors, Monitoring functions. Data types for monitored subnets, Errors in monitors