\chapter{Using the YARP companion utility}

\label{sect:using-utility}

This is informal, tutorial-style section meant to give the flavor
of using YARP.

First, please
open two terminal windows; we'll refer to these as A and B.
%
Before doing any communication, is is necessary to start the YARP name
service -- this is a program which keeps track of what YARP resources
are currently available and how to access them.
%
In terminal A, type:

\begin{verbatim}
yarp server
\end{verbatim}

If all goes well, you will see the message ``yarp: name server starting at ...'' -- if not, check any configuration file
mentioned in the output of ``yarp where''.
%
Next, in terminal B, type:
%
\begin{verbatim}
yarp check
\end{verbatim}
%
This will try to communicate with the name server, send a message,
receive a message, and basically make sure that everything is
working well.  Here is what you should see:

\begin{quote}
{\small
\begin{verbatim}
==================================================================
=== Trying to register some ports
yarp: Registered port ... as tcp://5.255.112.225:10011
yarp: Registered port ... as tcp://5.255.112.225:10001
==================================================================
=== Trying to connect some ports
yarp: /tmp/port/2: Receiving input from /tmp/port/1 to /tmp/port/2 using tcp
yarp: Sending output from /tmp/port/1 to /tmp/port/2 using tcp
==================================================================
=== Trying to write some data
==================================================================
=== Trying to read some data
*** Read number 42
==================================================================
=== Trying to close some ports
yarp: Shutting down port /tmp/port/2
yarp: /tmp/port/2: Stopping input from /tmp/port/1 to /tmp/port/2
yarp: stopping output from /tmp/port/1 to /tmp/port/2
yarp: Shutting down port /tmp/port/1
*** YARP seems okay!
\end{verbatim}
}
\end{quote}
%
\noindent
Here is an example of things going wrong:
%
\begin{quote}
{\small
\begin{verbatim}
==================================================================
=== Trying to register some ports
yarp: Couldn't connect to 5.255.112.225
yarp: Name server missing
\end{verbatim}
}
\end{quote}

If networking is broken on your machine, then YARP will have trouble.
If you are running the YARP name server on a machine that does not
have a static IP address or a name registered with DNS, then you
should check the configuration file mentioned by ``yarp where'', and
make sure that the first line of the configuration file is of the form:
\begin{quote}
  current.valid.ip.address 10000
\end{quote}

The number ``10000'' is the default port number that the YARP name
service uses.  This is usually fine; if you have a conflict with this,
then please change it in the configuration file.

If all is well, we can try exercising YARP a little more.

In terminal B, type:
%
\begin{verbatim}
yarp read /port1
\end{verbatim}
%
This will report \ctt{yarp: Registered port /port1 ...} in terminal B and in
terminal A some corresponding message will also appear.
%
Next, in terminal C, type:

\begin{verbatim}
yarp write /port2
\end{verbatim}

If all goes well, this will report \ctt{yarp: Registered port /port2 ...} in
terminal C and in terminal A some corresponding message will also
appear.
%
Now, in terminal D, type:

\begin{verbatim}
yarp connect /port2 /port1
\end{verbatim}

Terminal C will report \ctt{Connecting /port2 to /port1}.  Now if
you type ``hello world'' into terminal C, and hit enter, that text
will appear on terminal B.


If everything is going okay so far, type on terminal E:
%
\begin{verbatim}
yarp read /port3
\end{verbatim}
%
and on terminal D, type:
%
\begin{verbatim}
yarp connect /port2 /port3
\end{verbatim}
%
Now any line you enter in terminal C should appear in both terminal B and E.