%
% File viegophr.tex
%
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%+ INTERNET GOPHER, CLIENT & SERVER FOR IBM VM/CMS    (1992-06-19/15:00) +
%+                                                                       +
%+ Notes on installation and usage of the `Vienna' VM/CMS GOPHER System. +
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%
% NOTE: This is not the original version of the document!
%       Instead, this is the sequenced and stripped version of a
%       hypertext file.
%       The linear LaTeX version is provided for your convenience.
%       For more information about the hypertext version contact the author.
%       LaTeX is described in: (I'm not sure..)
%         Leslie Lamport:  LaTeX, A document preparation system
%         Addison Wesley
%
\documentstyle{article}
\pagestyle{headings}

% pagelayout ---------
% \topmargin10mm
% \headheight12mm
% \headsep5mm
% \topskip0mm
% \textheight245mm
% \textwidth175mm
% \oddsidemargin17mm
% \evensidemargin65mm
% \marginparwidth46mm
% \marginparsep5mm
% \marginparpush5mm

%needed???? yes...
\newfont{\vsmtt}{cmtt8 scaled 1000} % very small type writer

%\makeindex

\begin{document}



\pagenumbering{roman}
\thispagestyle{empty}
\title{VieGOPHER\\---\\A Gopher System for VM/CMS}
\author{Gerhard Gonter}
\date{\today}
\maketitle

\begin{abstract}\footnote{This
file is still somewhat ... er ... incomplete ... sorry ...}
The Internet Gopher Protocol provides a simple, yet very effective
method for distributed document search and retrieval.  This document
describes usage, installation, maintainance and also some points 
about the implementation of a Gopher
system for IBM's operating system VM/CMS, called the VieGOPHER.
Both, using the client and administrating the server are discussed.

The system can be distributed freely and is dedicated to the community
of cyberspace.
\end{abstract}

\pagebreak[4]
\tableofcontents
\pagebreak[4]
\listoftables
\listoffigures
\pagebreak[4]

\newcommand{\SUBsection}[1]{\subsection{#1}}
\newcommand{\SUBsubsection}[1]{\subsubsection{#1}}

% ---------------------------------------------------------------------- 
\setcounter{page}{1}
\pagenumbering{arabic}



\section{Introduction}

This document describes an implementation of the Internet GOPHER Server
and Client protocol for IBM's operating system VM/CMS, known as the
`Vienna' VM Gopher System or `VieGOPHER'.
There are things left out and enhancements will follow.  If you find any
errors or have other suggestion then don't hesitate to contact me on one
of the addresses given in section \ref{gg.addr} on page \pageref{gg.addr}.
 
The system consists of a client, based on {\sf XEDIT} ({\tt GOPHERC.EXEC}
together with
a bunch of {\tt .XEDIT} and {\tt .EXEC} files) and two servers,
the older one is a simple,
straight forward, plain vanilla, nothing special, ordinary, single-treaded
Internet Gopher Server\footnote{not supported anymore} ({\tt GOPHERD.EXEC}),
the new one ({\tt GOPHERDD.EXEC}) %\index{GOPHERDD.EXEC}
is just the opposite of that all...  well...  the most interesting feature
of it is that it is multi-threaded.  This means, it can handle more than
one connection at the same time and, in fact, the version I currently run
listens on four ports at the same time and is still able to handle a
couple of connections simultanously.  Since this server listens on four
different ports you might suspect that one is the officially assigned
gopher port (70) and the the other two ports are something else.  This
assumption is not completely wrong, the server also listens on port 79
and pretends to be a finger server as well on port 17 and serves out fortune
cookies.  The service on port 17 is also known as the Quote-of-the-Day
protocol.  Finger protocol (see \cite{rfc1288})
and Quote-of-the-Day protocol (see \cite{rfc865})
are handled by the Gopher Server as a by-product,
as you may have time to read in the code.
 
