COMSAT request-file protocol...

The following programs use this protocol:
	(Q)MAIL, BUG, MSG - regular mailing pgm & variants.
	MM Mail - EMACS library program for sending mail.
	Babyl	- Another EMACS library for mail.
	FTPS	- FTP server, for incoming net mail.
	DDT	- turns failing :SENDs into mail.
	INQUIR	- sends update requests to all UPDATE-INQUIR mailboxes.
	DRAGON	- asks people to print out the monthly ZUSRPT file
	PWORD	- and PANDA for accounts notification.
	NAME	- for crash reports.
	LGM	- CStacy and Duffey's Digest sending programs.
	APNYT	- redistributes newswires from SAIL.
	BDAY	- (DRAGON;DAILY BDAY) sends birthday greetings every midnight.
	*	- Any other programs using the protocol should
		be added here, in order to more easily update
		them when and if the protocol is changed or improved.

OVERVIEW
	Any program can send mail simply by writing a file in the
proper format to .MAIL.;MAIL >.  The comsat will detect this writing
by virtue of a special system word named NQMFWR that is incremented
whenever a file open for writing on .MAIL. is closed. The file will be
slurped up, and the necessary mailings or sendings carried out--
response will be nearly instantaneous if the comsat was idle to begin
with, but can be delayed for indefinite periods (1 or 2 minutes at
most, usually) if there is already a request being processed or mail
being unqueued.


GENERAL SYNTAX
	Such a file or request is composed of various ITEMS, each with
a name and value (another terminology is to say "attributes" instead
of "items").  Names should always start at the beginning of a line,
and must be composed of only letters, digits, and dashes; their values
are strings which can contain any characters.  Blank lines between
items are ignored.
	There are only two ways of specifying such items, which depend on the
fact that either a colon or a semi-colon will terminate a name:

[1] <name>:<string value><crlf>
	In this case, the use of ":" implies that the string comprising the
	value of <name> is everything after the ":", up to but not including
	the <crlf>.  The only forbidden character in a value of this type is
	<cr>, which terminates the string.  For example,
	FROM-PROGRAM:QMAIL<crlf>

[2] <name>;<char count><crlf>
<string value>
	This form is used when one desires to use <cr>'s in a string value,
	and is the most general.  The ";" indicates that the string up to the
	<crlf> is an number specifying the length, in chars, of the
	string value following the <crlf>.  This is most commonly used to
	specify message text.  For example, to specify "Hi<crlf>there<crlf>"
	(11. chars) one would say:
	TEXT;11.
	Hi
	there

	The character count, as well as any strings specified as being
numbers, can be either octal or decimal; a number with a trailing
decimal point is decimal (e.g. 11.), whereas one without is octal
(e.g. 13).
	There is also one special case of [2].  If the number
specified is "-1", it is taken to mean that everything following, up
to end-of-file, is the string value.  This is also mostly useful for
specifying message text when the exact length is unknown or too much
trouble to figure out beforehand; it does, however, require that the
item using this construction be the last one in the file.
	For most items, leading spaces are allowed and will be ignored
(but the character count after a semicolon must include them).
Exceptions are TEXT, FAKE-TO, and SUBJECT, which are taken verbatim.

MAIL ITEMS

	The following are the possible items which can be specified in
a request to the comsat.  In each case, the item name is followed by
a discussion of the specific syntax required and what the item does.

Some items are absolutely required; without them the COMSAT
will complain that the MAIL file is in error.  These items are:
	* One of AUTHOR or FROM.
	* One of RCPT or TO.
	* TEXT.
Some others are "mostly required", by which we mean that every
program is strongly encouraged to explicitly provide them, but the
COMSAT will default them anyway.  In order of importance, these are:
	* FROM-PROGRAM
	* FROM-XUNAME
	* FROM-UNAME

	The order in which the items appear is not significant to the mailer.
HOWEVER, for debugging purposes it is strongly recommended that 
the FROM-PROGRAM item be first in the file (so that if there is a format
error it will be possible to tell what program needs to be hacked), and
that the FROM-XUNAME be next (to create the highest probability that
the sender name is recoverable even if the file contains a format error,
so that the sender can be notified and can correct the problem).

	And now, the items themselves:

AUTHOR		<Rcpt spec of one of the authors>
	This is a recipient-type specification.  There should be one of
	these for each author of the message.  There MUST be at least
	one AUTHOR or COMSAT will complain.
	These people will be put in the FROM field in the header.
	NOTE: at the moment, only one AUTHOR is allowed, and it
	must be a simple string, as for FROM-UNAME.  In the future
	more than one will be allowed and full rcpt syntax will
	be parsed. {=> PARCSN A$CSN}

