                          Using MAIL-SERVER
                          -----------------
 
                                  by
 
                           Adrian F. Clark
                           (18th May 1988)
 
                  Revised by Brian {Hamilton Kelly}
                         (18th October 1990)
 
For network users who can send mail but not  transfer files, accessing
remote archives is a problem.  The  conventional way to  do this is to
use `mail servers'  on the machines holding  the archives.   These are
programs which read mail messages directed  to  a specific username on
the archive machine, with  the message consisting  of commands  to the
mail  server.  The  server processes the   commands  which are usually
requests to send files to the requestor as mail messages.
 
The mail server described  here is intended  for  use on VAX computers
running   the VMS  operating   system.  It  accepts  several commands,
described in the  following  sections.  In each  case, the commands to
the server are specified in the body  of  the mail message.  This is a
little  different  from  many other mail  servers, which   require the
command to be in the `subject' field of the mail message.
 
 
Where is the TeX Archive Mail Server?
-------------------------------------
 
The TeX  archive's mail server is accessed  by sending a mail request,
containing ONE valid MAIL-SERVER command, to the JANET user
 
                       TEXSERVER@UK.AC.TEX
 
(From outside the  UK JANET community,  it may be necessary to specify
this as TEXSERVER@TEX.AC.UK or even as TEXSERVER%TEX.AC.UK@<gateway>.)
 
Note that MAIL-SERVER operates without any  operator interaction: your
mail is never seen by human  eyes (unless  the  archive  maintainer is
deliberately doing so), so it is  essential that you get your requests
right. INVALID REQUESTS ARE SIMPLY IGNORED!
 
 
Note
----
 
There  is currently one  restriction  on the  use of MAIL-SERVER:  the
/COMPRESS and   /DECOMPRESS qualifiers produce compressed files  which
are readable only under VMS.  This is  because the author has not been
able to trace a version  of the Lempel-Ziv compression software  which
runs under VMS and  produces  files  readable under Unix. If anyone is
able to supply such software, the author would be eternally grateful.
 
Format of TeXserver Requests
----------------------------
 
The  TeXserver  used to require  that  messages  be sent in a peculiar
format which contained the following sequence of records:
 
1) Any number of lines of text, which would be ignored entirely.
2) A line starting with three hyphens: remaining text on this line was
   ignored.
3) Your e-mail address, as seen by Aston.  This had to include any
   necessary gateway explicitly.
4) The command for interpretation by the server.
 
This old format can still be used.  However, so many users had so much
trouble  in  specifying  their  return  address,  that  we  have   now
implemented a more intelligent front-end.  In this new message syntax,
you must provide  ONLY  the TeXserver command that you want  executed;
however,  this must appear as the FIRST non-blank line of your message
(after ignoring any RFC-822 headers, etc., inserted by your mailer and
those through which the message reaches Aston).
 
Sometimes  users  want  to specify  a different  return route  for the
information being mailed to them; with the old format, the appropriate
route was merely included on the line after the hyphens.  With the new
format, see the description of the PATH command below.
 
Whenever you send a request to  TeXserver, this front-end examines it,
and will send you a ``receipt'' which  will inform  you as  to whether
your request  was valid or not.   The receipt will be sent back to the
address provided to TeXserver by the incoming mailer: if you don't get
a receipt (or anything else), it may be that Aston  is not  authorized
to send traffic to your site.  For example, traffic to sites connected
to the  UK-PSS  network would have to pass through one of the gateways
between  Janet and PSS,  for which Aston would have to pay real money.
You  may wish to  consider  routing  your  traffic  through one of the
sites,  such as  UK.AC.UKC which  can  handle such commercial traffic,
either by  sending your  requests via that site, or by specifying them
in a PATH command (see below).
 
Valid requests will then  be queued for processing by a separate batch
job: depending upon how many other jobs are  ahead of you in the queue
(and their sizes) this may take between one and twelve hours.
 
Getting Help
------------
 
This help message can be acquired  by sending the following message to
MAIL-SERVER:
 
   HELP
   ignored-text
 
The  FIRST  non-blank  line  should  contain only the word  `HELP' (or
`HELP'  with a language qualifier --- see below),  specified in lower,
UPPER or MiXeD cases.  Any subsequent lines are ignored.
 