In order to run either the server or the client you also need a program
called {\tt REXTCPIP.MODULE} (by Ken Hornstein).  You can find it on any
{\sf BITNET LISTSERV} that carries {\sf VM-UTIL}, (e.g. {\sf DEARN}).
Be sure to use version 1.8.4. or newer.  Section \ref{bugs} gives
information about modifications that improve the stability of the
program.  If necessary, a modified version can be obtained from me.
You also need TCPIP to run either the server or the client.
The new server can also employ {\tt YWAKEUP.MODULE} to trap messages
from servicing machines.

Clients running under TCPIP version 2 can take advantage of RXSOCKET
instead of REXTCPIP.  RXSOCKET is generally more elaborate and
stable, either version 1 or can be used.

The instability of REXTCPIP is the main weaknes of the server.
To overcome this problem I work along three paths:
\begin{enumerate}
\item   I try to make the REXX code of the server as shock-proof
        as possible,
\item   I try to correct some of the problems inherent in
        REXTCPIP, see section \ref{bugs} for a documentation
        about some of the patches sofar,
\item   allowing to select RXSOCKET seems to be the most
        promising path in the long run.
\end{enumerate}
 


\subsection{Features}

\noindent Client:
\noindent\begin{itemize}
\item can work with WAIS search gateways
\item convenient XEDIT interface
\end{itemize}

\noindent Server:
\noindent\begin{itemize}
\item multiple connections
\item integrated finger server
\item integrated cookie server
\item interface for embedded applications
\end{itemize}

% ---------------------------------------------------------------------- 


\subsection{{\sc Rose} installation procedure}

The source code of the programs and the parts of the \LaTeX\ documentation
are stored together in NED's HYX format --- NED is a MSDOS `hypertexty'
text editor.  From this source three text files are generated:
\begin{itemize}
\item   {\tt VIEGOPHR.PRO(DUCT)} containing the program code,
\item   {\tt VIEGOPHR.TEX} containing the documentation,
        (this document)
\item   {\tt VIEG-PRO.TEX} containing the source code listing.
\end{itemize}

{\tt VIEGOPHR.PRODUCT} needs to be processed by {\tt ROSE.EXEC}.
{\sc Rose} is not part of VieGOPHER, however, it was developed
for it's installation.
The program can be distributed freely just as the other
package.  

% To install VieGOPHER using {\sc Rose} these conditions should be met:
% $\Box$ the files {\tt ROSE.EXEC} and {\tt VIEGOPHR.PRODUCT} in
% read access on any minidisk.  A read/write minidisk as A with at
% least XXX free blocks.  If you have the $\Box$ optional file
% {\tt VIEGOPHR.FIX}, possibly from an earlier experience with {\sc Rose},
% then you should place it now on minidisk A.  Note:  This file
% will be changed or created during installation.

\subsubsection{Quick'n'dirty installation}

Appendix \ref{inst.opts} on page \pageref{inst.opts} lists all {\sc Rose}
prompt texts that will be presented during the installation phase.

\noindent
Use this checklist to get the system off the ground:
\begin{itemize}
\item[1 $\Box$] Put {\tt VIEGOPHR.PRODCUT} and {\tt ROSE.EXEC}
                on any readable minidisk.

\item[2 $\Box$] Prepare a R/W minidisk with filemode A with at
                least 2 cylinders (275 blocks with 4096 byte).

\item[3 $\Box$] If you have {\tt VIEGOPHR.FIX} around somewhere,
                you can place it on minidisk A, but this is not necessary.

\item[4 $\Box$] Start the program generator by entering:
                {\tt ROSE VIEGOPHR}

\item[5 $\Box$]  Read the options presented by {\sc Rose} and answer the questions
        appropriately.  In most cases you will want to use the
        predefined option.  In this case simply enter code 1 or hit
        the ENTER key.  If you want to change something enter code 3
        (followed by pressing the ENTER key of course) and then enter
        the value that you want to use.

\item[6 $\Box$]  After prompting for all options {\sc Rose} will generate all
        modules and invoke the postinstallation procedure {\tt GOPHINST.EXEC}.

\item[7 $\Box$]  Fetch any missing file that the postinstallion procedure might
        point out.  If the postinstallation procedure finds
        inconstencies in your installation, remove the appropriate
        line from {\tt VIEGOPHR.FIX} and go back to step 4.

