[UBET
Installation & Setup][MSE User
Guide][UCE User
Guide]
Mkvfsm converts UBET ucg graphs (use case graph) into a VFSM format - the specification language of the VFSM model (http://ihgpweb.ih.lucent.com/~vfsm/).
The format generated consists of one VFSM control spec file and three VFSM dictionary files (input, output, and state) per participating process.
The conversion requires the presence of basic msc's linked to the nodes in the ucg graph. The events inside these MSC fragments are the events that are translated into the VFSM actions - preserving the control flow structure of the ucg graph.
Before using mkvfsm to convert ucg graphs to VFSM model, following requirements have to be met.
1. A main ucg graph with optional underlying ucg sub-graphs and msc charts are required.
2. ucg graph should be created using UBET tool uce. One Start node and one Stop node per ucg graph are required. An ucg graph should be saved to a file with extension ".ucg" (or "poga" previously).
3. An msc chart should be created using UBET tool mse. Each msc chart is actually a fragment that describes the behavior of a use case. All msc fragments should be well defined, and any overlapping and conflict should be carefully avoided. An msc chart should be saved to a file with extension ".itu".
4. Each node in main ucg graph and ucg sub-graphs (except Start node and Stop node) can have a reference to another ucg sub-graphs (optional). However, a cyclic reference is not allowed, and it will cause a fatal error if existing cyclic reference.
5. Each node in main ucg graph and ucg sub-graphs (except Start node and Stop node) can have a reference to an msc chart (optional). However, if no msc chart defined in all nodes, this system is invalid, and it will be reported as an error and no vfsm model will be generated.
6. All working files including ucg and msc files should be placed in a same directory
in order to be referenced properly.
mkvfsm supports timers. To define timer in an msc chart, either one of following notations or their combination can be used:
1. ITU timer notation. ITU timer Set, Reset, and Timeout can be used to represent timer start, stop, and expire respectively. ITU timer notation does not support multiple timers in a single process, and it does not allow a timer to span over different msc charts either. Due to this limitation, ITU timer notation is not recommended, and Text box notation is preferred instead.
2. Text box notation. This is an alternative way to define timers. To use text box for
timer, a couple of pre-defined keywords have to be used. Presently, the keywords are
"TSTART", "TSTOP", and "TEXPIRE" respectively. The syntax
for timer is "KEYWORD(id)". Where "KEYWORD" represents one of
pre-defined keywords above, and "id" specifies a name for the timer.
Please note that the parentheses are required.
mkvfsm supports pause mechanism. The reason to introduce the pause is to represent a wait condition.
The notation for pause is similar to timers. To define a pause, a text box has to be
used, and a pre-defined keyword "PAUSE" should be the only content in the
text box.
Type at the UNIX or MS-DOS command line:
mkvfsm [-o outpath] [-s sysname] infile
Where:
-h Display this help page.
-o outpath Directory for storing all output files. If no
'-o' specified,
by default, output directory
is named after
infile base name plus suffix
'.vfsm', or
sysname plus suffix '.vfsm' if '-s'
specified.
-s sysname System name used to name system definition file
('.dv'), and also
name output directory if no
'-o' specified.
infile Main ucg file name with suffix '.ucg' or '.poga'.
It is not necessary to run mkvfsm at the directory of infile. In other words, there is no need to set current directory before running mkvfsm as long as outpath and infile are set correctly.
Following is an example:
mkvfsm ../callproc/callproc.ucg (UNIX)
or
mkvfsm ..\callproc\callproc.ucg (MS-DOS)
Errors and warnings are printed on stderr and warn about potentially problematic
constructs. For instance, cases of event divergence (where more than one outgoing
messages exist according to higher-level control flow from the ucg), lead to potentially
conflicting decisions. mkvfsm can analyze the consequences of such
trouble spots in a design.
mkvfsm terminates with a return code. In the case of success, a value of zero will be returned. Otherwise a value of non-zero will be returned. Following is the return code definition:
SUCCESS 0
ERRBADPARAM 100
ERRFILEMISSING 101
ERRFILEOPEN 102
ERRASSERTION 103
ERRBADUCG 104
ERRCYCLICREF 105
ERREXPIRATION 106
ERRUCGTOOBIG 107
ERRFILEACCESS 108
All output VFSM control spec files and dictionary files can be found at directory outpath upon '-o' is specified, or a default directory (see section Usage). However, mkvfsm may not generate these files in a variety of error situations.
VFSM files generated by mkvfsm use following naming convention:
The name of each process will be used as the VFSM file name. Each VFSM consists of four files, and the file extensions are defined as follows:
.vs Control spec
.di Input dictionary
.do Output dictionary
.ds State dictionary
In addition, a system definition file for whole system will also be generated by mkvfsm. The naming convention for system definition file is as follows:
It takes infile's base name, or sysname if '-s' specified, as its base name (see
section Usage), and uses '.dv' as its extension.
mkvfsm uses following dictionary convention for VFSM model:
| Input dictionary |
|
| IGT_UNX_SRC | An initial message |
| IGET_message_FM_source | An input "message" from vfsm "source" |
| IGT_id | An input message caused by timer timeout or text box with keyword "TEXPIRE" |
| IPAUSE | An input message caused by keyword "PAUSE |
| ISD_message_TO_dest | An input message derived from a corresponding output message ISD_message_TO_dest, which is caused in the case of making choices |
| ISD_NOTHING | An input message caused in the case of making choices |
| Output dictionary |
|
| OSD_message_TO_dest | An output "message" to vfsm "dest" |
| OST_id | An output message caused by timer set or text box with keyword "TSTART" |
| OSP_id | An output message caused by timer reset or text box with keyword "TSTOP" |
| OCHOOSE | An output message caused in the case of making choices |
| OSD_NOTHING | An output message caused in the case of making choices |
| State dictionary | |
| SSTART | An initial state |
| SSD_message_TO_dest | An output "message" has been set to vfsm "dest" |
| SW4_message_FM_source | Waiting for input "message" from "source" |
| SGT_message_FM_source | An input "message" from "source" has been received |
| SST_id | A timer has started by timer set or test box with keyword "TSTART" |
| SSP_id | A timer has stopped by timer reset or text box with keyword "TSTOP" |
| SGT_id | An timer has expired by timer timeout or text box with keyword "TEXPIRE" |
| SPAUSE | A waiting state |
| SCHOOSE | A choice needs to make when existing multiple choices (incoming and outgoing messages) |
| SSD_NOTHING | A choice needs to make when existing multiple choices (incoming messages) |
| SEND | A last state |
Currently, following limitations exist in mkvfsm:
1. Co-region in msc chart is not supported in this version, all co-region definitions
are simply ignored by mkvfsm.
2. All work files including ucg and msc files should be placed in a same directory because
path reference is not supported.