UBET->VFSM CONVERSION MODULE (mkvfsm)


[UBET Installation & Setup][MSE User Guide][UCE User Guide]


CONTENTS


Synopsis


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.


Preparation


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.
 


Note for timer


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.
 


Note for pause


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.
 


Usage


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)
 


Diagnostics


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
 


Output files


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.
 


Dictionary convention


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

Limitation


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.
 


pos_lucent.gif (1187 bytes)