Initial revision

doc/programmer/inter.tex

@@ -0,0 +1,69 @@
+\subsection{The SICS Interpreter}
+ The SicsInterpreter implements a Tcl-look alike command list with each
+ object having a similar wrapper function to those used in Tcl. But
+ augmented with a pointer to a Connection structure in order to enable
+ authorisation checking and providing the I/O context. The object wrapper
+ function has a prototype looking like this:
+
+
+{\bf  int ObjectWrapper(SConnection *pCon, SicsInterp *pInter,  void *pData,
+int argc, char *argv); }
+
+
+ pCon is the connection responsible for this call and holds necessary
+ information for authorisation checking. pInter is the Sics interpreter.
+ pData is a pointer to an object specific datastructure (the struct holding
+ the motor data for instance). Argc and argv hold the arguments as in a C
+ main program. The object wrapper is meant to evaluate the arguments, do the
+ right thing to the object with them and than pass results back. There are
+ two ways to do that. The prefered one is to copy results or error messages
+ into the interpreters result space and associate an output code with the
+ result space. After returning the interpreter will than copy these results
+ to the client. However, a scan routine might want to print status
+ information to the client during a lengthy operation. In this case the
+ object can write directly to the connnection usinfg the provided connection
+ pointer. The object wrapper function returns true or false depending on the
+ success of the operation.
+
+
+ The command list is a doubly linked list holding for each command a record
+containing: the commands name, a pointer to the objects object function, a
+pointer to the objects data structure (passed as pData) on invocations and a
+pointer to a function which is capable to delete the objects data structure.
+This function will be called when the object/command is removed. In the end
+the SicsInterpreter implements the following datastrucures an
+interfaces:\begin{verbatim} typedef struct __Clist {
+                          char       *pName;
+                          ObjectFunc OFunc;
+                          KillFunc   KFunc;
+                          void *pData;
+                          struct __Clist *pNext;
+                          struct __Clist *pPrevious;
+                        }  CommandList;
+\end{verbatim}
+ The structure held in a doubly linked list for each command.\begin{verbatim}
+typedef struct __SINTER
+             {
+               CommandList *pCList;
+               char *pErrors;
+               int iSpace;
+               OutCode eOut;
+             }SicsInterp;
+\end{verbatim}
+ The interpreter data structure. Access only through the interface  functions given below:\begin{itemize}
+\item {\bf SicsInterp *InitInterp(void) } creates a new interpreter. Returns a pointer on success, NULL on failure.
+\item {\bf int AddCommand(SicsInterp *pInterp, char *pName,  ObjectFunc pFunc, KillFunc pKFunc, void *pData); } adds a new command  to the commandlist of the specified interpreter. Returns True or false depending on success.
+\item {\bf int RemoveCommand(SicsInterp *pInterp, char *pName) } finds  command name and removes it from the list. Returns True on success (command found) and False if it fails.
+\item {\bf int InterpExecute(SicsInterp *self,pSConnection pCon, char *pCommand) } executes pcommand in the SICS interpreter. Returns -1 if the command did not exist. If ist exists True or False is returned depending on the success of the command.
+\item {\bf int InterpWriteResult(SicsInterp *self,char *text) } used within object wrapper functions to append result text to the interpreter. Allocating sufficient memory is taken care of by this function.
+\item {\bf void InterpSetOutCode(SicsInterp *self, OutCode eCode) } does what it says.
+\item {\bf OutCode InterpGetOutCode(SicsInterp *self) } return the  current output code for the interpreters result.
+\item {\bf CommandList *FindCommand(SicsInterp *pInterp, char *name) } return a pointer to a commandlist structure if the object specified  by name exists, NULL else. Used in the definition of interpreter and macro functionality.
+\item  {\bf const char *InterpGetResult(SicsInterp *self) } returns a  pointer to the interpreter result space. This space is managed by the  interpreter, never ever delete it in client code.
+\item {\bf void DeleteInterp(SicsInterp *self) } removes the interpreter, his command list etc. Frees all allocated memory for  this interpreter.
+\item {\bf WriteSicsStatus(SicsInterp *pSics, char *file)} opens the file
+for writing and writes the current status of SICS objects int the file. In
+order to do so, the SaveStatus function of each object registered in the
+interpreter is called.
+\end{itemize}
+