\begindata{text,538945396}
\textdsversion{12}
\template{default}
\define{global
}
\define{footnote

attr:[Flags OverBar Int Set]
attr:[FontSize PreviousFontSize Point -2]}
\majorheading{Overview of the Andrew Message System Database

}
\chapter{Introduction}

The Andrew Message System (AMS) is a collection of interfaces to the AMS 
``Message Server,'' another program whose purpose is to interact with a large 
and diverse database.  The elements of this database are implemented as normal 
Unix\footnote{\
\begindata{fnote,539314696}
\textdsversion{12}
Unix is a trademark of AT&T Bell Laboratories.\
\enddata{fnote,539314696}
\view{fnotev,539314696,1455,0,0}} files and directories, but there are several 
classes of these files and directories, each of which has a purpose and 
content specialized for use by and for the Message Server.  This document 
describes all classes of files and directories created by and/or for the 
Andrew Message System.


\begindata{bp,539644360}
\enddata{bp,539644360}
\view{bpv,539644360,1456,0,0}
\chapter{Terminology}

This chapter introduces several phrases and terms necessary to understanding 
the functions of the diverse parts of the AMS database.


\leftindent{\bold{Body}	The portion of a \italic{message} which follows the 
\italic{header} region and which may contain arbitrary text.  See ``Header''.


\bold{Address}	The destination of a \italic{message}.  One or more destination 
addresses are specified by the sender of a message, indicating who the 
recipients are to be.  In the Andrew Message System, the concept of an address 
is often broken down into the following two domains:

\leftindent{\description{\bold{Display Address}	This is the address that is 
``advertised'' for a given destination; i.e., the address that users are told 
to specify in their outgoing messages.  The display address may or may not 
uniquely identify the recipient to the delivery system; however, 
\italic{validation} can convert a display address into a \italic{submission 
address}.

\bold{Submission Address}	This is the address that is actually used by the 
delivery system to route the message to the correct recipient(s).

}}Display addresses are designed to be easily remembered; for instance, to 
send a message to ``andrew.ms'' (which is the name of a local public folder at 
Carnegie Mellon), the sender need only place ``andrew.ms'' in the ``To'' field 
of an outgoing message.  The sender need not be aware that validation converts 
``andrew.ms'' to the more meaningful submission address 
``+dist+/afs/andrew.cmu.edu/usr0/postman/DistLists/AMS-users.dl@andrew.cmu.edu.\
''


\bold{Caption}	A brief, one-line summary of a \italic{message}, usually 
containing the sending date, a portion of the Subject \italic{header}, the 
name of the sender, and the length of the message in bytes.  AMS interfaces 
typically display some of the message captions in whichever \italic{folder} 
the user happens to be reading; the user then chooses which full messages to 
read based on the captions.


\bold{Display Address}	See ``Address.''


\bold{FLAMES}	The Filtering Language for the Andrew MEssage System.  This 
programming language, based on Lisp, can be used to write programs that 
control the disposition of incoming \italic{message}s during \italic{mailbox 
processing}.


\bold{Folder}	A sequenced collection of \italic{message}s.  A folder is used 
to represent a user's mail, a bulletin board, a USENET newsgroup, etc.  A 
folder is the unit of \italic{subscription}; i.e., a user may subscribe to a 
folder, after which he or she will normally be shown the new messages as they 
arrive in that folder.  Each folder is implemented as a Unix directory with 
some special attributes:  it must contain a special index file; it must reside 
somewhere beneath a \italic{folder root}; and it may contain zero, one or more 
message files and/or \italic{subfolder}s.


\bold{Folder Root}	Any directory whose name begins with the string 
``.MESSAGES''.  A folder root is not a \italic{folder}, but directories and 
subdirectories beneath it may be folders.  If a directory is not somewhere 
beneath a folder root, then it is not a folder.


\bold{Header}	One of several information lines that are normally found at the 
beginning of a \italic{message}.  A message is divided into two parts:  the 
header region and the \italic{body} 
region\footnote{\
\begindata{fnote,539484168}
\textdsversion{12}
Refer to Internet RFC 822 for a detailed description of the format of network 
mail messages.\
\enddata{fnote,539484168}
\view{fnotev,539484168,1457,0,0}}.  Each header has a name, such as 
``Subject,'' ``Date'' or ``From.''  The name is terminated by a colon (:), 
followed by the content of the header.  Headers typically identify the sender 
of a message, the date it was sent, the subject of the message, the intended 
recipients, the route taken by the message to reach its current location, etc. 
 The end of the header region (and the beginning of the body region) is 
demarked by the first empty line encountered.


\bold{Mailbox}	A repository for incoming \italic{message}s.  All messages 
arriving at a given destination are immediately placed in that destination's 
Mailbox.  These messages may then be filed into one or more \italic{folder}s, 
possibly via a \italic{FLAMES} program.  Once in folders, messages may be read 
normally.  A Mailbox is simply a Unix directory.


\bold{Mailbox Processing}	The process of removing \italic{message}s from a 
\italic{mailbox} and (usually) placing them into \italic{folder}s.  Messages 
must be in folders in order to be read with any AMS interface.  Mailbox 
processing can be controlled with a \italic{FLAMES} program.


\bold{Message}	An individual piece of mail, or a bulletin board post.  Each 
message is stored individually in its own Unix file.


\bold{Postmaster}	A specially designated user of the system.  The postmaster 
is typically responsible for maintaining public \italic{folder}s, delivering 
\italic{message}s, and various other tasks.  The postmaster is highly 
priveleged with respect to the AMS Database.


\bold{Subfolder}	A subdirectory of a \italic{folder}.  Any directories 
appearing inside of folders are themselves folders (as long as they meet the 
necessary conditions for ``folderness'').


\bold{Submission Address}	See ``Address.''


\bold{Subscription}	An indication to the Andrew Message System that the user 
wishes to read the \italic{message}s in a given \italic{folder}.  When a user 
subscribes to a folder, he or she will then normally be informed by AMS 
programs when new messages arrive in that folder.  A user may have any number 
of folder subscriptions.


\bold{Validation}	That phase of \italic{message}-sending wherein 
user-specified destination \italic{address}es are disambiguated and/or 
corrected.  For instance, if a user addresses a piece of mail to ``John 
Smith,'' and there are three John Smiths known to the AMS, then the user will 
be prompted with a menu of different John Smiths, and may choose from among 
the three unique \italic{user-id}s.  Alternatively, validation may convert a 
\italic{display address} to a \italic{submission address}.

}
\begindata{bp,538269640}
\enddata{bp,538269640}
\view{bpv,538269640,1458,0,0}
\chapter{Mail}