RCPT:		<Recipient spec>
	The construction of <rcpt spec> is exactly like that in the
	NAMES > database; this allows arbitrarily complex options to
	be given in a standardized format.  There must be at least one
	RCPT specification; any reasonable number may be given.

FROM-PROGRAM	(name of program writing this file)	[old FROM-JOB]
	This item is not required, but is strongly recommended as a
	debugging aid.  It is also recommended that this be the first item in
	the file (so that it is intact if there is an error later).

FROM-UNAME:	<UNAME of sender process>		[old SENT-BY]
	This is used for the SENDER (or SENT-BY) field in the header.
	It also provides the COMSAT with the name of the person to complain
	to if there is trouble sending the message.  If not present it
	defaults to the FROM-XUNAME; if both missing, defaults to
	the first AUTHOR. {=> PARSBY A$SNM}

FROM-XUNAME:	<XUNAME of sending process>
	This is not used now, but may be someday.  If not present,
	defaults to FROM-UNAME; if both missing, defaults to first
	AUTHOR.  {=> PARNIL}

CLAIMED-FROM: <uname>
 (OBSOLETE - do not use!)
 	This used to be specified only for two situations: first,
	when the user explicitly furnished a "claimed-from name".
	If not, then only if the sending process' XUNAME was different
	from the UNAME, whereupon the XUNAME would be specified by
	this item.  These are obsoleted by AUTHOR and FROM-XUNAME.
	{=> PARCSN A$CSN}