This help message is also available  in a variety of  other languages.
The appropriate language  version  is specified   simply  by adding  a
`command  qualifier' to   the HELP  command---so that,  for   example,
`HELP/DANISH' or `HELP/DANSK' will select the  Danish-language version
of the help text.  The following qualifiers are currently supported:
 
   /DANISH  or /DANSK
   /DUTCH   or /NL or /NEDERLANDS
   /FRENCH  or /FRANCAIS
   /GERMAN  or /DEUTSCH
   /ITALIAN or /ITALIANO
   /SPANISH or /ESPAGNOL
   /SWEDISH or /SWEDE
 
You can truncate the qualifier  to the  point of uniqueness,  so  that
`HELP/FRE'  selects French and `HELP/DE' German.  But do so carefully,
for   MAIL-SERVER  will simply    ignore ambiguous  commands  such  as
`HELP/FR'.  And make sure you spell the qualifier correctly!
 
If you requested  HELP  in a language other than English, but received
this instead,  it's because we  haven't yet got a translation into the
requested  language.   Perhaps  you'd  care  to  consider  making  the
translation  yourself,  and mailing it to  <rmcs_tex@uk.ac.tex>.  Your
contribution will receive acknowledgement, of course.
 
It  is well worth  transferring the help  text to yourself  as a first
experiment of the system; this will ensure that  you understand how to
format messages  for MAIL-SERVER and  to specify  network addresses on
VAX/VMS.
 
 
Generating Directory Listings
-----------------------------
 
You can  acquire a directory  listing of (a  part of) the   archive by
sending the following message to MAIL-SERVER:
 
   DIRECTORY directory-specifier
   ignored-text
 
The  `DIRECTORY'  command,  which  can be  specified  in any  case and
truncated to  `DIR',  should be given a directory specification as its
argument,  conforming to the VAX/VMS directory syntax (see below).  If
omitted, a listing of the directory [TEX-ARCHIVE] is returned.
 
Normally, the files listed by the DIRECTORY command can be used as the
basis of a  `FILES' command   (described in  a later section),   which
requests  files to  be  transferred.   VMS  wizards can, however,  put
qualifiers to  the DCL  `DIRECTORY' command *following*  the argument.
The most useful one is  probably `/SIZE', which  returns the file size
in units of 512-byte blocks.   Note  that  to use  qualifiers requires
that you provide a  directory-specifier, even if you want a listing of
[TEX-ARCHIVE] itself.
 
To make  full use of the  `DIRECTORY' command, you  need to know about
VMS filenames.   Firstly, a filename   consists  of three  parts,  the
*name*  itself, the *extension* (file-type)  and the *version number*,
specified as
 
                        name.extension;version
 
Both  the name  and extension   may  be up  to   39  characters  each,
consisting of alphanumerics, dollar, underscore and hyphen.  Upper and
lower case letters are not distinguished.  Note, however,  that `name'
is not the same  as `name.', since   MAIL-SERVER (and the  VMS mailer)
applies a default extension to the former but not to  the  latter.  If
the version   number  is   omitted   (in which  case    the semi-colon
punctuation is not required), VMS   automagically selects the  highest
(most recent).
 
Files, of  course, reside  in directories.   These  are   specified in
square   brackets.   Like  Unix  and  many  other operating   systems,
directories under VMS are hierachical.  Sub-directories are specified,
within the square brackets, following  the parent  directory name  and
separated by periods.  Hence,
 
                     [TEX-ARCHIVE.V_PUBLIC.VV-PUBLIC]
 
is a valid directory name and
 
              [TEX-ARCHIVE.V_PUBLIC.VV-PUBLIC]PRIVATE.TXT;42
 
a file within it.
 
Of  course,   directories  reside  on   discs  and discs   on nodes on
networks...but that is getting needlessly complicated.
 
The other thing you need to know  about is wildcards.  There are three
of them:
 
    *   matches zero or more characters
    %   matches exactly one character   (NB *not* ?)
   ...  matches a sub-directory tree
 
Hence, the MAIL-SERVER command
 
   DIRECTORY [TEX-ARCHIVE...]*.TXT
 
will find  all versions  of  all   files  with  an extension  of  .TXT
(conventional for text files)  in the directory  [TEX-ARCHIVE]  or any
of its sub-directories and  return the output  to you (if  you got the
return address right).
 
 
Searching Files
---------------
 
You can  search through files  in the archive  for a  given  string of
characters.  This  is useful, for  example, when you know something is
present in the archive, but not exactly which files are relevent.  The
SEARCH request has the following format:
 
   SEARCH directory-specifier search-string
   ignored-text
 
The directory specification  should have the  same format as  for  the
`directory' request.  The search string can be any arbitrary series of
characters, but if it includes one or more of the characters '"/@# the
whole string should be enclosed in double quotes (and double quotes in
the search string specified twice consecutively).  For example,
 
   search [TEX-ARCHIVE...]*.TXT text
 
