\section{Client Tools}
When writing the first {\it Discuss} client program, we came across a
number of problems that had to be solved.  Instead of solving
these problems in a limited way, we attempted to build general tools
that could find use in different situations.  These tools have found
their way into other {\it Discuss} clients, and other software projects.

This section describes the tools that were built to support {\it
Discuss}.  These tools are the {\it Discuss} library, which contains
general routines that can be used by any {\it Discuss} client, the
subsystem ({\it ss}) library, which supports command-line interfaces,
and the Common Error-handling ({\it com\_err}) package, which allows
multiple packages to report errors in a coherent way.

\subsection{The {\it Discuss} library}

When we wrote our first {\it Discuss} client program, we were
aware that there would be those who would not like the style of
interface that we chose, and who would want some other interface to
use.  We wanted to be able to build clients with different interfaces 
without resorting to ``sharing via text editor.''

To meet this goal, we designed the {\it dsc} library. 
It performs all
interaction with {\it Discuss} servers (via RPC calls) as well parsing and
updating a user's {\tt .meetings} file.
Thus the user interface needs only know how to call these
routines and need not know any of the implementation details.

%% this paragraph is XpXoXoXrX lousy
%Given a set of include files and the library (and of course
%documentation on the library), a programmer building a new {\it
%Discuss} client program need not have any more information about the
%mechanisms of {\it Discuss} at hand in order to write his software.

Using this library, a prototype X-based client {\tt xdsc} has been
written. Although we found one or two very
minor problems in the actual implementation, we believe the modularity
imposed by the {\it dsc} library has greatly reduced the effort
required to develop new user interfaces.

\subsection{A Simple User Interface}

Another package we wrote for this project was the
original shell-like user interface.  While the routines implementing
the specific commands are very particular to {\it Discuss}, the driver
that prompts for them is not.  The package we use, known as {\it ss}, provides the input
and dispatch routines for not only our own original {\it Discuss} client
program, but also a control program used by {\it Zephyr}, one of the
{\it Kerberos} administrative utilities, and various other programs
which need a simple interactive shell-like interface.  This
section gives a brief overview of the use of this package.

This subsystem package consists of a command table translator and a
run-time library.  The command table translator converts a descriptive
list of commands (including several command names, a short one-line
description, and a subroutine name for each) into a C source file
which is compiled and linked into the the application, along with the
run-time library.  The {\it ss} library consists primarily of a dispatch
routine which prompts for input, reads and parses a command line, and
calls one of the subroutines listed in the command table.  A user of
this system calls a routine to create a subsystem object, and then
invokes a dispatch routine with that subsystem object as a parameter.
The routines are called with
``argc, argv'' arguments similar to the C function {\tt main},
along with a third parameter indicating which subsystem
object the command was invoked from.

This subsystem package includes as built-in commands a ``?'' command,
which lists the commands available (and their descriptions), and some
simple commands like ``quit''.  It manages input handling, primitive
shell-like argument parsing (breaking up a string into an array of
words), and a help utility that makes use of programmer-supplied
directories of help files (to be viewed with ``more'').

Although this package lacks such features as intelligent argument
handling and command and argument completion, it is extensible
and still under development.  Even without these features, we have found this
subsystem management package to be useful for a number of
applications.

% parallels and lack thereof


\subsection{Error handling}
One of the aspects of the {\it Discuss} client programs is that they use
different packages within the same program.  These packages come from
different sources, and each has its own way of reporting error
conditions.  Although UNIX has well-defined error handling for kernel
routines, there is no standard way for libraries to return errors.  In
many cases, each package defines a set of error codes, and provides a
separate method of converting this error code into an error message.  For some
procedure calls, an error may arise from several sources.  In this
situation, there is no way for the calling procedure to understand the
error.

In response to this problem, we created the {\it com\_err} package.
It allows multiple libraries to return error codes in a coherent
manner.  With {\it com\_err}, errors are represented as 32-bit
unsigned integers.  These integers can be returned by functions,
passed between different libraries, and sent over the network.  The
{\it com\_err} library supplies a routine to convert these integers
into error messages.

To use {\it com\_err}, the programmer first creates a text file
describing the error table.  This text file names the error table, and
lists the symbolic names of the error codes and the error messages
associated with them.  The {\it error table compiler} reads this text
file, and produces two files: a C source file that defines the
symbolic names as C-preprocessor symbols, and an object file
containing the error messages.  The programmer includes the C source
file to obtain definitions for the error codes, and links the object
file into the application.

To avoid collisions between error codes, {\it com\_err} uses the error
table name to generate the numbers for error codes.  Error tables are
named using four letters.  {\it com\_err} collapses these letters into
the top 24 bits of the error code, leaving 8 bits to differentiate
among different errors in the same error table.  This restricts error
tables to at most 256 entries, which has proven more than adequate.
The first 256 error codes are reserved for UNIX errors, so that UNIX
errors can be treated as {\it com\_err} codes.

We added {\it com\_err} to {\it Discuss} by generating error tables
for the different packages it used.  For packages that have their own
error codes, such as {\it Kerberos}, the caller of the package
converts the returned value into a {\it com\_err} codes by adding a
constant.  All {\it Discuss} routines return standard {\it com\_err}
error codes.

{\it com\_err} provides a flexible approach of handling error codes,
and has been adopted for other projects.  For example, {\it Zephyr}
uses {\it com\_err} to encode and transmit error indications.  {\it
com\_err} provides the glue that allows multiple packages to be
integrated smoothly.