% (C) Copyright International Business Machines Corporation 23 January 
% 1990.  All Rights Reserved. 
%  
% See the file USERAGREEMENT distributed with this software for full 
% terms and conditions of use. 
% File: tutorial.tex
% SCCS Info: @(#)tutorial.tex	1.8 3/19/91

\section{Working through the Tutorial}
\label{tutorial}

We recommend that you run the tutorial code.  Source files for the tutorial
code examples are stored in the directory {\tt \~{}hermes/tutorial\_examples}.
\cb{08a}In our book, {\em Hermes: A Language for Distributed Computing},
many of the tutorial examples are not complete Hermes modules---some
include only code fragments and others only declarations or type definitions.  
All the examples in {\tt \~{}hermes/tutorial\_examples}
have been merged into complete source files that compile and execute.
\endcb{08a}

Most of the tutorial example programs receive their initialization message on a
{\tt standardIn} input port (except {\tt boundedbuffer} whose initialization
port is a member of the type {\tt bbIn}).  Like all languages, this
implementation of Hermes defines a {\em main} program, which is the kind of
program that the interpreter can load and run directly.  A Hermes main program
has an init port of type {\tt mainQ} (see Section~\ref{mainIntf} for more
details) which passes it capabilities to many Unix and Hermes facilities.


To run the tutorial examples use a small main program called {\tt stdIntf}
which will load a tutorial program that uses the {\tt StandardIn} init port and
connect it up.  (To run the {\tt boundedbuffer} program use the main program
{\tt bbintf}.)  {\tt stdIntf} also takes the rest of the character string input
and passes it to the tutorial program.  For example, to run the {\tt
helloworld} program, enter {\tt hermes stdintf helloworld}.  To run the {\tt
echo} program, enter {\tt hermes stdintf echo}.

{\tt Compound} is especially interesting because it loads another program and
connects that program's output to {\tt filter}.  Any program that has a
{\tt standardIn} initialization port will work, including {\tt
compound} itself.
You might try running {\tt hermes stdintf compound helloworld/},
{\tt hermes stdintf compound echo/},
{\tt hermes stdintf compound compound/echo/}, etc.  You
might also write another {\tt standardIn} program and make it a client of {\tt
compound}.

The {\tt boundedbuffer} program is a server program---it has an infinite loop
in which it receives and services calls.  The main program {\tt bbintf} is an
interactive front-end that lets you be the client of {\tt boundedbuffer}.
Enter {\tt hermes bbintf boundedbuffer}.  {\tt bbintf} responds to three
commands
\begin{description}
\item [{\tt P line}] puts {\tt line} into the bounded buffer
\item [{\tt G}] gets the first entry from the bounded buffer
\item [{\tt Q}] quits the bounded buffer program
\end{description}
{\tt boundedbuffer} also accepts an optional argument, the size of the
buffer.  Try {\tt hermes bbintf boundedbuffer 8}.

You may notice that {\tt hermes} terminates when you try to put into a full
boundedbuffer or get from an empty boundedbuffer.  It terminates because there
are no processes ready to run, so the interpreter has nothing left to do.  When
you type at the {\tt bbintf} prompt, {\tt bbintf} is doing a {\tt getline} and
is the only runnable process.  It then makes a get or put call to {\tt
boundedbuffer} and blocks, waiting for the return.  If {\tt boundedbuffer}
cannot handle the call, because doing so would exceed its buffer capacity, then
it cannot run either.  Thus there are no runnable processes, and the
interpreter terminates.  To design a more robust boundedbuffer you might want
to provide exception returns on the put and get calls, so an unsuccessful call
terminates.

The window system is the last and most elaborate tutorial example.  To run it
enter {\tt hermes stdintf wmsystem}.  Its built-in front-end understands the
following commands:
\begin{itemize}
\item {\tt line} - dispatch line to window currently in focus
\item {\tt !!line} - dispatch {\tt !line} to the window currently in focus.  
This is how you send data which begins with an escape character.
\item {\tt !C windowname application} - create a window {\tt windowname} 
running {\tt application}
\item {\tt !F windowname} - change focus to {\tt windowname}
\item {\tt !K windowname} - kill {\tt windowname}
\item {\tt !Q} - quit window system
\end{itemize}

This is obviously not a realistic window manager, but its structure can be used
as a guide to building something more practical.  You should try it with
multiple windows, all three of the tutorial's standard interface programs, and
tickle its error conditions.  Why doesn't the front-end prompt always come out
before you start to type in the next command?

Suggested exercises: Write a {\tt standardIn} program that uses the tokenizer
to count characters words and lines like the Unix wc command.
Run this program with {\tt compound}.  Write a more robust {\tt boundedbuffer}.
This requires scrapping
the GetLine and PutLine interfaces and defining GetBuffer and PutBuffer
interfaces for the buffer.  The drawback of this change is that this
{\tt boundedbuffer} will no longer compose with other processes that
interface with PutLine and GetLine.
