PDP-10.its/doc/_mail_/names.info

.MAIL.; NAMES > is a list of mailbox equivalences.  Each machine has
its own distinct copy for addresses at that machine; do not copy the
file to other machines!

Here's basic documentation of the standard cases.  What follows is
more detailed documentation of hairy cases.  That documentation is now
pretty badly out of date; don't believe everything it says.  If you
want to do something hairy, try and find an instance of someone else
doing it in the NAMES file and imitate it.  For help, send mail to
BUG-MAIL. 

The file defines a set of mailing lists.  List specifications are
Lispy; they look like

(<name-of-list> (EQV-LIST <recipient1> <recipient2> ...))

Recipients can be of the following forms:

* KLH -- mails to KLH on the local machine
* KLH@MC -- sends the mail on to MC, telling MC that the mail is for KLH
* (<recipient> (R-OPTION FOO)) -- modifies the way the mail is delivered
* [FOO;BAR BAZ] -- delivers the mail into the specified file on the
		   local machine.  DO NOT put devices (such as AI:)
		   in the file name!  It will seem to work but really
		   break things.
* (FILE [FOO;BAR BAZ]@MC) -- delivers the mail to the specified
			      file on another machine.
* (@FILE [FOO;BAR BAZ]) -- indirects through the specified file, which
			   should contain a list of recipients.

The <recipients> list can be continued onto a continuation line (as
in 

(FOO (EQV-LIST SOMEONE SOMEONE-ELSE
	       ANOTHER-PERSON))

), but the continuation lines MUST start with a space or tab.  Ideally
they should be Lisp ground.

Make sure you balance parentheses correctly.

Comments start with a semicolon.

Alphabetical order is not crucial, but improves readability within
groupings.

For pathological names, "/" or "^Q" will quote characters such as
spaces, parentheses, brackets, etc.


GENERAL RECIPIENT SYNTAX

	Each list in the NAMES > file is really just a
recipient specification, in a structured format which is
almost always the same anywhere one may wish to specify
a "recipient".  

A recipient spec or RSPEC in standard form is:

	(<rtyp> <rnam> <#1> <attr>  <attr>  ... <attr> )
    
or 

        <recipient>@<host>

Where:
 <rtyp> - Recipient type, such as NAME, FILE, RUN, BUG.
	If <rtyp> is not a recognized type, it is interpreted
	as being the <rnam>, of type NAME.

 <rnam> - Recipient name string, such as KLH, INFO-ITS, [SYS;TS FOO].

 <attr> - Attributes, each of which is parsed as:
	(ATTR AVAL)
	 Where	ATTR - Attribute name.
		AVAL - Attribute value.
	If <attr> is an atom rather than a list, it is read as
	(ATTR).  I.e. it exists but has no value.
 <#1>  -   Also an Attribute, but interpreted crockishly.
	If a list, it is a normal Attribute.
	If an atom,
	  1) If "@" is the first character, interpretation is (SITE X)
	  2) If a number or site name, interpretation is as above.
	  3) Else as for atomic <attr>.

	Other special notes: If <rnam> contains a @ and the text
after it is a valid host name, it is interpreted as having the
syntax Foo@Site.  It is possible to have multiple site definitions
just as it is possible to multiply define anything; the effects
of this are QUITE undefined and which one gets priority depends
on where it actually hangs in the internal core list storage.

	Equivalence entries are just like rcpt specs,
except that they can have the attribute (EQV-LIST <Rspec> ... <Rspec>)
which implies that when mail arrives for the recipient name,
it will be sent instead to the recipients on the EQV-LIST.
Thus, (KLH (EQV-LIST KLH@MC)) in the NAMES > file will
cause any mail arriving for KLH to be "forwarded" to KLH@MC.

For the case where you want to specify an EQV-LIST, but
still want the original recipient to receive a copy, hearken
to the following example:
	(KLH (R-OPTION FOO) (EQV-LIST KLH KLH@OTHERSITE))
Simply including the name itself as part of the EQV-LIST causes
a circularity which is detected and handled properly.  This also
demonstrates the setting of an R-OPTION for the original name.

MINOR RECIPIENT OPTIONS - "R-OPTION"

	There are several options, switches, and attributes
which a recipient might wish to set in NAMES >.  The bulk of these are
specified as R-OPTION arguments, and are listed here in alphabetical order:

(R-OPTION APPEND)
	This is a very useful option which specifies that
	all of your mail be APPENDED onto the bottom of your mail
	file, rather than being "pushed" on the top in reverse
	chronological order.

