This is the README file for CMS Gopher 2.4.2 (ver 2 rel 4 mod 2).
If you have any questions, send e-mail to
[email protected].
You can acquire updates and refreshes via Gopher from the
Gopher server at ricevm1.rice.edu. This is VRM 2.4.2.
Copyright 1993 Richard M. Troth. This software was developed
with resources provided by Rice University and is intended
to serve Rice's user community. Rice has benefitted greatly
from the free distribution of software, therefore distribution
of unmodified copies of this material is not restricted.
You may change your own copy as needed. Neither Rice
University nor any of its employees or students shall be held
liable for damages resulting from the use of this software.
You will need CMS Pipelines. (5785-RAC)
You will need VM TCP/IP, V2 or later. (5735-FAL)
You will need REXX/Sockets (supplied), a part of VM TCP/IP.
------ ------ ------ ------ ------ ------ ------ ------ ------
PLEASE NOTE: when fetching MODULEs and VMARC files from some hosts,
the record structure must be restored. If you pick-up a MODULE from
a UNIX FTP host, you must "deblock" it back into its CMS form with:
PIPE < program MODRAW | DEBLOCK CMS | > program MODULE A
For VMARC files, reblock to Fixed 80 with:
PIPE < package VMARCRAW | FBLOCK 80 00 | > package VMARC A
and then "vmarc unpk" the package.
CMS TAR files are true binary and need not be re-blocked.
MODULEs and other record oriented files archived into a CMS TAR
file or tape will be correctly re-blocked by CMS TAR.
------ ------ ------ ------ ------ ------ ------ ------ ------
See GOPHER24 FILELIST for a complete list of files.
Experimental Forms Oriented Feedback support is included.
To display GIFs with CMS Gopher, get the VMGIF package from
LISTSERV at BLEKUL11, or via Anonymous FTP to cc1.kuleuven.ac.be.
To process MIME type objects with CMS Gopher, get the MIME package.
(should be found wherever you acquired this Gopher package)
The gem EXPAND REXX (expand TABs) has been replaced by
the gem UNTAB REXX, which should soon be replaced by a
CMS Pipelines built-in function (probably CMS 10).
Dieter Gobbers and Alan Flavell graciously created and supplied a
German message repository. Other languages would be most welcome.
Rice's CMS Gopher client is the only one I know of that is mult-lingual.
You can (and should) get the full PH PACKAGE from
LISTSERV at IRISHVMA or from Nick LaFlamme, NLAFLAMM at IRISHVMA.
After a year and half, Gopher's HELP files are still crummy.
------ ------ ------ ------ ------ ------ ------ ------ ------
Client Features:
o displays GIFs via the VMGIF package from BLEKUL11 (not supplied)
o processes MIME objects via optional MIME package (not supplied)
o handles WAIS searched menus
o interacts with CSO/qi phonebook servers via PH EXEC
o can use any file viewer you desire
o "next item" key
o bookmarks
o multi-lingual (German and American English supplied)
Server Features:
o hierarchical menus with or without SFS
o both static and dynamic files (latter created by pipes)
o offers WAIS-like searched menus internally with WISHLP tool
------ ------ ------ ------ ------ ------ ------ ------ ------
WELCOME
Welcome to GopherSpace! I hope you enjoy your trek.
If you have any questions about the Rice CMS Gopher client or server
or if you have trouble setting them up, send e-mail to Rick Troth,
[email protected], or call me at (713) 285-5148. There's also a dis-
cussion list to which you may subscribe:
[email protected].
Subscribe with a note to
[email protected] with the following:
subscribe vmgopher first-name last-name
The InterNet Gopher (or just "gopher" for short) is a simple
information dispersal tool based on TCP/IP. It is an example
of the kind of seemless interoperability that is possible
when we (programmers) actually try to do things right.
The Gopher protocol doesn't care about host operating systems,
their file storage formats, character sets, or command suite
(or lack thereof).
CMS Gopher is based on three very strong tools: the REXX language,
Arty Ecock's REXX/Sockets, and CMS Pipelines. As a programmer,
I literally went to tears over how well these three work together.
More warm fuzzies later. You need to unpack this thing.
------ ------ ------ ------ ------ ------ ------ ------ ------
SETTING UP THE CLIENT
Don't access an old version of Gopher in front of a new version.
You may have some special method of giving users access to your
CMS applications. At Rice, we keep most applications on their own
minidisk, and leave a "wrapper" EXEC on a public, always accessed
minidisk (our X disk). The client is GOPCLI. Whatever wrapper you
create should STATE GOPCLI EXEC and access the right disk or SFS
directory if it's missing.
You may want to tailor a couple of environment variables. There's no
CONFIG file for the client in CMS Gopher 2.4. All configuration data
are kept in user GLOBALVs. See HELP GOPHER for a list of user-settable
Global Variables. HOST and NAME are two that many people like to predefine.
HOST is the TCP/IP host computer where your "top level" gopher server runs.
NAME is the name of that "top level" menu. (there's no way in the
Gopher protocol for a menu to name itself; all menus and plain files
are named by the menu that references them, so you need to set NAME
or you'll get "(root menu)", harmless but ugly)
Note that the client reserves the fileid VMGOPHER DOCUMENT for times
when it needs to write a file to CMS disk if it can't make sense of
the name provided by the current server. (servers may be running on
UNIX, VAX/VMS, MVS, PC/MS-DOS, or even Macintosh)
PICTURES
CMS Gopher 2.4 supports the gopher "image" (type I) files. Presently,
the only format displayable is GIF files using the VMGIF package available
from the fine folks at BLEKUL11:
tell listserv at blekul11 get vmgif package
MIME objects
CMS Gopher 2.4 supports MIME type items. All you need is for the
MIME package (found wherever you picked-up this Gopher package)
to be available on an accessed minidisk or directory.
If MIMEREAD REXX is missing, Gopher presents MIME objects as text.
------ ------ ------ ------ ------ ------ ------ ------ ------
SETTING UP THE SERVER
The server is GOPSRV. Setting it up is trickier than setting up the
client because you not only have to create a virtual machine for it to
run in, but you also have to take the time to structure your gopher data
nicely. See GOPHERD DIRECT for an example CP Directory entry.
You can have multiple gopher servers.
If you don't have SFS, you can create a hierarchical set of menus using
FILELISTs. Some VMers insist on using FLIST. They say it's faster
than FILELIST. Fine. But FILELIST lets you save and load FILELISTs
such that you can easily bundle files together almost as easily as with
true directories. If you do have SFS, you can let it do the work of
maintaining your menu hierarchy.
Gopher FILELISTs are made up of lines of the form:
fn ft fm path "name" type
where fn/ft/fm are the filename, filetype, and filemode
of the file being referenced. The path is really only the last part of
the gopher "selector string" pointing to this file. The paths of all
parent menus are automatically prepended. The name (must be in quotes)
is what the user sees in the menu referencing this file. The type is a
one-digit type indicator, any of:
0 this file is plain-text
1 this item is a menu
4 this is a Macintosh file
5 this is an MS-DOS file
6 this is a UUEncoded file
7 this item is a search on a menu
9 this is a binary file
I image (graphic; typically GIF)
s a sound file
M a MIME object
F a forms-oriented feedback item
There are other types, but these are the ones most useful in FILELISTs.
Everything except the filename is optional. Filetype, filemode, path,
name and type may all be omitted, in which case the server will choose.
The first character of each line in a Gopher FILELIST must be either
a blank or an asterisk, the latter denoting a comment. With care,
you can in fact use a Gopher FILELIST as input to CMS' FILELIST EXEC.
I mentioned the menu type, digit 1. Please note that you do NOT specify
a menu within a menu by marking some file as type 1, but rather by using
a special filetype "*". The server will automatically mark it as type 1.
The "root" menu is defined by <userid> FILELIST, where <userid>
is the name of your gopher server virtual machine, typically GOPHERD.
You can override this and other parameters in GOPHERD CONFIG.
So, making a long story longer, to setup your gopher server, define
virtual machine GOPHERD, give it access to your local gopher disk,
create GOPHERD FILELIST listing one or more files you wish to serve-out,
then CP AUTOLOG GOPHERD.
This "picture" might illustrate what I'm trying to say:
GOPHERD virtual machine
\
GOPHERD FILELIST "root menu"
\
GOPHERD README
MYFILE DOCUMENT
SUBMENU FILELIST
\
FILE1 DOCUMENT
FILE2 DOCUMENT
FILE3 DOCUMENT
There is a CONFIG file, which you can tailor as needed. With the 2.4
server, the only variables meaningful in the config file are LOGPIPE,
PORT, and ROOT. PORT defaults to 70. ROOT defaults to the virtual
machine name (server's userid). LOGPIPE defaults to CONSOLE.
You will probably want to dedicate port 70 to GOPHERD in your local
PROFILE TCPIP for you TCPIP service virtual machine. It's also good
to have GOPHERD listed as AUTOLOGged by TCPIP. Neither of these steps
are required to test GOPHERD; just run it. It's pretty harmless.
PIPES AND AUTHORIZATIONS
A nice way to degrade performance of your gopher server is to create a
NAMES file for a menu. In spite of the cost, this is useful because
you can control access to and/or define CMS Pipelines specifications for
menus and items in the NAMES file.
When the server accesses a directory, it looks for <menu> NAMES.
(this works best with FILELISTs; if you do it for SFS directories,
consider that the server may access other directories, releasing the
one that holds your NAMES file, as it resolves the selector path string)
If <menu> NAMES exists, the server uses NAMEFIND to process it.
This is best explained by an example:
:nick.myfile :fn.my :ft.file
:auth..rice.edu deny .cuny.edu .gov allow *
:pipe.CP Q NAMES | SPLIT /,/
For the file MY FILE, any host who's InterNet hostname ends in
".rice.edu" (all of the Rice campus) can read it. Any host who's
InterNet hostname ends with ".cuny.edu" or ".gov" is prohibited.
Everyone else is then permitted. If the client is permitted access,
then instead of reading the file MY FILE, the server sends the output
of the pipeline CP Q NAMES | SPLIT /,/ to the client.
This can get quite sophisticated. No, you do not have to have both
an auth and a pipe in the NAMES file entry. You can have either one
or neither. And know that CMS NAMEFIND does not provide a way to
specify the filemode of the NAMES file, so be careful about menu
name collisions.
You can also specify host, port, path, name, and type in a NAMES file.
This means that you can use NAMES files in place of GOPLINK files,
but remember that NAMEFIND is going to cost you.
Link files? They let you point to other gopher servers.
See the Q&A section below, otherwise this section will go on forever.
SEARCH ITEM
Creating a search item in a menu is easy. Set it up just like you
would any other sub-menu, but mark it as Type 7. Something like:
MYSEARCH FILELIST * whatever "My Own Search Item" 7
in the parent menu's FILELIST.
There's no reason why you can't have the menu as a whole listed
right next to the searched version, like:
MYSEARCH FILELIST * whatever "My Own Search Item" 7
MYSEARCH FILELIST * whatever "My Own Search Item (not indexed)"
You must also create an index file for this menu. The easiest way is
by using GOPGEN. GOPGEN is primarily a tool for making your own mods
to CMS Gopher, but it also performs the right incantation on WISHLG
(thank's Yossie) to create an index for you. The server then will
invoke WISHLP (thank's again, Yossie) to list the files that match
the client's search expression.
GOPGEN INDEX MYSEARCH
MYSEARCH FILELIST must exist. All of the files it lists must exist.
You must then put the index file, MYSEARCH GOPINDEX, where the server
will access it.
------ ------ ------ ------ ------ ------ ------ ------ ------
FUNCTIONS OF FILES
Here's a list of most of the files in the package and their function:
GOPHER EXEC "wrapper" EXEC; ensures product disk accessed
GOPCLI EXEC the client
GOPCLINI EXEC client initialization (called once from GOPCLI)
GOPCLISX REXX handles all TCP/IP "sockets" work for the client
GOPCLITM REXX decides what how a given item should be processed
GOPCLIST REXX displays connection status, "Reading ...", etc
GOPCLIMB REXX menu browser
GOPCLIUI REXX user input (prompting)
GOPCLITX REXX reformats plain-text
GOPCLIFV REXX file viewer; may be used stand-alone
GOPCLIGV REXX graphics viewer; presently GIFs only
GOPCLIFI EXEC returns legal CMS fileid from a gopherspace path
GVM EXEC "DIALed Gopher" client; calls GOPHER to call GOPCLI
GVM DIRECT CP Directory entry for the DIALed Gopher
GOPHERD EXEC "wrapper" EXEC for the server; write your own
GOPSRV EXEC the server
GOPSRVLS REXX lists files and menus (menus in LISTFILE format)
GOPSRVRP REXX gopher path resolution; uses GOPSRVLS output
GOPSRVMB REXX menu builder
GOPSRVGL REXX gopher "link" processor
GOPSRVAU EXEC performs authorization check
GOPSRVFM EXEC dummy filemode function for server
GOPHERD DIRECT example CP Directory entry for the server
UNTAB REXX expands TAB characters
PRINT REXX similar to CMS PRINT, but a pipe
A2E REXX translate ASCII to EBCDIC
E2A REXX translate EBCDIC to ASCII
TCPA2E REXX A2E, but follows TCP/IP translate tables
TCPE2A REXX E2A, " " " " "
STANDARD TCPXLATE suggested ASCII <---> EBCDIC translate tables
STANDARD TCPXLBIN binary object built from above TCPXLATE
GOPUME MESSAGES message repository source
GOPUME TEXT message repository object
GOPXEDPR XEDIT XEDIT profile for XEDIT used as file viewer
GOPXEDII XEDIT "item info" command for XEDIT as file viewer
GOPHMARK EXEC migrates bookmars from 2.3
RXSOCKET MODULE Arty's wonderful CMS Socket tool
DISKWRIT MODULE minidisk need reACCESSing?
WISHLP MODULE Yossie's *fast* search engine
WISHLG MODULE index builder for above
PH EXEC Nick LaFlamme's CSO/qi/ph (phonebook) client
GL EXEC primitive tool for browsing CMS Gopher FILELISTs
GOPHERCAT EXEC dumps gopherspace files right onto your console
GOPHERDH REXX a pipeline stage that interprets CMS HELP
HELP NAMES defines HELP menu to the server using above
------ ------ ------ ------ ------ ------ ------ ------ ------
There is a discussion list,
[email protected].
Please join us. We discuss development and featurs of CMS Gopher.
There is another CMS Gopher (both server and client), popularly called
"the Vienna Gopher", available from Gerhard Gonter <GONTER@AWIWUW11>.
------ ------ ------ ------ ------ ------ ------ ------ ------
Q: The basics, documents and FILELIST menus, is fairly easy to grasp,
but the relationship of a NAMES file and its entries to a FILELIST
file and its entries is not at all evident to the poor soul that
just wants to provide an information service without much time
invested (I.e., without subscribing to VMGOPHER).
A: The easiest way to start is just name some plain-text files in
GOPHERD FILELIST (which are available to your GOPHERD service
machine on an accessed disk or SFS directory). Then after you're
comfortable with that, try some "links" (filetype GOPLINK) and
sub-menus (filetype FILELIST). Then get into NAMES files.
Q: How to I point to another server/menu?
A: The easiest way is with a "link" file (filetype GOPLINK).
When a link file shows-up in any FILELIST, the contents of
that file are read and the information specified is presented
to the client for that particular menu item.
The contents of a GOPLINK file are the same as
for a UNIX server link file, of the form:
Name=Rice University CMS Gopher server
Host=ricevm1.rice.edu
Port=70
Path=1/
Type=1
As of 2.4, GOPLINK file can have more than one link in it.
(but you will probably find things easier to manage
if you have just one link per GOPLINK file)
NOTE: Gopher server link files MUST be RECFM V or you
will get trailing blanks which UNIX servers won't like.
Q: How does a GOPLINK file differ from a "link" in a NAMES file?
A: The NAMES file is far more extensive. (and exPensive)
With the CMS Gopher server, you don't use "link" files to
override the characteristics of other files in the menu (as you
would with a UNIX server). With the CMS server, GOPLINK
files are exclusively used to reference other network (usually
non-local) resources, while the NAMES file may apply to local
files, which reside on your system OR to remote services.
Q: Some folks have made it seem that their gopher server files
are free for the taking ... is there a gopher feature
to pull these in?
A: To "receive" (keep) an item, press PF5. The receive function
will not overwrite an existing file (though you can still
view & SAVE from XEDIT).
Q: GOPHERD should document DISKWRIT in the prolog.
A: GOPHERD uses DISKWRIT to perform the same "reaccess" trick that
GONE EXEC does when you reconnect. If disks appear to have
changed, they are reACCESSed so that the server has the latest
revision of any files on those minidisks.
Q: Why are the "STANDARD" translate-table files provided?
Are these for use with the server?
A: Both server and client.
The default ASCII <---> EBCDIC translation in VM TCP/IP (FAL)
is not 100% correct for the majority of the VM/UNIX/VMS/DOS/Mac
world we live in. STANDARD TCPXLATE and TCPXLBIN provide
a 1-for-1 translation between de-facto "network EBCDIC"
(codepage 1047) and "extended ASCII" (ISO 8859-1).
Q: If PhoneBk and Search are available, how do we use them?
A: Presently, CMS GopherD does not support PhoneBk engines.
Search engine is provided by Yossie Silverman's WISHLG/WISHLP.
The client (GOPCLI) is happy to utilize such servers on any
