======================================================================
                  mkvfsm -- VFSM Conversion Module
                      Version 1.1 Apr 16, 1999
             Copyright (c) 1999 by Lucent Technologies
======================================================================


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:

1. 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

2. 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

3. 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.
