 
   RESERVED WORDS AND ERROR MESSAGES FOR THE SOFTWARE LIBRARY
    -----------------------------------------------------
                 
 		          Himanshu A. Sanghavi 
		        Advisor : Dr. Vijay K. Garg 
	    Department of Electrical & Computer Engineering
		  The University of Texas at Austin 
		           Austin, Texas 78712.
			  August 1, 1991

		          Bharath S. Oruganti
		     Advisor : Dr. Ratnesh Kumar 
	           Department of Electrical Engineering 
		        University of Kentucky 
		     Lexington, Kentucky 40506.
			  August 1, 1997


                     		Reserved words:
                   		------------
 
The software attaches a special meaning to three words (character
strings) and hence they should be used carefully.  The three words are
"ALL", "*" and "dead".  Note that the quotes are not part
of the reserved word but are are used as delimiters.  These words
should NOT be used for any other purpose than that described below.
 
Consider a situation where we want to compute the set of states
reachable from a give state.  The library provides two alternatives:
the first is to compute the set of states which can be reached
through ANY of the transitions allowed in the FSM
while the second is to compute the set of states which can be reached
through ONE particular transition.  If the latter is
desired, the name of the transition is given as one of the arguments
to the function.  If the former is desired, the corresponding
argument is the character string "ALL".
 
Each and every transition of a state machine has a name, represented
by a character string.  In order to denote epsilon-transitions,
a special symbol, "*" is used.  Thus any transition labeled
"*" is assumed to be an epsilon-transition.
 
The character string "dead" is used by the software for
denoting some special intermediate states of some computations.
These states are not visible to the user, but the user should not
give this name to any state or transition to ensure that there is
no confusion.
 
Some functions require the software to generate a unique name for a
new state.  The software can generate up to two thousand six hundred
unique names of the form "a00", "a01", ..., "a99", "b00", ..., "z00", ...,
"z99".  Though it is not an absolute requirement, it is recommended that
the user avoid using such names for the states of his/her machine.  This
will make it easy for them to detect the new state(s) generated by the
software during the computation.
 
                      	            Error messages:
                      	            -----------
 
The library checks for a number of possible errors and if one is
detected, the program aborts after printing an error message on
the standard error (stderr) output.  Most of the error messages
clearly indicate the problem.  This section further helps in
identifying the cause of the error.
 
The error message always specifies the name of the function in which
the error occurred.  This helps in pin-pointing the part of the program
in which the error occurred.  In what follows, an explanation of each
error message is given.
 
NULL pointer passed as argument for (struct *):
 
A NULL pointer was passed as an argument to a function where a pointer
to a particular structure was required.  The (struct *)
shown above is used as a generic term.  The actual error message
generated will indicate something like (FSM *) or
(ST_LIST *)+ etc.  Check all the arguments of type
(struct *) given to the function identified in the error
message.
 
 
State whose reach is to be computed does not exist:
 
 
This message is generated by the function fsm_reachability.
You want the function to compute the reach of a state which does not
exist in your machine.  Check the arguments corresponding to the name
of the state whose reach is to be computed.
 
 
Length of string exceeds MAX_LENGTH:
 
The software uses character strings for naming states and transitions.
Although the storage for these names is dynamically allocated, it is
limited to a certain maximum number of characters per string.  This
number is specified by the parameter max_length in the file
fsm.h.  The length of a string in your program has exceeded this
limit.  Either provide smaller names or increase this limit.  If you
choose the latter, remember to recompile the program.
 
Cannot generate unique name for state:
 
Some of the routines of the library (fsm_union, fsm_rename etc.)
require the library to generate a unique name for a new state of the
machine.  The program can generate up to a maximum of 2600 unique
names.  If you have exceeded this limit, your application is probably
too big for this software.

Invalid file pointer:
 
The function requires a file pointer to an input or output file.  You
have passed an inappropriate argument for this.  Check the statements
in your program which open/close files and the call to this particular
function.
 
 
Inappropriate input file format:
 
The input file created by you is not of the correct format or has
some errors.  Check it to see if it is of the format described in
Section 3.  Also check if the number of states and the number of
transitions going out of each state are specified correctly.
 
 
Creating an executable
 
The library consists of four main and one auxiliary file.  The four
main files include a header file (fsm.h) and three source
code files (fsm_general.c, fsm_lower.c, fsm_operators.c)
The fifth file is a makefile.
 
A library archive of compiled modules of the source code files is
created using the makefile.  This archive file can then be compiled
with the users program to make an executable.  The archive file is
named fsm.a and is essentially an archive of the three
*.o files.  In order to make the executable, the user has to execute a
command such as
 
      gcc -ansi -o fsm  one.c two.c  ...  fsm.a
 
Here one.c, two.c ... refer to the source code of the
users program.  The above command will create an executable file
named fsm.
 
The library has been written in the C programming language.  Some
C compilers will compile programs with function calls having incorrect
number or type of arguments.  This invariably leads to a core
dump.  In order to avoid this, the user is advised to compile his/her
program using a ANSI C compiler which forces type-checking.  The GNU C
compiler, gcc along with the -ansi option is a good
choice because it forces type-checking but does not insist on ANSI C
syntax.
 
Depending on whether the users compiler accepts function prototypes or
not, the header file fsm.h may have to be changed.  The comments
in that file explain what has to be done.

Any comments, suggestions etc. are welcome.  Please direct them to:

Dr. Vijay K. Garg
Department of Electrical & Computer Engineering
The University of Texas at Austin
Austin, TX 78712.
 
e-mail : vijay@pine.ece.utexas.edu
 
Dr. Ratnesh Kumar
Department of Electrical Engineering
University of Kentucky
Lexington, KY 40506.
 
e-mail : kumar@engr.uky.edu