\section{Introduction}

A major use of the Andrew Message System is electronic mail; i.e., the sending 
of messages among individual users.  This chapter describes the portions of 
the AMS Database used for the purposes of personal mail.


\section{Essential Files and Directories}


\subsection{Directories}


\paragraph{$HOME/Mailbox}

This directory is the repository for incoming mail.  The Andrew Message 
Delivery System places messages destined for a particular user into that 
user's Mailbox directory, each message in a separate and uniquely-named file. 
 These messages then await mailbox processing, at which time they may be 
placed into folders, re-sent to other destinations, etc.  By default, mailbox 
processing places all messages in Mailbox into the user's ``mail'' folder.


The permissions on $HOME/Mailbox should be set so that anyone may insert or 
lock files and do directory lookups; the owner should be able to read, insert, 
lock, lookup and delete files from $HOME/Mailbox.


\paragraph{$HOME/.Outgoing}

This directory is the repository for outgoing mail.  When a user composes a 
message and then submits it for delivery, it is placed in a file in this 
directory.  The message will then shortly be delivered by the Andrew Message 
Delivery System.


The permissions on $HOME/.Outgoing should be set so that the owner may read, 
insert, delete, list and lock files; the Postmaster should have the same 
rights.


\paragraph{$HOME/.MESSAGES}

