miccautil(n) 1.2 miccautil "Support for XUML Model Translation"

Name

miccautil - Supporting Executable Model Translation into C

Table Of Contents

Synopsis

Description

This manpage describes the miccautil package. Miccautil is a Tcl script-based extension that give a set of utility procedures to use with micca generated XUML domains.

COMMANDS

The package exports the following commands which also constitute an ensemble command on the ::miccautil namespace.

::miccautil model create objname savefile
::miccautil model new savefile
objname

The name of the command to be created which represents the model. The new version of the constructor creates a name automatically.

savefile

The name of a file saved from a micca run. This file should be saved in TclRAL native serialization format.

The create and new methods create an instance of a model object. The savefile argument is required and is the name of a file produced by a run of micca with the -save option. The return value of the function is a fully qualified command that may be used with the methods given below.

::miccautil dfs graph ?start?
graph

a graph command as returned from struct::graph, usually obtained by invoking, modelobj stateModelGraph class.

?start?

the name of node where the search is to start. If start is not given, then the search starts at node given by the initialstate attribute of the graph.

The dfs subcommand performs a depth first search (DFS) of graph. graph is a command as returned from struct::graph, usually obtained by invoking the stateModelGraph method with the desired class name. The return value of the command is the empty string.

During the DFS, each node in the graph is annotated with the following additional attributes:

pre

the pre-order number of the node, starting at 1. This is the order in which the node was visited during the DFS.

rpost

the reverse post-order number of the node, starting at 1. This is the order the node would be visited in a reverse post-order traversal. For graphs that do not contain cycles, the rpost numbers form a topological sort of the graph. Graphs which have no back edges (see following) have no cycles.

Each edge in the graph is annotated with one additional attribute:

type

the classification of the graph edge. The type attribute has one of the following values:

tree

the edge is part of a spanning tree for the graph, i.e. the target node is visited for the first time when the edge is traversed.

forw

the edge is a forward directed, i.e. the target node is a decendent of the source node.

back

the edge is a back edge, i.e. the target node is an ancestor of the source node.

cross

the edge is a cross edge. All edges which are not classified as tree, forw, or back are classified as cross edges.

::miccautil spanningTree graph ?start?
graph

a graph command as returned from struct::graph, usually obtained by invoking, modelobj stateModelGraph class.

start

the name of node where the DFS for the tree is to start. If start is not given, then the tree starts at node given by the initialstate attribute of the graph.

The spanningTree subcommand returns a graph command handle as obtained from the struct::graph package in Tcllib. The returned graph contains a spanning tree of the graph argument. The spanning tree returned is the sub-graph of graph where only tree type edges are retained. The caller is responsible for invoking the destroy method on the returned graph command when it is no longer needed. It is not necessary to have run the dfs command previously on graph as that will be done by spanningTree.

::miccautil graphToDot graph ?edgekeys? ?nodekeys?
graph

a graph command as returned from struct::graph, usually obtained by invoking, modelobj stateModelGraph class.

edgekeys

a list of key names which will be included as the label of an edge.

nodekeys

a list of key names which will be included in the label of a node.

The graphToDot subcommand returns a Tcldot command handle which is the dot representation of graph. The edges of the dot drawing are annotated with the values given by the edge attribute keys contained in the edgekeys list. Similarly, the nodes of the dot drawing are annotated with the values given by the node attribute keys contained in the nodekeys list. The command handle can be used in the same way as those returned by the stateModelDot method. Note that invoking graphToDot with the return value of stateModelGraph does not yield the same rendering as the stateModelDot method. The later method insures the rendered state model appears more in line with usual UML notation.

MODEL OBJECT METHODS

The return value of the ::miccautil model create and ::miccautil model new commands is a TclOO command object. The following methods may be applied to the object.

modelobj destroy

The destroy method is used to delete modelobj when it is no longer needed.

modelobj domainName

The domainName method returns the name of the domain represented by modelobj.

modelobj classes

The classes method returns a list of the names of the classes defined in the domain represented by modelobj.

modelobj attributes class
class

The name of a class in the domain represented by modelobj.