\item[8 $\Box$]  Put the file {\tt VIEGOPHR.FIX} at a safe place.  You might want
        to use it again for a fast re-installation later on.

\item[9 $\Box$]  Place {\tt RXSOCKET.MODULE} and/or {\tt REXTCPIP.MODULE} on minidisk A.

\item[10 $\Box$]  Done!  Your minidisk A should now contain all necessary programs 
        for the client and server.

\item[11 $\Box$]  If you don't want the server you can remove {\tt GOPHERDD.EXEC}.

\item[12 $\Box$]  If you want to run the server it's time to look through
        this document ({\tt VIEGOPHR.PS}) now to find out about
        index files, access groups, etc...
\end{itemize}



\section{Client}

% * Client Modules
% * General Module Layout
%   * Modules from other Sources
% * Installation
%   * Quick Installation
%     Professional Installation
%     * (1)
%     * Fig: Instsec in GOPHER.EXEC
%     * (2)
%     * Fig: Instsec in GOPHFTCH.EXEC
%     * (3)
% * Files
% * Global Variables
%   * User Setup
%   * temporary variables used by the GOPHER modules
% * Using the Client
%   * Fig: Root Index Screen
%   * temp files



\subsection{Client Modules}

The client is based on {\sf XEDIT} and {\sf REXTCPIP} or {\sf RXSOCKET}.
It does not
require any other non-standard extensions of the operating system, like
{\sf CMS-PIPES} and should also work with TCP/IP release 1 (the
REXTCPIP version only).




\subsection{General Module Layout}

 


\subsubsection{Modules from other Sources}
 
The files {\tt REXTCPIP.MODULE} and {\tt RXSOCKET.MODULE}
alternatively provide the network transport system.
 
TCP/IP must be available to the user; the TCPIP public disk is not
required unless the user also wants to use TELNET.
 
 


\subsection{Installation}

%   * Quick Installation
%   * Professional Installation
%     * (1)
%     * Fig: Instsec in GOPHER.EXEC
%     * (2)
%     * Fig: Instsec in GOPHFTCH.EXEC
%     * (3)


\subsubsection{Quick Installation}

Installing the VieGOPHER client quickly is fairly easy:  Just get the
distribution package\footnote{see appendix \ref{sources} how to obtain it},
and follow the installation procedures given in the readme file (or
in the introduction),
get {\tt REXTCPIP.MODULE} version 1.8.4 or {\tt RXSOCKET.MODULE},
put everything on your minidisk, and type {\tt GOPHER}.
If everything is ok you should get the root menu of the server
{\tt gopher.wu-wien.ac.at}\footnote{Figure \ref{run.cl1} on page
\pageref{run.cl1} shows such a menu}, otherwise you have a problem.
% and you should consider reading the upcomming section about
% professional installation.



\SUBsection{Using the Client}

The gopher client is invoked by executing GOPHER.  If everything is set up
properly, the root menu of your default server should appear within a
few seconds.  Figure \ref{run.cl1} shows a root menu.  The beginning of
a menu line contains an item marker, {\tt $<$F$>$} indicates a text file
and {\tt $<$D$>$} indicates another menu or directory.
Table \ref{supported.items} lists all item types that are supported
by this client.  Please note that other servers might also provide
different item types, these are flagged by a marker of the form
{\tt $>$}{\sl{x}}{\tt{$<$}}.  A list of other know item types is provided
in table \ref{supported.items}.

%    * Fig: Root Index Screen
%    * Programmable Function Keys
%      * (1)
%      * Fig: Programmable Function Keys
%      * (2)
%    * Bookmarks
%    * saving items
%    * Feedback
%    * Outlook
%    * temp files
%    * Supported Item Types
%    * Tbl: Supported Item Types


\begin{figure}
\caption{Root Index of a Gopher Server}\label{run.cl1}
\rule{0mm}{2mm}
\begin{center}
\begin{small}
\begin{verbatim}
 GOPHTMP  TMP0     A1  V 122  Trunc=122 Size=20 Line=1 Col=1 Alt=0