FROM:	[<option chars>"]<UNAME of sender process>
 (OBSOLETE - do not use!)  see AUTHOR, HEADER-FORCE, and REGISTERED.
	This is documented here for conversion purposes.  It
	will be flushed as soon as all programs are converted.
	Format is: [<chars>"]<name>
	If a quote-mark doesn't exist anywhere in the string,
	the whole string is taken to be the sender name.
	Otherwise, the chars preceding the quote-mark are interpreted as:
		N - requests NET-style header
		T - ditto
		I - requests ITS-style header
		R - requests no header (i.e. quote text).
		X - Send receipt only for failed messages.
		Q - Send receipt only for queued & failed messages.
			(default, if neither X nor Q, is to send
			 receipts for ALL (sent, queued, failed))
	(See HEADER-FORCE for default header).
	{=> PARSND A$SNM}

TO:	<host><mode-chars>"<rcpt spec>	see also RCPT
	This item is somewhat obsoleted by RCPT, but is still okay to
	use.  If the first non-blank character is a "(" then parsing is
	exactly as for RCPT.
	Otherwise, a host number is read (in octal, but decimal
	can be indicated by a decimal point after the last digit).
	If the string does not start with any digits, the local
	host is assumed.
	After the parsing or defaulting of the host number, the
	"mode characters" are read, up to a quote-mark; everything
	past the quote-mark is parsed as for RCPT.  The valid
	mode characters are:
		C - this rcpt is a "CC:" rather than a "To:".
			Same as (R-OPTION CC).
		B - this rcpt is a Blind CC: and isn't shown in the header.
			(NOT IMPLEMENTED by administrative fiat)
		S - Sets "send-mode" switch:
			-S send, don't mail if fails.
			 S send, mail if failed.
			+S send, and always mail too.
		M - Sets "mail-mode" switch:
			-M Mail, don't notify rcpt.
			 M Mail, notify if rcpt allows it.
			+M Mail, and always notify rcpt.
	Note that the mode switches can require that a "+" or "-"
	prefix the letter.  "S" determines whether message is
	to be sent, mailed, or both; absence implies mail only.
	QSEND uses simple "S" mode.
	"M" doesn't really do anything; someday it might.

HEADER-FORCE	<type>
	Forces header to style specified by <type>, as follows:
		ITS - ITS style header
		NET - NETwork style header
		RFC733 - special case of NET style.
		NULL - Quote message text; no header formation.
		*MSG - *MSG-style header (DISTRIB, EXPIRES, etc.)
	(The default header in absence of this item
	 is ITS for intra-ITS mail, NET otherwise.)

REGISTERED:	<character>
	Specifies that some confirmation message be returned to
	the sender.  The single <character> can be one of:
		N - Returns no receipts at all.
		F - returns "receipt" for failed mail only.
		A - returns receipt for all msgs when sent, queued, or failed.
	(The default is to return a receipt only for messages
	which are not successfully sent immediately; i.e. which
	are queued and sent, or which fail.)

NET-MAIL-FROM-HOST:	<host no.>
	This item should be used only by the FTP server unless
	special dispensation is granted.  No "FROM" or "SENT-BY" should be
	used.
	It has various special effects which vary with time.  Only the
	COMSAT source fully documents it.  For example, it used to
	quote the message text (no header generated), specify the network
	site sending the message, and generate an internal "FROM" name
	of NET-ORIGIN.  (THIS EXAMPLE IS NO LONGER TRUE)

FAKE-TO		<name to use in header>		[old RCPT-LIST-NAME]
	If specified, this item overrides use of the "TO"-specified
	names in the formation of message header.  There will be
	only a single "To:" line in the header, showing this item.
	However, CC's will still be listed.

SUBJECT		<subject line>
	If specified, a subject line will be created in the header,
	using <subject line>.

USER-HEADER	<line of text>
	If specified, the <line of text> will be placed in the header
	of the message, verbatim.  This allows a user program to get
	arbitrary lines into the header; for example, one might
	use this to put in a "Reply-To: FOO at MIT-MC" line.  There
	many be any number of these items, so you can put in more than
	one user-specified line.  The lines will appear in headers of
	all formats, including MSG and ITS headers as well as NET
	and RFC733 headers (but not null headers).

MSG-FN1		<first filename for .MSGS. message>
	This item is used when sending to a wild-card recipient name
	of the form "*FOO", which generally means a *MSG-type message.
	If given, it specifies the first filename to use when writing
	to the .MSGS. directory.  If unspecified, it defaults to "MSG->".

MSG-FN2		<second filename for *MSG>
	As above.  If not given, defaults to ">".

EXPIRES		<no. of days to expire in>
	Also for use by *MSG-type requests, this specifies how many
	days to let the message run before it is subject to
	automatic or manual deletion from the .MSGS. directory.
	Default if unspecified is 7 days.

TEXT		<text of message>
	Here is the actual nitty-gritty.  Always required; merely
	specifies the text of whatever you are going to all this
	trouble for.

ATTRIBUTE:	(<attrib-name> <attrib-val>)
	Allows arbitrary specification of message attributes.
	For use by COMSAT maintainers only!

		SAMPLE MESSAGE

	Suppose the MAIL program is invoked as follows by KLH0, on MIT-AI:

:MAIL RMS,MOON@MC There's a new feature in MAIL
called "FOO".^C

	The following will be written to .MAIL.;MAIL > :

FROM-PROGRAM:QMAIL
FROM-UNAME:KLH0
FROM-XUNAME:KLH
AUTHOR:KLH
RCPT:(MOON MC)
RCPT:(RMS)
TEXT;54
There's a new feature in MAIL
called "FOO".


-------------------------- OLD STUFF ----------------------

FROM-JOB	<actual JNAME of sender process>
	Now interpreted as FROM-PROGRAM.
RCPT-LIST-NAME -- same as FAKE-TO.

FROM -- Ugh!  old syntax as already described; however, the "sender name"
	furnished was interpreted as the UNAME of the sending process.
	Old desc:
	The sender name should preferably be a UNAME; if it isn't, or
	if it isn't the UNAME of the actual sending process, SENT-BY should
	be used also.  You would do better not to use this,
	instead use SENT-BY and/or CLAIMED-FROM.

SENT-BY -- now interpreted as FROM-UNAME {=> PARSBY A$SNM}.  Old desc:
	  val: <UNAME of sender process>
	This item is required only when FROM does not specify the
	right thing, i.e. the UNAME of the sender or sending process;
	this provides the satellite with the proper address for
	failure messages, as well as being stuck into the header
	when it is different from the FROM.  If using the new format,
	there is no FROM; CLAIMED-FROM is used instead.

CLAIMED-FROM -- same, old description furnished here:
	val: <UNAME of actual person sending>
	This item allows one to specify a "sender name" other than
	the UNAME of the job sending the message, and this
	is what will actually appear in the "From:" field of the
	message header.  It will still work if the name specified is
	not a real UNAME, but in that case confirmation and notification
	of errors cannot be done.
	You don't have to give both SENT-BY and CLAIMED-FROM if they are
	the same.

		--------------------
		OLD SAMPLE MESSAGE

For the same example given with "new" format, old format was:

FROM-JOB:MAIL
FROM:KLH
SENT-BY:KLH0
RCPT:(MOON MC)
RCPT:(RMS)
TEXT;54
There's a new feature in MAIL
called "FOO".