.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 ( (EQV-LIST ...)) 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 * ( (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 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: ( <#1> ... ) or @ Where: - Recipient type, such as NAME, FILE, RUN, BUG. If is not a recognized type, it is interpreted as being the , of type NAME. - Recipient name string, such as KLH, INFO-ITS, [SYS;TS FOO]. - Attributes, each of which is parsed as: (ATTR AVAL) Where ATTR - Attribute name. AVAL - Attribute value. If 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 . Other special notes: If 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 ... ) 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 ) Where = {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 ) If mailing the message, this attribute governs how message notifications are done. Positive : Always notify regardless of other options. Zero : Notify only as per other options. Negative : 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 ) 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 : Always mail message as well. Zero : Mail only if the :SEND fails. Negative : 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 is treated as a , 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,,] 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 ) 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 ( )) 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 ) 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.