This is the user's default folder root.


The permissions on $HOME/.MESSAGES should be set so that the owner has 
complete access.  No other users should have rights to this directory.


\paragraph{$HOME/.MESSAGES/mail}

This is the user's default folder.  If the user does not have a FLAMES 
program, then messages in that user's mailbox will automatically be placed in 
this folder during mailbox processing (i.e., when the user ``Checks new 
mail.'')


The permissions on $HOME/.MESSAGES/mail should be set so that the owner has 
complete access.  No other users should have rights to this directory.


\subsection{Files}


\paragraph{$HOME/.AMS.prof}

This file contains information about the user's subscriptions.  It consists 
primarily of lines of the form


\leftindent{<folder name> <full pathname> <subscription type> <time>

}
It records the time of the last message read by the user in a given folder. 
 When the user returns to the folder, any messages that have appeared since 
this recorded date will be displayed as ``new.''  This file is created and 
maintained automatically by AMS interfaces.  More about this file will be 
mentioned in the section concerning subscriptions.


\paragraph{$HOME/.MESSAGES/mail/.MS_MsgDir}

This is a special index which appears in all folders.  It is a non-ASCII file 
containing a header followed by entries referring to every message in the 
folder.  Each record contains the message caption, the associated file name, 
the date of the message, and the attributes of the message (such as ``deleted 
but not purged'').  When a folder is created or deleted, or when a message is 
added to or deleted from a folder, the .MS_MsgDir is updated accordingly 
(assuming that these operations are performed from within AMS interfaces).


The permissions on $HOME/.MESSAGES/mail/.MS_MsgDir should be set so that the 
owner has complete access.  No other users should have rights to this 
directory.


\paragraph{$HOME/.MESSAGES/.SubscriptionMap}

This is a special index which appears in all folder roots.  For every folder 
which is a subdirectory (or sub-subdirectory, etc.) of $HOME/.MESSAGES, this 
file contains a line mapping the folder's ``nickname'' to its full path.  For 
instance, Bob Glickstein's (user id ``bobg,'' home directory 
/afs/andrew.cmu.edu/usr12/bobg) .SubscriptionMap contains the following lines 
(among others):


\leftindent{folders.personal:/afs/andrew.cmu.edu/usr12/bobg/.MESSAGES/folders/p\
ersonal

folders:/afs/andrew.cmu.edu/usr12/bobg/.MESSAGES/folders

mail:/afs/andrew.cmu.edu/usr12/bobg/.MESSAGES/mail

}
The .SubscriptionMap file is the device that allows users to specify nicknames 
such as ``mail'' when referring to folders, rather than having to specify 
entire pathnames.  This file is created and maintained automatically when 
folders are created, deleted or renamed with AMS interfaces.


The permissions on $HOME/.MESSAGES/.SubscriptionMap should be set so that the 
owner has complete access.  No other users should have rights to this 
directory.


\section{Optional Files and Directories}


\subsection{Files}


\paragraph{$HOME/.AMS.flames}

This is the default location for the user's FLAMES program.  FLAMES programs 
are used to override the default mailbox processing (removing messages from 
$HOME/Mailbox and placing them in $HOME/.MESSAGES/mail).  A FLAMES program 
acts on individual messages as they are read from the user's Mailbox.  Refer 
to the documentation on FLAMES programming for more information.


\paragraph{$HOME/.AMS_aliases}

This file allows a user to create nicknames for commonly-used mail addresses. 
 It consists of a sequence of lines of the form


\leftindent{alias	full-address

}
This file may also contain directives controlling whether certain recipients 
should always or never receive ATK-formatted messages; these lines have the 
form


\leftindent{$forceformat	full-address

}
Note that $forceformat is only one of the possible directives.  Refer to the 
documentation on AMS aliases for more information.


\paragraph{$HOME/AMS_NO_MAILBOX_SORTING}

This is a zero-length file which, if it exists, will cause AMS to ignore the 
chronological ordering of the files in $HOME/Mailbox during mailbox 
processing.  Normally (i.e., when this file does not exist), mailbox files are 
processed in chronological order.