searches all  files  in the archive with  an extension of .TXT for the
string   of   characters   `text'.    (Note   that    the    search is
case-insensitive.)  Similarly, to search for the string `/"text"', one
would use
 
   search [TEX-ARCHIVE...]*.TXT "/""text"""
 
Locating Files
--------------
 
With an archive as large as Aston's it's sometimes difficult to locate
the required file(s).  One *can* pore over a copy of 00DIRECTORY.LIST,
hoping to spot the wanted file, but this is reminiscent of needles and
haystacks.  One could also request a directory listing using the `...'
ellipsis to hunt down the whole tree, but a better method is to use:
 
   WHEREIS name
 
The server will return a directory listing  of all instances of `name'
occurring as the filename part of a file specification, just as if you
had said
 
   DIRECTORY [TEX-ARCHIVE...]name.*
 
Transferring Files
------------------
 
Now  that you can generate listings  of  the contents  of the archive,
extracting  files from it is child's  play!  Simply  edit  the listing
returned by the `DIRECTORY' command into the following form:
 
   FILES
   filename
   filename
   .
   .
   .
 
It is  recommended that you  should remove  the `;n' version specific-
ation from  the  end  of each filename,  particularly with those files
such as  [TEX-ARCHIVE]00DIRECTORY.LIST which are regularly updated: if
you request  a  specific  version, an attempt will be made to send it,
but if  the file  has  been  deleted  between  the  date at which your
directory  listing  was  generated  and  the time  at which  TeXserver
processes your  request,  you'll  get  nothing!   On  the other  hand,
omitting  the version  specifier altogether  will  collect  the latest
version available, so should always be satisfied.
 
Any number of filenames may follow the `FILES' command.  Each filename
must  be  specified  on a separate  line;  each file will normally  be
returned as a separate mail message.  Wildcards are  now  supported by
the  `FILES'  command;  however, don't imagine you'll get the whole of
the archive by asking for [TEX-ARCHIVE...]*.*;*, because the TeXserver
will  run  out  of workspace  long  before it's packaged up the  files
requested!
 
`FILES' supports a number of qualifiers, as follows:
 
/ENCODE.  This specifies that files should be encoded using the `BtoA'
program  before inserting into  an archive (see below) and/or mailing.
This allows binary files to be mailed.
 
/COMPRESS.  This specifies that  files should be compressed  using the
algorithm described in [1]  before  inserting into an  archive  and/or
mailing. (NB: /COMPRESS also implies /ENCODE, since only encoded files
can be mailed.)
 
/DECOMPRESS.  This  specifies that files  should be decompressed using
the algorithm described in [1] before inserting into an archive and/or
mailing.
 
