\documentclass{article}\addtolength{\textwidth}{18pt}\begin{document}\section{SMif --- The SIMATH interface functions}SMif is the SIMATH interface program. SMif uses a simple scriptlanguage to extract data from arbitrary text files or from the outputof arbitrary programs. In some sense it is similar to the standardUnix utilities awk or sed although some of the capabilities of theselanguages have not been implemented and the design of SMif focuses onthe extraction of numerical data, and not on general text pieces.SMif uses the \emph{tcl} library and numerical operations and internalrepresentations depend on \emph{tcl}.\subsection{SMif functions}The following funtions resp.\ macros can be used to obtain data fromthe underlying SMif interpreter and to administrate the results of theinterpreter. All these functions can be used in any C program, inparticular in SIMATH programs. Since all of the \emph{tcl}functionality resides in the interpreter, programs using SMif do nothave to be linked against the \emph{tcl} library.\begin{verbatim}  void SMifRes_Init (SMifRes* smifres)  void SMifRes_FromFile (SMifRes smifres, char* textfname,                          char* scriptname)  void SMifRes_FromProg (SMifRes smifres, char* progname,                         char* paralist, char* scriptname)  single SMifRes_Count (SMifRes smifres)  single SMifRes_Error (SMifRes smifres)  char* SMifRes_ErrMsg (SMifRes smifres)  single SMifRes_Type (SMifRes smifres, single nr)  char* SMifRes_Get (SMifRes smifres, single nr)  void SMifRes_SetCsh (SMifRes smifres, char* cshname)  void SMifRes_Free (SMifRes *smifres)\end{verbatim}Here, \texttt{SMifRes} is a data type used to store the resultsreturned by the SMif interpreter.Every variable of type \texttt{SMifRes} must be initialized by a callto \texttt{SMifRes\_Init()} before it can be used in any of the SMiffunctions.  \texttt{SMifRes\_Free()} frees the storage area allocatedby \texttt{SMifRes\_Init()} for an object of type \texttt{SMifRes}.\texttt{SMifRes\_FromFile()} requires as parameters the name of a textfile \texttt{textfname} and the name of a script file\texttt{scriptname}.  The interpreter SMif operates on the text file\emph{textfname} according to the script file \texttt{scriptname}. Theresults are stored in the variable \texttt{smifres}.\texttt{SMifRes\_FromProg()} expects as parameters the name of anexternal program \texttt{progname}, the argument list\texttt{paralist} for this program, and the name \texttt{scriptname}of an SMif script. The external program \texttt{progname} is executedfor the arguments in \texttt{paralist} and the SMif interpreteroperates on its output according to the scriptfile\texttt{scriptname}. The results are stored in the variable\texttt{smifres}.SMif creates some temporary \texttt{csh} scripts. By default, thesefiles are processed by \texttt{/bin/csh}. This can be changed by acall to the \texttt{SMifRes\_SetCsh()} function.The rest of the functions resp.\ marcos are used to read the resultsof the SMif interpreter in a convenient manner.\texttt{SMifRes\_Count()} returns the number of entries in a\texttt{SMifRes} object. A valid entry can be of one of the types\texttt{SM\_single}, \texttt{SM\_int}, \texttt{SM\_list}, or\texttt{SM\_pol}.  \texttt{SMifRes\_Type()} returns the type of entry\texttt{nr}. If this entry does not exist, \texttt{SM\_unknown} isreturned.  \texttt{SMifRes\_Get()} accesses the value of the entry\texttt{nr}, i.\ e.\ a single precision number, an integer ofarbitrary size, a SIMATH list, or a polynomial in the appropriateexternal representation of these types.  (I.\ e.\ the\texttt{SMifRes\_Get()} returns a string which can be easily convertedto the appropriate SIMATH data type by certain SIMATH functions.)If SMif encounters an error, the macro \texttt{SMifRes\_Error()}returns \texttt{SMifRes\_error}. (Otherwise \texttt{SMifRes\_ok} isreturned.)  In case of an error \texttt{SMifRes\_ErrMsg()} returns adetailed description of the error.The functions, macros, and constants described above are declaredresp.\ defined in the header file \texttt{\_SMfiRes.h}.\vspace*{12pt} \textbf{Example.} Let \texttt{anyprogram} be anexternal program (i.\ e.\ a program which could as well be executed bya shell) which returns the output\begin{verbatim}  *** anyprogram  %1 = (x + y^3)(x^3 + y)\end{verbatim}for the arguments (in the string) \texttt{arg1 arg2}. Suppose that thescript file \texttt{script} looks as follows:\begin{verbatim}  SKIP UNTIL SEEN {[CHAR] =}  GET POL\end{verbatim}We examine the following code fragment:\begin{verbatim}#include <_simath.h>#include <_SMifRes.h>int main() {  SMifRes smifres;  char *tmpstr = NULL;  .....  /* bind(), init() for SIMATH data types */  .....  /* Initialize a SMifRes variable */  SMifRes_Init(&smifres);      SMifRes_FromProg(smifres, "anyprogram", "arg1 arg2", "script");    if(SMifRes_Error(smifres) != SMif_ok) {    /* Error processing */    printf("SMifRes_Error: %s\n", SMifRes_ErrMsg(smifres));    exit(1);  }  if(SMifRes_Count(smifres) != 1 ||      SMifRes_Type(smifres, 1) != SM_pol) {    /* Something went wrong */    printf(.....);    exit(1);  }  tmpstr = SMifRes_Get(smifres, 1);  printf("example: %s\n", tmpstr);  .....    SMifRes_Free (&smifres);   .....}\end{verbatim}A part of the output of the program:\begin{verbatim}  example: 1*x^4*y^0 + 1*x^1*y^1 + 1*x^3*y^3 + 1*x^0*y^4\end{verbatim}\subsection{The SMif script language}\subsubsection{Characters and words.}SMif commands operate on a given text file. A pointer always points ata well defined position in the text file. The text file is splitted inappropriate tokens by default symbols or user defined symbols. Thefollowing notation is used to describe characters and words.\begin{verbatim}  {[CHAR] ch1 ch2 ... [WORD] word1 word2 ...}\end{verbatim}Strings of this form are called \emph{controldefinestrings}. Thefollowing command tells the interpreter to ignore all of the givencharacters and strings within a text file to be processed by SMif.\texttt{IGNORE} \emph{controldefinestring}\subsubsection{\texttt{GET} commands}The four \texttt{GET} comands \texttt{GET SINGLE}, \texttt{GET INT},\texttt{GET LIST}, and \texttt{GET POL} generate the output of theinterpreter.  The \texttt{GET SINGLE}, \texttt{GET INT}, and\texttt{GET LIST} command search for integer expressions beginningwith the current pointer position. A \texttt{GET POL} command collectsall the items which are not to be ignored. There are certain commandswhich change the default behaviour of \texttt{GET} commands.\texttt{IGNORE NEWLINE AFTER} \emph{controldefinestring}\texttt{SETITEM SIZE} \emph{n} \texttt{PATTERN} $\{$\emph{patterndefinestring }$\}$\texttt{STOPGET IF SEE} \emph{controldefinestring}The \texttt{IGNORE NEWLINE AFTER} command tells SMif which charactersor words at the end of a line have to be treated as a continuationmark.  A continuation mark indicates that the line is to be treated ascontinued in the next line (without line break). The \texttt{GET  SINGLE}, \texttt{GET INT}, and \texttt{GET LIST} commands puttogether two integer expressions before and after a continuation mark.\texttt{GET POL} puts together two arbitrary words before and after acontinuation mark.\texttt{SETITEM SIZE} is valid for \texttt{GET SINGLE}, \texttt{GET  INT}, and \texttt{GET LIST} commands only. It is ignored for\texttt{GET POL} commands. \texttt{SETITEM SIZE} defines how manyinteger expressions will be treated together and what will happen withthese expressions.  We will see an example for this later. Theexpressions are identified by the symbols \texttt{\$1}, \texttt{\$2},...  \emph{patterndefinestring} is a mathematical formula over thesesymbols.  For example,\texttt{SETITEM SIZE 3 PATTERN \{\$1\}} \newline defines that only thefirst expression of three expressions will be returned.  For\texttt{GET INT}, this is the only valid type of\emph{patterndefinestring}. The \texttt{GET SINGLE} and \texttt{GET  LIST} commands are based on C long integers and it is possible toapply any mathematical operation defined in the \emph{tcl} language tothe symbols \texttt{\$1}, \texttt{\$2}, ... In this case, validexpressions are for example\texttt{SETITEM SIZE 2 PATTERN \{int (cos(\$1)*tan(\$2))\}} \newlineor\texttt{SETITEM SIZE 2 PATTERN \{\$1>\$2?\$1:\$2\}}.  \newline Acomplete list of available operators can be found in the \texttt{expr}man page of the \emph{tcl} library.The \texttt{STOPGET} command tells SMif to stop moving the filepointer as soon as a given character or the beginning of a given wordare read. This is one of the three conditions for a \texttt{GET}command to terminate.  Furthermore, a \texttt{GET} command willterminate if a \texttt{REPEAT} loop or a \texttt{GET} commandenclosing this \texttt{GET} command terminate, and of course, a\texttt{GET} command will terminate at the end of the input file.\subsubsection{The scope of control commands}A \texttt{GET} command can contain a sub script. In particular, a\texttt{GET LIST} command can contain another \texttt{GET LIST}command.  In this way, SMif can deal with sub lists of lists.  Thevalidity domain of a definition (made by a \emph{controldefinestring})is determined by the following rules.1. The global level, i.\ e.\ the part of the SMif script not containedin any \texttt{GET} command has level number 0.  Every \texttt{GET}command increments the level number by 1 and all the definitions oflevel number $n - 1$ are valid in level number $n$.2. A definition by \texttt{IGNORE}, \texttt{IGNORE NEWLINE}, and\texttt{STOPGET} remains valid until it is canceled by one of thefollowing \texttt{NOPOWER} commands on the same level:\texttt{NOPOWER IGNORE} \emph{controldefinestring}\texttt{NOPOWER IGNORE NEWLINE AFTER} \emph{controldefinestring}\texttt{NOPOWER STOPGET} \emph{controldefinestring}3. A valid \texttt{SETITEM} definition is canceled by a new\texttt{SETITEM} command on the same level or by the command\texttt{NOPOWER SETITEM} which restores the default behaviour.  Thedefault definition is \texttt{SIZE 1 PATTERN \{\$1\}}.\textbf{Example.}\begin{verbatim}  # comment: example  IGNORE {[WORD 123 234]}  GET SINGLE {}  GET SINGLE {