% % 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 ====> WU-Wien Gopher Information Service: Main Menu gopher.wu-wien.ac.at:70 <1> About Internet Gopher (gopher.wu-wien.ac.at:70) Local Info ---------------------------------------------------------------------- Gophers around the house (Univ. Economics, Vienna) Gophers around the place (Austrian Universities) Gophers around the world (and other information services) ---------------------------------------------------------------------- Early Music List: archives of EARLYM-L@AEARN.bitnet + rec.music.early CERRO: the Central European Regional Research Organization WAFE: Widget Athena Frontend documents services external services pointers (things you might also find elsewhere) life, the NET and everything The Guide! ---------------------------------------------------------------------- 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