Initial revision

doc/programmer/buffer.tex

@@ -0,0 +1,81 @@
+\subsection{The LNS R\"unbuffer}
+R\"unbuffers are a special LNS feature for handling instruments. Essentially
+a R\"unbuffer is a list of commands which can  be executed as a block. On
+line editing of such a R\"unbuffer is supported as well. R\"unbuffers can
+also be saved to or read from disk files. R\"unbuffers are related to the
+batch file processing facility FileEval. However, there are subtle
+differences. The first is I/O: When evaluating a batch file with FileEval
+all messages except errors and warnings are suppressed. This is a nice
+feature if the file evaluated contains a macro, where a user might be
+confused when confronted with all internal messages. With R\"unbuffers all
+output is written to the user. R\"unbuffers support only SICS commands, with
+FileEval Tcl commands can be given as well.
+
+
+It turned out that the  R\"unbuffer system together with the R\"unlist
+facility documented in the next section is rarely
+used. Experimentators prefer the batch file facility ``fileeval''
+instead. Consequently, this may be retracted and cleaned out in some
+stage.     
+
+A R\"unbuffer is characterized by a an own data structure:
+\begin{verbatim} 
+  typedef struct {
+                   pObjectDescriptor pDes; /* needed */
+                   char *name;             /* BufferName */
+                   int iLineList;          /* Handle to the Line List */
+                   } RuenBuffer, *pRuenBuffer;
+\end{verbatim}
+The fields:
+\begin{description}
+\item[pDes] A pointer to the usual SICS object descriptor.
+\item[name] The name of the R\"unbuffer.
+\item[iLineList] The handle of the lldlist holding the lines of the
+R\"unbuffer.
+\end{description}
+
+Interaction with R\"unbuffers happesn through the functions listed below.
+All functions return 0 on failure or 1 on success, if not stated otherwise.
+Most functions take as first parameter a pointer to the R\"unbuffer to act
+upon.
+\begin{description}
+\item[pRuenBuffer CreateRuenBuffer(char *name)] creates a R\"unbuffer.
+Returns the pointer to the new r\"unbuffer on success, or NULL on failure.
+\item[void DeleteRuenBuffer(void *pSelf)] Deletes a R\"unbuffer.
+\item[pRuenBuffer CopyRuenBuffer(pRuenBuffer pOld, char *NewName)] copies a
+R\"unbuffer including all data lines. Returns NULL on failure, a pointer to
+a new R\"unbuffer structure otherwise.
+\item[int BufferAppendLine(pRuenBuffer self, char *line)] appends line to
+r\"unbuffer self.
+\item[int BufferDel(pRuenBuffer self, int iLine)] deletes line iLine from
+r\"unbuffer self.
+\item[int BufferInsertAfter(pRuenBuffer self, int iLine, char *line)]
+    inserts line line AFTER line number iLine in the RuenBuffer self.
+\item[int BufferPrint(pRuenBuffer self, SConnection *pCon)]
+   lists the contents of the RuenBuffer on the Connection pCon.
+\item[int BufferReplace(pRuenBuffer self, char *pattern, char *pReplace)]
+   replaces all occurences of the string pattern in the whole RuenBuffer
+   by the replacement string pReplace.
+\item[int BufferRun(pRuenBuffer self, SConnection *pCon, SicsInterp *pSics)]
+    executes the lines of the Ruenbuffer one by one. 
+    Returns 1 on success, 0 on error.
+\item[int BufferSave(pRuenBuffer self, char *file)]
+   writes the contents of Ruenbuffer self to the file specified by
+   file. 
+    Returns 1 on success, 0 on error.
+\item[int BufferLoad(pRuenBuffer self, char *file)]
+   reads the contents of file into the RuenBuffer self. 
+    Returns 1 on success, 0 on error.
+\item[int InitBufferSys(SConnection *pCon, SicsInterp *pSics, void *pData,\\
+                    int argc, char *argv[])] The factory function for the
+R\"unbuffer system. Initialises the Buf command and the ruli command. 
+\item[int BufferCommand(SConnection *pCon, SicsInterp *pSics, void *pData,\\
+                    int argc, char *argv[])] The object wrapper function
+which implements the Buf command.
+\item[int BufferAction(SConnection *pCon, SicsInterp *pSics, void *pData,\\
+                    int argc, char *argv[])] The object wrapper function for
+the R\"unbuffer itself.
+\item[pRuenBuffer FindRuenBuffer(SicsInterp *pSics, char *name)] finds
+r\"unbuffer name in the interpreter pSics. Returns a pointer to the
+r\"unbuffers data structure if it exists, NULL otherwise. 
+\end{description}