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@.) 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 . 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 needs to be routed to . 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]