The attributes method returns a dictionary of the attributes of class. The keys to the dictionary are the names of the attributes. The values associated to the keys are the data type of the attribute. If class does not exist in the domain, an empty dictionary is returned.

modelobj states class
class

The name of a class or assigner in the domain represented by modelobj.

The states method returns a list of state names for class. If class does not exist in the domain or if class does not have a state model, an empty list is returned. A state name of, @, indicates the pseudo-initial state out from which creation events transition.

modelobj events class
class

The name of a class or assigner in the domain represented by modelobj.

The events method returns a list of event names for class. If class does not exist in the domain or if class does not have a state model or any polymorphic events, an empty list is returned. The returned list includes the event names for any type of event that the class may have. For example, a superclass may not have a state model, but could have polymorphic events and these names would be returned.

modelobj creationevents class
class

The name of a class or assigner in the domain represented by modelobj.

The creationevents method returns a list of event names for class which cause a transition out of the pseudo-initial creation state (represented here as the state named, "@"). If class does not exist in the domain or if class does not have a state model or any creation events, an empty list is returned.

modelobj transitions class
class

The name of a class or assigner in the domain represented by modelobj.

The transitions method returns a relation value that contains the state transitions for class. The heading of the returned relation value is:

|Domain |Model  |State  |Event  |NewState   |Params   |
|string |string |string |string |string     |Relation |

where:

Domain

is the name of the domain.

Model

is the name of the class or assigner.

State

is the name of a state. A State name of, @, indicates the pseudo-initial state out of which creation events transition.

Event

is the name of an event which causes a transition out of State.

NewState