====>
<D> WU-Wien Gopher Information Service: Main Menu
gopher.wu-wien.ac.at:70 <1>                                                  
<F> About Internet Gopher (gopher.wu-wien.ac.at:70)
<D> Local Info
<F> ----------------------------------------------------------------------
<D> Gophers around the house (Univ. Economics, Vienna)
<D> Gophers around the place (Austrian Universities)
<D> Gophers around the world (and other information services)
<F> ----------------------------------------------------------------------
<D> Early Music List: archives of EARLYM-L@AEARN.bitnet + rec.music.early
<D> CERRO: the Central European Regional Research Organization
<D> WAFE: Widget Athena Frontend
<D> documents
<D> services
<D> external services
<D> pointers                        (things you might also find elsewhere)
<D> life, the NET and everything
<D> The Guide!
<F> ----------------------------------------------------------------------
<D> VieGOPHER: VM/CMS Gopher Version
 1= Help      2=(altpfs)  3= GoBack  4= Disp->BMK   5= Curs->BMK   6= BMK  
 7= PageUP    8= PageDN   9= Save   10=            11= Display    12= Circle


\end{verbatim}
\end{small}
\end{center}
\rule{0mm}{2mm}
\end{figure}
 


\SUBsubsection{Programmable Function Keys}

Basically, the user interface is `pure' {\sf XEDIT} with a customized
PF-key setting.  How the keys are set up is shown in table \ref{PF.keys}.



\begin{table}
\caption{Programmable Function Keys}\label{PF.keys}
\rule{0mm}{2mm} % see also * setup for the keys
\begin{center}
\noindent\begin{tabular}{|l|l|l|}
\hline
Key     & Label             & Description\\
\hline\hline
PF1     & {\tt Help}        & activate help menu (just for XEDIT)           \\
PF2     & {\tt (altpfs)}    & assing PF 1-12 with functions of PF 13-24     \\
PF3     & {\tt GoBack}      & quit the currently displayed item             \\
PF4     & {\tt Disp-$>$BMK} & save a bookmark for the currently             \\
        &                   & displayed item                                \\
\hline
PF5     & {\tt Curs-$>$BMK} & save a bookmark for the menu item that is in  \\
        &                   & the line where the cursor currently is        \\
PF6     & {\tt BMK}         & activate (display) bookmark file as a menu    \\
PF7     & {\tt PageUP}      & go one page back (up)                         \\
PF8     & {\tt PageDN}      & go one page forward (down)                    \\
\hline
PF9     & {\tt Save}        & save the item that is currently displayed     \\
PF10    &                   & {\it unassigned yet, reserved ***}            \\
PF11    & {\tt Display}     & display item of line where cursor is currently\\
PF12    & {\tt Circle}      & switch to next active item                    \\
\hline\hline
PF13    & {\tt First}       & goto first screen if still active             \\
PF14    & {\tt (basepfs)}   & assign PF 1-12 with base functions            \\
PF15    & {\tt Exit}        & leave Gopher immediately                      \\
PF16    &                   & {\it unassigned yet, reserved ***}            \\
\hline
PF17    & {\tt Split}       & split the screen                              \\
PF18    & {\tt Join}        & join screens                                  \\
PF19    & {\tt PageUP}      & go one page back (up)                         \\
PF20    & {\tt PageDN}      & go one page forward (down)                    \\
\hline
PF21    & {\tt ShowRing}    & show active items in XEDIT ring               \\
PF22    &                   & {\it unassigned yet, reserved ***}            \\
PF23    & {\tt Setup}       & Setup some parameters for using Gopher        \\
PF24    & {\tt Execute}     & execute command                               \\
\hline\hline
ENTER   &                   & display item of line where cursor currently is\\
\hline
\end{tabular}
\end{center}
\end{table}




PF24 triggers execution of general editor commands just like the ENTER
key would do during a normal XEDIT session while the ENTER key has the
same function as PF11, that is displaying the selected item.
Activating the {\tt Display} function will make the
Gopher client fetch the item described by the line of the menu where
the cursor is currently in, the result is then displayed as a new XEDIT
file. The file containing the menu is then still ac