(R-OPTION FAST-APPEND)
	This is similar in effect to APPEND, but uses a special
	mode for output which is MUCH more efficient than APPEND.
	This is a new feature and is not yet recommended for use with
	regular personal MAIL files, which should be fairly small anyway.
	However, large script files should definitely try this out.
	Read MC:KSC;?APPND > before using it.

(R-OPTION CC)
	This option causes its recipient to be listed in message headers
	as a "CC:" or "Carbon-Copy:" recipient, rather than "To:".

(R-OPTION INFINITE-CLI)
	Message notifications ("You have mail...") will include the
	complete message.  See SMALL-CLI and NO-LOCAL-CLI.

(R-OPTION NEW-FILE)
	This option causes the message to always be written into
	a "new" file by itself.  That is, if a file already exists
	with the same name, it is flushed; the message is not added
	to it, but rather replaces it.  For FN2's of "<" or ">",
	the NEW-FILE option is assumed; however, due to the fact that
	writing with these filenames creates a new, unique filename,
	no existing file is replaced (flushed) by the write operation.

(R-OPTION NO-CLI)
	This option suppresses all message notification; the recipient
	will never be notified of arriving mail.  See SMALL-CLI,
	NO-LOCAL-CLI, and INFINITE-CLI for graduated control.

(R-OPTION NO-LOCAL-CLI)
	This option suppresses message notification if the message
	originated locally; thus the only notifications which are
	sent are those pertaining to incoming network mail.

(R-OPTION NOQC)
	This specifies that you don't want to be notified either
	of messages which were queued, or which were queued and finally
	were sent.  It doesn't suppress actual error messages if something
	goes wrong.

(R-OPTION NOSHOW)
	This option prevents the recipient name, and anything it
	expands to, from ever appearing in any header.  It is really
	an internal option; to get the effect of a BCC, use (R-OPTION BCC).

(R-OPTION NOTDIST)
	This only applies when one or more of the recipients for the
	message is of type *MSG.  All recipients without a NOTDIST
	option will be included in the special DISTRIB: header line
	given to the *MSG recipient.  (which is normally a file on
	.MSGS.;)

(R-OPTION SHOWLIST)
	This is used for EQV lists where one wants the
	list itself seen in the message header, rather than the
	name of the list itself, as would normally be the case.
	If the list name itself wasn't going to be in the header
	anyway, the list won't appear no matter what.

(R-OPTION SMALL-CLI)
	With this option, message notifications will be limited
	to 2 lines, the first announcing "You have mail..." and
	the second stating the message length.

(R-OPTION SUPER-QUOTE)
	Normally, when a message is written, a header is added to
	the text and ^_'s (cntrl-underbar, 037 octal) are converted
	to a up-arrow, underbar (2 char) representation, with a true
	^_ added to the end of the message.  This option suppresses
	all that; no header is added, no checking is done for ^_'s,
	and no ^_ is added at the end.  Otherwise, writing is as
	for any other message, obeying the APPEND, NEW-FILE options, etc.

RECIPIENT ATTRIBUTES WHICH AREN'T "R-OPTION"

The following are also per recipient, but are attributes in themselves
rather than being R-OPTION values.

(R-HEADER-FORCE <arg>)	 Where <arg> = {NET, ITS, NULL}
	This will try to have all your mail delivered to you
	using the header format specified.  NET indicates standard
	network header, ITS the compact style we all know well, and
	NULL prevents any header from appearing (possibly useful when
	mailing cruft to a file or program - see (R-OPTION SUPER-QUOTE).)
	NOTE: This doesn't yet work for incoming net mail, but will as
	soon as the code for parsing same gets written.  This may not
	be for a long time, owing to the incredible variety of header
	formats used by different sites.

(R-MODE-MAIL <num>)
	If mailing the message, this attribute governs how message
	notifications are done.
	Positive <num>: Always notify regardless of other options.
		Zero  : Notify only as per other options.
	Negative <num>: Never notify regardless of other options.
	NOTE - whether the message is actually mailed or not
	can depend on the R-MODE-SEND attribute)

(R-MODE-SEND <num>)
	First, the existence of this attribute indicates the message
	as a whole should be CLI'd to the recipient; that is, :SENT.
	The numerical argument specifies 3 additional options:
	Positive <num>: Always mail message as well.
		Zero  : Mail only if the :SEND fails.
	Negative <num>: Don't mail at all.


RECIPIENT TYPES

	The TYPE attribute determines the interpretation of the
recipient name string, and can at present be any of the following:
NAME  - Normal, the string is simply a recipient name, like "FOO".
	This type is the default, but can be specified explicitly
	just like any other.