/SHAR.   This  specifies  that the  requested files,  after optionally
encoding and compressing/decompressing, be formed into a single `shell
archive', a format which  can be unpacked into the  original  files on
Unix systems by processing with the Bourne shell (/bin/sh).
 
/DCLAR.   This  specifies that the  requested  files, after optionally
encoding and  compressing/decompressing,  be formed into a single `DCL
archive',  a format  (analogous to the  shell archive)  which  can  be
unpacked  into  the original  files  on  VAX/VMS systems by processing
(`@'-ing) with DCL.
 
These qualifiers can be specified, in any order, following the `FILES'
command, typed in any case and truncated to the point of uniqueness.
 
Note: It is  conventional, but not universal,  for compressed files in
the archive to have an extension which ends in `_Z' (e.g., `.TXT_Z').
 
When   archive  files  (albeit  shar or   dclar) are unpacked   on the
requestor's host, any directory structure present  in the archive will
be  *lost*, since  the  directory information is  stripped off  as the
archive  file is created.  (This is what  most users want,  and avoids
problems  of filename translation.)   Moreover, the unpacked names are
based on the requested filenames; hence, Unix users, who dislike upper
case filenames,  can use lower  case characters in their  requests and
omit the version number,  which will  cause lower case filenames to be
created when unpacking a shar message.
 
DO NOT request that you be sent files with the file type extension and
version number  `.DIR;1':  these are VAX/VMS directory structures, are
binary, and  cause  the  TeXserver  (and  many  mailers)  considerable
indigestion!
 
Executing Arbitrary DCL Commands
--------------------------------
 
This command is likely to be  of interest to VMS  wizards only.  It is
possible to   process an  arbitrary   series   of  DCL commands    via
MAIL-SERVER and have their result  returned to you.  The  mail request
has the following format:
 
   DCL filename
   $ DCL commands
   $ which generate
   $ the file `filename'
   .
   .
   .
 
For example, the following message would show the current state of the
system and return it to the requestor:
 
   DCL T.T
   $ ASSIGN/USER T.T SYS$OUTPUT
   $ SHOW SYSTEM
 
MAIL-SERVER automatically deletes  the  file specified on  the   `DCL'
command line (T.T in the example), but no others.  If you  do use this
command, please tidy up after  yourself!  (Remember: you'll be in  the
context of  a batch job,  so compilers will  generate listings, and so
on.)
 
Note:  DCL-serving  is  a  possible security hazard  and  many  system
managers and archive maintainers will, very sensibly, disable it.
 
                  IT IS NOT AVAILABLE ON THE TeXserver.
 
Specifying the Return Address
-----------------------------
 
If you wish to specify an alternate route by which mail messages shall
be returned to you, you may precede the TeXserver command with a line
of the form
 
   PATH return-address
 
(This is  the  only  instance in  which  the  server will  process two
commands:  PATH and the actual service requested.)
 
One reason  why you might wish to use this  format is to avoid a route
which  goes through a  mailer relay such as UK.AC.EARN-RELAY, which is
notorious for  corrupting  mail.   (It does this not just because it's
bloody-minded, but because it converts the incoming ASCII message into
EBCDIC for processing by an IBM machine,  and then converts back using
a table  which  is  not symmetrical:  the commonest  corruption is  to
change  circumflex accents  (^:\hat)  into tildes  (~:\tilde),  whilst
tilde is  changed  into  per-cent (\%).   Since  real  percents remain
unchanged,  unravelling TeX  source  with these  corruptions is a non-
trivial task!
 
The syntax used for network addresses is the one  used throughout most
of the  networking  community,  `user@site'.  For example,   for JANET
users, requests from `orinoco' at site `uk.ac.wimbledon.common' should
have a return address of
 
                    orinoco@uk.ac.wimbledon.common
 
Note that the VMS mailer folds the return address to UPPER case.
 
For BITNET users, you need to send the mail out via the EARN gateway:
 
                 user%machine.site.BITNET@EARN-RELAY
 
Note that the order  of specifying domains *is* important  to the EARN
mailer.  The syntax is similar  for other networks  accessed  via  the
EARN  gateway.
 
Requests from  North America  (e.g.,  those with  .EDU addresses), and
other sites on the Internet,  may also use the EARN gateway:  however,
mail is  less likely to be corrupted  if sent via  UK.AC.NSFNET-RELAY.
Bitnet sites in North America could therefore route their  traffic via
NSFNET-RELAY and EDU.CUNY.CUNYVM.
 
                   user%machine.site.EDU@NSFNET-RELAY
or
              user%site.bitnet%cunyvm.cuny.edu@NSFNET-RELAY
 
N.B.  Aston only understands addresses on the Janet network: it has no
concept  of domain routing,  so cannot know  that <fred@node.site.edu>
needs to be routed to <fred%node.site.edu@uk.ac.nsfnet-relay>.  Please
remember this when specifying an explicit path.
 
Other relays are UK.AC.EAN-RELAY, UK.AC.MHS-RELAY and UK.AC.SPAN-RELAY
Sites using these relays will probably be aware of it!
 
From  the  UK,  traffic  to the  UUCP  domain  is normally  routed via
UK.AC.UKC (Univeristy of Kent at Canterbury).
 
Other users should try NSFNET in the  first instance  (it seems to  be
pretty clever).  If that fails, consult  a local networking  guru.  If
that fails, mail the archive maintainer, who should be able to put you
in touch with someone who can help.  If all else fails, you're on your
own!
 
Sites on the  SPAN  network  (a global DECnet, with thousands of nodes
supposedly on-line together)  may send their  mail to  TeXserver via a
site known to  Janet as  UK.AC.SPAN-RELAY;  it is understood that this
site is known as  RLESIS  on  SPAN,  so such users  *could* send their
requests to:
                   RLESIS::"TeXserver@tex.ac.uk"
 
The corresponding return route that will be used by default is:
                  \dSITE::USER\d@UK.AC.SPAN-RELAY
(The `\d' sequences are a PMDF convention for the `"' character.)
 
However, SPAN-RELAY does not provide any store-and-forward capability,
so your site's machine *must* be accessible from RLESIS over SPAN when
the reply is sent by TeXserver;  this will be a few minutes after your
request arrives,  when the receipt is sent,  but could be  many  hours
later for the actual information requested.
 
It may seem strange,  but a more reliable routing is available through
North America,  thanks to the good offices of the Goddard Space Flight
Centre; mail should be sent from SPAN to:
 
                EAST::"TeXserver%Uk.Ac.TeX@nsf.ac.uk"
the corresponding return path is then
             USER%gov.nasa.dnet.SITE@Uk.Ac.NSFnet-Relay
 
 
Reference
---------
 
[1]  "A Technique for High-Performance Data Compression"
     Terry A. Welch
     IEEE Computer vol 17, no 6, pp8--19 (June 1984)
 
 
Backispiece
-----------
 
MAIL-SERVER was written  by  Adrian F.  Clark.  Any comments, queries,
suspected bugs, etc should  be addressed to  the   author, not  to the
maintainers of the archives  it serves.   (If  any  query doesn't  get
answered  within, say,  a week,  please re-submit  it;   the  author's
network connection is rather flaky!)  Note that the  author is *not* a
networking Wizard.
 
The front-end was written by Brian {Hamilton Kelly}, with assistance
from Niel Kempson.  These individuals, together with Adrian Clark and
many other volunteers, help Peter Abbott to maintain the contents of
the Aston Archive.
 
As usual with public-domain software, no commitment is given as to the
quality of this software: it may not do what this help says it does.
 
 
   Adrian F. Clark
   JANET:  alien@uk.ac.essex.ese
   ARPA:   alien%uk.ac.essex.ese@cs.ucl.ac.uk
   BITNET: alien%uk.ac.essex.ese@ac.uk
   Smail:  Dept. of Electronic Systems Engineering, Essex University,
           Wivenhoe Park, Colchester, Essex C04 3SQ, U. K.
   Phone:  (+44) 206-872432 (direct)
 
   Brian {Hamilton Kelly} & Niel Kempson
   JANET:     TeX@uk.ac.cranfield.rmcs
   BITNET:    TeX%uk.ac.cranfield.rmcs@ukacrl
   INTERNET:  TeX%uk.ac.cranfield.rmcs@nsfnet-relay.ac.uk
   UUCP:      {mcvax,ukc,uunet}!rmcs.cranfield.ac.uk!TeX
   Smail:     School of Electrical Engineering & Science, Royal Military
              College of Science, Shrivenham, SWINDON SN6 8LA, U.K.
   Phone:     Swindon (0793) 785252 (UK), +44-793-785252 (International)
 
 
Character Codes
---------------
 
To check if this file arrived without being mangled by assorted
character set conversions, here's a list of some boring ASCII
characters:
 
First, the uppercase alphabet: ABCDEFGHIJKLMNOPQRSTUVWXYZ
Now lower case: abcdefghijklmnopqrstuvwxyz
Digits zero to nine: 0123456789
Now punctuation:
! exclamation point
" double quotes
# hash mark (may be a pound sterling sign on some terminals/printers)
$ dollar sign
% percent sign
& ampersand
' right single quote
( left parenthesis
) right parenthesis
* asterisk
+ plus sign
, comma
- minus sign
. period
/ slash
: colon
; semicolon
< less-than sign (pointing to left)
= equal sign
> greater-than sign (pointing to right)
? question mark
@ at-sign
[ left square bracket
\ backslash
] right square bracket
^ caret or up-arrow
_ underscore
` left single quote
{ left curly bracket
| vertical bar
} right curly bracket
~ tilde
 
[End of the MAIL-SERVER help]