\begindata{bp,538930120}
\enddata{bp,538930120}
\view{bpv,538930120,1459,0,0}
\chapter{Folders}


\section{Introduction}

A folder is an AMS object which contains a sequence of messages.  Folders are 
used to represent bulletin boards, private mail, USENET newsgroups and so on.


A user's private mail folder is only a specialized case of the more general 
concept of a folder.  All folders, however, must be owned by some user; in the 
case of public folders (bulletin boards), the owner is usually a 
pseudo-account with a name such as ``bb.''  In this chapter, ``~bb'' will be 
used to signify the home directory of such an account.


\section{Essential Files and Directories}


\subsection{Directories}


\paragraph{~bb/Mailbox}

This mailbox is used to receive all messages destined for any of the folders 
in bb's tree.  The particular folder is often identified with a special 
construct in the ``To:'' header of the message, as follows:  in order for 
users to be able to send messages to bb's mailbox, the recipient of the 
message must be identified as ``bb.''  However, each message is likely to be 
destined for a different folder.  Although many potential mechanisms for 
differentiating between destinations exist, the most commonly-user one is to 
identify the nickname of the folder in a string following the user-id (``bb'') 
and a plus-sign (``+''), and preceding the hostname in the destination 
address.  In short, a ``To'' header of the following form:


\leftindent{To: bb+foo.bar@andrew.cmu.edu}


would indicate a message that is to be sent to the mailbox of user bb at host 
andrew.cmu.edu, and which is to be placed in bb's ``foo.bar'' folder during 
mailbox processing.  The FLAMES program in ~bb/.AMS.flames is used to 
interpret the folder-identifying string in the header.  (N.B.: Users are 
ordinarily not required to send messages explicitly to addresses such as 
``bb+foo.bar@andrew.cmu.edu''; if bb's folder tree is properly set up, and the 
sender's ``mspath'' is also properly set up, then validation will convert the 
display address ``foo.bar'' into the submission address 
``bb+foo.bar@andrew.cmu.edu.''  Refer to the chapter in Validation for more 
information.)


\paragraph{~bb/.MESSAGES}


\paragraph{~bb/.MESSAGES/\bold{folder}}


\subsection{Files}


\paragraph{~bb/.MESSAGES/\bold{folder}/.MS_MsgDir}


\paragraph{~bb/.MESSAGES/.SubscriptionMap}


\paragraph{~bb/.AMS.flames}


\section{Optional Files and Directories}


\section{Private Folders}


\section{Semi-private Folders}


\section{Public Folders}


\begindata{bp,539690184}
\enddata{bp,539690184}
\view{bpv,539690184,1460,0,0}
\chapter{Subscriptions}


\section{Introduction}


\section{Essential Files and Directories}


\section{Optional Files and Directories}


\begindata{bp,539671752}
\enddata{bp,539671752}
\view{bpv,539671752,1461,0,0}
\chapter{Validation}


\section{Introduction}


\section{Essential Files and Directories}


\section{Optional Files and Directories}


\begindata{bp,539671048}
\enddata{bp,539671048}
\view{bpv,539671048,1462,0,0}
\chapter{Administration}


\section{Introduction}


\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,1464,0,0}
Copyright 1992 Carnegie Mellon University and IBM.  All rights reserved.

\smaller{\smaller{$Disclaimer: 

Permission to use, copy, modify, and distribute this software and its 

documentation for any purpose is hereby granted without fee, 

provided that the above copyright notice appear in all copies and that 

both that copyright notice, this permission notice, and the following 

disclaimer appear in supporting documentation, and that the names of 

IBM, Carnegie Mellon University, and other copyright holders, not be 

used in advertising or publicity pertaining to distribution of the software 

without specific, written prior permission.



IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS 

DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT 

SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER 

BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY 

DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 

WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 

ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 

OF THIS SOFTWARE.

 $

}}\enddata{text,538945396}