FILE  - The string is a filespec and the mail should be stored
	in that file (appending or pushing as the case may be).
	enclosing the string in square or curly brackets is a
	shorthand way of doing this.  Do NOT use host devices such as 
        such as ML:, MC:, etc.; it will break things.
        Use (FILE [FOO;FILE NAME] @MC) instead.
*MSG  - The string is an announcement-group name.  Recipients of
	this type will be given a special header and always written
	to .MSGS. using the MSG-FN1 and MSG-FN2 attribs if given.
PGM   - The string is a filespec of a program which should be started
	and run, with the message text as JCL.  See separate section
	about "PGM" recipients.
@FILE - The string is a filespec to a file which is "indirected"
	through; it should contain a list of recipient specs in
	the same format as described here, separated by commas
	or CRLF's.  It acts like EQV-LIST, except that its arguments
	live in a file and are dynamically read for each message.


MORE ABOUT THE "PGM" RECIPIENT TYPE

		 Sending to a Program

	When mail arrives for a recipient of type PGM, its <name>
is treated as a <filename>, and the specified file thereupon
loaded and started as an inferior job of the Comsat.  The message
text will be passed on as JCL for the program, and any errors
can be reported to the appropriate person.
	The default action, in the absence of specific directives,
is to let the job run for either 2 seconds run time or 1 minute
real time, whichever comes first, and then disown it.  Hence,
the JCL must be read within a reasonable time after startup.

In more detail:
	The default device for loading the file is always DSK: since
the LOAD symbolic system call will not work otherwise.  If
message text was present, the Comsat will set the OPTCMD bit in
the job's .OPTION variable, saying "I have JCL for you".
The job's XUNAME is also set to the name of the message sender, if
known.
Requests to read and write (clear) the JCL will be honored
in the same fashion as DDT;  that is, the usual .BREAK 12,[5,,<loc>]
must be used.  During execution, all fatal conditions except
.BREAK's to hack the JCL are handled by killing the inferior.
Unless stopped by a .BREAK 16, - the usual way for programs to
request DDT to kill them - an error message will be sent to
the program's maintainer, detailing the nature of the lossage.
In particular, things like .VALUE [ASCIZ /:KILL/] should
be avoided, as well as any .VALUE which is not intended to signify
an error.  In general, it is a good idea to try .LOGOUT before
the .BREAK 16, in case the job was disowned before it decides
to kill itself.
	The special attributes for handling PGM recipients are

(R-PGM-MNTNR <rcpt>)
	This specifies where error messages pertaining to job
execution should be sent.  If none is specified none is sent,
other than a standard copy to COMSAT-WIZARD.
	
(R-PGM-USET (<Value - sym to set>  <Value>))
	This (there may be any number) attribute allows arbitrary
user variables to be set before it is started.  Unfortunately
until symbolic .USET arrives, the first value must be the numerical
value of the symbol to write the second value into.  (Reading is
a useless operation in this context and is not attempted).

For example:
(PGM [FOO;HACK BIN] (R-PGM-MNTNR KLH) (R-PGM-USET (400074 465757000000)))
	Will run the program HACK BIN from FOO; and before
starting will set the XUNAME (see what DDT gives you when you
type something like .SXUNAME= at it) to the given value, which happens
to be FOO in left-justified sixbit.

(R-PGM-DISOWN <num>)
	As previously said, Comsat will stick to the job, serving
any JCL requests and handling interrupts, until either it has used
2 sec of run time or 1 minute of real time.  These actions can
be modified with the R-PGM-DISOWN attribute, as follows:

		RH -  corresponds to the ctl bits for the DISOWN
symbolic call, which will be used when and if the job is disowned.
These bits are all passed on directly, with the following
special actions:

Bit 1.4 is ALWAYS complemented - i.e. you must specify it to avoid the
	"default" of setting BUMRTL (system guns job if it does
	nothing for 1/2 hr)
Bit 1.3 will cause immediate disowning.  Obviously no JCL can be
	supplied for this case, and the LH bits are ignored.

		LH - bits specify mailer actions.
Bit 3.1 Says job never wants JCL.  This allows the mailer to proceed
	asynchronously, handling interrupts as they occur.
Bit 3.2 Says job will want JCL again even after it manages to read
	it all successfully.  This forces mailer to "stick with" job
	until it gets disowned.
Bit 3.3 Says if disowning is attempted, job should instead be KILLED
	and an error reported.  
Bit 3.4 Says that bits 4.9-4.1 contain the # secs of runtime job should
	be allowed - real time is ignored.  Dangerous!!
Bit 3.5 Says job should not be run if another already exists with
	identical UNAME/JNAME.  Note that this is checked BEFORE any
	USET's are done (so setting JNAME that way will lose).  JNAME is
	FN1 unless that is "TS", in which case it's the FN2.