is the name of the state entered by the transition caused when Event is received in State. A NewState name of IG indicates the Event is ignored when it is received in State. A NewState name of "CH" indicates it is logically impossible to receive _Event_ in _State_ (i.e. can't happen) and at run time will cause a panic condition.

Params

is a relation valued attribute giving the parameters of Event (and hence the arguments to NewState). The cardinality of the Params attribute is zero if the event carries no supplemental event data. The Params attribute has the heading:

|Name       |Position   |DataType |
|string     |int        |string   |

where:

Name

is the name of the parameter.

Position

is the order of the parameter carried in Event. Position values start at zero and sequentially increase for each tuple in Params.

DataType

is the "C" type name for the parameter.

The cardinality of the returned relation is states times events where states (including the pseudo-initial state for a creation event, if present in the model) is the number of states in the model and events is the number of events. The cardinality of the returned relation is zero if the class has no state model. Each tuple in the returned relation represents a cell in a conceptual states by events transition matrix with NewState as the cell value.

modelobj startTransitionRecording

The startTransitionRecording method initializes internal data structures in preparation for recording event transitions in the domain represented by modelobj. In particular, any previous event transition counts are reset back to zero. Attempting to start an already running session is silently ignored. The method returns the empty string.

modelobj stopTransitionRecording

The stopTransitionRecording method closes an ongoing event transition recording session. The information gathered during the session is not modified. Attempting to stop an already stopped session is silently ignored. The method returns the empty string.

modelobj recordTransition class currstate event
class

The name of a class or assigner in the domain represented by modelobj.

currstate

The name of the state in class which is the source state in a transition.

event

The name of an event in class which caused a transition from currstate.

The recordTransition method counts the transition which occurred when class was in currstate and received event. It is necessary to start the event transition recording session by invoking the startTransitionRecording method before invoking this method. The method returns a boolean value indicating if the counting occurred, i.e. if currstate and event form a valid transition in class.

modelobj reportTransitions pattern
pattern

A pattern of the format used by the string match command for the names of classes or assigners in the domain represented by modelobj.

The reportTransitions method returns a relation value containing the transition counts for all classes whose names match pattern. The heading of the returned relation value is:

|Domain |Model  |State  |Event  |NewState   |TransCount |
|string |string |string |string |string     |int        |

where:

Domain

is the name of the domain.

Model

is the name of the class or assigner.

State

is the name of a state. A State name of, @, indicates the pseudo-initial state out of which creation events transition.

Event

is the name of an event which causes a transition out of State.

NewState

The name of the state entered by the transition caused when Event is received in State. A NewState name of IG indicates the Event is ignored when it is received in State. A NewState name of CH indicates it is logically impossible to receive Event in State (i.e. can't happen) and at run time will cause a panic condition.

TransCount

The number of times recorded when Model was in a given State and Event was received.

modelobj startMecateTransitionCount reinobj
reinobj

An object command as returned from the rein command of the mecate package. A reinobj represents a bosal generated test harness and methods of the object allow for operations on the test harness.

The startMecateTransitionCount method starts capturing event transitions as they arrive from a bosal generated test harness. This method uses the traceNotify method of the reinobj to install a callback handler for when event traces arrive. Note this method does not turn on event tracing in the test harness. That is done with the reinobj trace on command which must be executed before any events will be received and counted.

modelobj stopMecateTransitionCount reinobj
reinobj

An object command as returned from the rein command of the mecate package. A reinobj represents a bosal generated test harness and methods of the object allow for operations on the test harness.

The stopMecateTransitionCount method stops capturing event transitions as they arrive from a bosal generated test harness. The previous reinobj callback handler is re-instated.

modelobj defaultAttributes

The defaultAttributeValues returns a relation value giving the default values that attributes in the domain represented by modelobj are given if not otherwise specified. The heading of the returned relation is:

|Domain         |Class      |Defaults |
|string         |string     |Relation |

where:

Domain

is the name of the domain.

Class

is the name of a class in *Domain*.

Defaults

is a relation valued attribute containing the attribute names and values for Class.

The heading of the Defaults attribute is:

|Attribute      |Value      |DataType |
|string         |string     |string   |

where:

Attribute

is the name of the attribute of the instance.

Value

is the value of the attribute in the instance.

DataType

is the "C" type name for the attribute.

modelobj initialInstancePopulation

The initialInstancePopulation method returns a relation value containing the initial instance population of the domain represented by modelobj. The heading of the returned relation is:

|Domain         |Class  |Instances |
|string         |string |Relation  |

where:

Domain

is the name of the domain.

Class

is the name of a class in Domain.

Instances

is a relation valued attribute containing the initial instances of Class.

The heading of the Instance attribute is:

|Instance       |ID         |Attributes |
|string         |int        |Relation   |

where:

Instance

is the name given to the inital instance in the micca population.

ID

is the numeric identifier of the instance. This number is the same as the array index of the instance in the storage pool for the class.

Attributes

is a relation valued attribute giving the attribute names and values of the initial instance.

The heading of the Attributes attribute is:

|Attribute  |Value  |
|string     |string |

where:

Attribute

is the name of the attribute of the instance.

Value

is the value of the attribute in the instance.

modelobj stateModelGraph class
class

The name of a class or assigner in the domain represented by modelobj.

The stateModelGraph method returns a graph command from the struct::graph package in Tcllib that represents the state model for class as a graph. It is the responsibility of the caller to insure that the returned graph command is disposed of properly by invoking graph destroy when no longer needed. If class does not not have a state model, the returned graph has no nodes or arcs. The returned graph is annotated by the following key / value attributes:

domain

the name of the domain.

class

the name of the class or assigner.

initialstate

the name of the default initial state.

defaulttrans

the name of the default transition, i.e. IG or CH.

Nodes in the graph represent states in the state model and are named the same as the state name. Nodes are annotated by the following key / value attributes:

activity

the state activity code.

final

a boolean value indicating if the state is a final state.

Arcs in the graph represent the directed transitions from a source state to a target state. Note that IG and CH transitions are not represented by arcs since as target states they do not cause an actual transition. Arcs are annotated by the following key / value attributes:

event

the name of the event causing the transition.

params

a list of event parameter names giving the additional values carried by the event.

modelobj stateModelDot class
class

The name of a class or assigner in the domain represented by modelobj.

The stateModelDot method returns a Tcldot command handle to the state model of class. The command handle can be used to render an image of the state model graph (along with many other uses).

See Also

micca

Keywords

translation