


1 DELIVER
H DELIVER is an adjunct  to  VMS  MAIL  which  makes  it  possible  for
H incoming  mail  messages  to  be  handled and processed automatically
H based on information provided in  a  user-supplied  file.   Different
H actions  can  be  taken  based  on  a  message's  address, subject or
H contents.  These actions include delivering the  message,  forwarding
H the  message  or  even  invoking a DCL command script to perform some
H complex operation.  Any actions taken occur immediately upon  receipt
H of  the  message;  the  user  does  not need to log in for DELIVER to
 operate.

H DELIVER is modelled after the MAILDELIVERY facility of the MMDF  mail
H system.   DELIVER  is, however, completely distinct from MMDF and the
H formats of .MAILDELIVERY files for MMDF and MAIL.DELIVERY  files  for
 DELIVER are dissimiliar.

H This document assumes that the reader is familiar with the  VMS  MAIL
 facility.
	2 Setup
H Users can set up DELIVER to handle their incoming mail by doing  just
 two things:

H(a)  Create a MAIL.DELIVERY file in their  accounts'  initial  default
H     directory  (SYS$LOGIN).   For  security reasons this file MUST be
H     located in the initial default directory -- it cannot  be  stored
H     anyplace  else.   The format of a MAIL.DELIVERY file is described

     below.

H(b)  Set  their  mail  forwarding   address   for   the   account   to
H     "DELIVER%user",  where "user" is the username associated with the
H     user's account.  The MAIL command to change or set  a  forwarding
H     address  is  SET  FORWARD.   Specifying  another  user's  name in
H     conjunction with "DELIVER%" will perform no  useful  function  --
H     mail  will  simply  be  forwarded  and  handled  by  that  user's
/     MAIL.DELIVERY file, assuming one exists.

H Once these two  steps  have  been  taken,  DELIVER  will  be  invoked
H automatically  to  handle  all mail as it is delivered.  For example,
H suppose user BOB wants to tell DELIVER to handle  incoming  messages.
8 BOB should create a MAIL.DELIVERY file and then type:


     $ MAIL
$     MAIL> SET FORWARD DELIVER%BOB
     MAIL>

2 Format
H The MAIL.DELIVERY file controls DELIVER and tells it  how  to  handle
H each   message.   A  MAIL.DELIVERY  file  consists  of  a  series  of
H directives with one  directive  on  each  line  of  the  file.   Each
H directive  specifies  how a certain kind of message is to be handled.
H A particular directive may or may not apply to a given  message.   An
H attempt is made to apply every directive in the MAIL.DELIVERY file to
H each message, thus more than one directive may  apply  to  (and  more
: than one action may be the result of) a single message.

H Any line in the file which begins with a semicolon or an  exclamation
6 point is considered to be a comment and is ignored.

H A directive line consists of the following items in order  from  left
 to right:

F     <from-pat> <to-pat> <subject-pat> <accept> <action> <parameter>

H Items must be delimited by  one  or  more  spaces  or  tabs.   Quoted
H strings  (use double quotes, not single quotes) are allowed as single
H items; the quotes are removed from the items as  they  are  read.   A
H double quote can be obtained by using two double quotes with no space
H between them.  This form of quote handling is consistent with that of
 VMS DCL.
3 Applicability
H The <from-pat>, <to-pat>, <subject-pat> and <accept> items  determine
H whether  or  not  the  directive  applies to a particular message.  A
H string comparison  is  performed  between  the  patterns  <from-pat>,
H <to-pat>  and  <subject-pat>  and  the  "From:", "To:" and "Subject:"
H fields of the message header respectively.   The  comparison  is  not
H case  sensitive.  The usual VMS wildcard characters ("*" and "%") can
A be used in the patterns.  The pattern "*" will match anything.

H Once  the  comparisons  have  been  performed,  the   <accept>   item
H determines  if  the directive should be applied to the message.  Only
H the first character of <accept> is significant.  It should be one  of
 the following:

=     A - always apply this directive; ignore the results of
         the comparisons.
<     X - never apply this directive; ignore the results of
         the comparisons.
<     T - apply this directive if the patterns all matched.
B     F - apply this directive if the patterns did not all match.
?     O - apply this directive if the patterns all matched and
A         no previous directive has been applied to the message.
>     B - apply this directive if a pattern did not match and
A         no previous directive has been applied to the message.
=     E - this directive applies if all the patterns matched
9         OR no other directive has been applied so far.

H Any character whatsoever is legal:  Y is the same as T, N is the same
H as  F,  question  mark  is  the same as O, Q is the same as B and all
& other characters are the same as X.

H Directives are tested in the order they appear in  the  MAIL.DELIVERY
 file.

H For example, suppose JIM sends a message to BOB.  The subject line of
H the  message is "Re:  Mooses".  BOB's MAIL.DELIVERY file contains the
H following lines (the function of the last two columns of  each  line,
; the <action> and <parameter> items, is described later):

     "FRED *" * *         T Q
'     "JIM *"  * *         T A JIM.LOG
)     *        * *mooses*  T A MOOSE.LOG
)     *        * *         O A OTHER.LOG
     *        * *         A D

H The first directive in the file does not apply since the  message  is
H not  from FRED.  The second and third directives both apply since JIM
H is the sender and the subject line contains the string "mooses".  The
H fourth directive's patterns all apply, but a preceeding directive has
H applied, so it does not apply.  The final directive applies since  it
H would  apply  to  any  message.   The result is that three directives
H apply to this message, and thus three separate actions are  taken  in
 processing the message.

H Note:  The patterns "FRED *" and "JIM *" are useful  since  VMS  MAIL
H lets  users  set  up  personal  name  fields which become part of the
H "From:" field of the message -- the  personal  name  is  enclosed  in
H quotes  and  appended  to  the user name.  Depending on personal name
H fields for message handling is not a good idea since some users  have
H a  tendency  to change personal names frequently and without warning.
H The use of the space followed by an asterisk will match any  personal
H name  field  a user sets up; the result is a MAIL.DELIVERY file which
$ is insensitive to personal names.

H If none of the directives in the file  are  found  to  apply  to  the
H message,  the  message  is  just delivered normally.  In effect, each
9 MAIL.DELIVERY file implicitly ends with the directive:

     * * * O D
3 Actions
H The <action> and <parameter> items specify what action is taken  when
H a directive is applied to a message.  The first character of <action>
H specifies what type of action to  take.   The  legal  characters  for
! <action> and what they do are:

B     A - append the body (or contents) of the message to a file.
A         The <parameter> item specifies the file name. The file
F         must already exist and the recipient must have write access
F         to the file; DELIVER grants the user no special file access
         privileges.
?     C - copy the body of the message to a file whose name is
?         <parameter>. Write access to the directory where the
-         file is to be created is required.
A     D - deliver the message normally. The message is placed in
=         the user's NEWMAIL folder. <parameter> is ignored.
@     V - deliver the message normally using system privileges.
C         This action is identical to action "D" above except that
B         the "From:" field of the message header is set to match
A         the name of the original sender instead of the name of
A         the user. This action makes use of the DELIVER foreign
A         mail interface in incoming mode which in turn requires
B         that the user be fully privileged. General users should
"         use action "D" instead.
D         This form of delivery requires the account delivering the
,         message to have BYPASS privilege.
C     E - execute the specified command. The DCL command specified
A         by <parameter> is executed. The command is executed in
>         the environment of the recipient's own account. Any
<         noninteractive DCL command is valid, including an
C         indirect command file specification. Several DCL symbols
;         can be used in the command to facilitate message
         processing:

:         FROM           - the message's "From:" address.
8         TO             - the message's "To:" address.
5         SUBJECT        - the message's "Subject:".
0         CC             - the message's "Cc:".
8         QFROM          - "From:" with quotes doubled.
;         QQFROM         - "From:" with quotes quadrupled.
6         QTO            - "To:" with quotes doubled.
9         QQTO           - "To:" with quotes quadrupled.
;         QSUBJECT       - "Subject:" with quotes doubled.
>         QQSUBJECT      - "Subject:" with quotes quadrupled.
6         QCC            - "Cc:" with quotes doubled.
9         QQCC           - "Cc:" with quotes quadrupled.
?         MESSAGE_FILE   - the name of the file containing the
=                          body of the message. MESSAGE_FILE
6                          is always fully qualified.
;         MESSAGE_DELETE - initially set to "YES", if this
A                          symbol is set to "NO" no attempt will
@                          be made to delete MESSAGE_FILE after
D                          all actions are complete. The M <action>
@                          sets MESSAGE_DELETE to "NO" as well.

B         The "Q" forms are useful if the symbol must be expanded
D         inside a quoted string. The MESSAGE_DELETE flag is useful
B         if MESSAGE_FILE has to be queued for further processing
@         at a later time, or if one of the actions has already
         deleted it.
?     F - forward the message. The message is forwarded to the
,         address specified by <parameter>.
C     W - forward the message using system privileges. This action
C         is identical to action "F" above except that the "From:"
B         field of the message header is set to match the name of
D         the original sender instead of the name of the user. This
D         action makes use of the DELIVER foreign mail interface in
@         incoming mode which in turn requires that the user be
A         fully privileged.  General users should use action "F"
         instead.
D         This form of delivery requires the account delivering the
,         message to have BYPASS privilege.
B     Q - quit; take no action and abort. If this action is taken
@         DELIVER stops scanning the MAIL.DELIVERY file at this
@         point. No subsequent directives will apply after this
@         one. Use this directive with care; it is very easy to
6         lose messages when this action is employed.
F     K - save the command file after execution. Normally the command
F         file created on behalf of the user is deleted automatically
>         after execution. This action, if used inhibits this
         automatic deletion.
E     L - save the batch log of the DCL commands executed by DELIVER
D         for each message processed in the file <parameter> in the
F         user's login directory. This option is useful for debugging
D         MAIL.DELIVERY files and command scripts. If more than one
D         L <action> is triggered only the last one has any effect.
F     M - save the message file after execution of the batch job. The
?         message file is normally deleted as the last step of
B         processing by the batch job. This action suppresses the
A         automatic deletion; the same effect can be obtained by
3         setting the MESSAGE_DELETE flag to "NO".

H For example, suppose that BOB sends  JIM  a  message.   JIM  has  the
1 following (rather complex) MAIL.DELIVERY file:

@     ! Messages with subject "Loopback" are returned to sender
!     "JIM *"   * "Loopback" T D
C     *         * "Loopback" O F """''F$ELEMENT(0,"" "",QFROM)'"""
!     *         * "Loopback" T Q
&     ! All other messages are logged
-     *         * *          A E @LOGALL.COM
%     ! Just log messages from TERRY
!     "TERRY *" * *          T Q
.     ! Just log archive messages from myself
!     "JIM *"   * "Archives" T Q
1     ! Save messages from BOB in a special file
)     "BOB *"   * *          T A BOB.LOG
1     ! Then deliver anything that gets this far
!     *         * *          A D

4 JIM's LOGALL.COM contains the following commands:

&     $ from    == "From:    " + from
$     $ to      == "To:      " + to
)     $ subject == "Subject: " + subject
1     $ open/append/error=make_one x message.log
     $ next:
     $ write x ""
     $ write x from
     $ write x to
     $ write x subject
     $ write x ""
     $ close x
*     $ append 'message_file' message.log

     $ exit

     $ !
     $ make_one:
     $ create message.log
"     $ open/append x message.log
     $ goto next

H If the subject line of BOB's message is not  the  string  "Loopback",
H the  message  will  be  logged  with a header in the file MESSAGE.LOG
H (located in JIM's SYS$LOGIN directory), appended to the file  BOB.LOG
H without any header and delivered to JIM's NEWMAIL folder.  If subject
H line is the string "Loopback", JIM's MAIL.DELIVERY file  will  bounce
! the message right back to BOB.

H As another example, if TERRY sends a message to BOB, the  message  is
H logged  only  in  BOB's  MESSAGE.LOG  file;  BOB  never  receives any
H notification that the message arrived.  Apparently TERRY  never  says
! anything of importance to BOB.

H It is clear that the ability to  execute  an  arbitrary  set  of  DCL
H commands  in response to a message is a very powerful tool.  It must,
H however, be used with care, since processing is initiated whenever  a
H message   is   received  and  operates  in  a  completely  unattended
 environment.
2 Implementation
H Warning:  The details in this section are technical in nature and are
> probably of interest only to system managers or programers.

H DELIVER is implemented as foreign interface to VMS MAIL.  DELIVER  is
H activated  when  a message addressed to "DELIVER%user" is sent.  MAIL
H invokes DELIVER by loading the DELIVER_MAILSHR  shareable  image  and
H calling  a  set  of  routines  DELIVER provides to interface to MAIL.
 DELIVER does the following:

H(1)  The $GETUAI system service  is  used  to  validate  the  address.
H     DELIVER  will  signal  an  error if an attempt is made to deliver
H     mail to someone who does  not  exist.   The  recipient's  default
H     directory  is  retrieved  to  use  when  opening  the recipient's
     MAIL.DELIVERY file.
H(2)  DELIVER checks to see that the recipient has a MAIL.DELIVERY file
H     in  his  or  her  home  directory.   If  this file does not exist
H     DELIVER signals an error.  If the file  exists  it  is  read  and
     parsed.
H(3)  DELIVER writes the body of the message to a temporary file in the
"     recipient's home directory.
H(4)  A command file is constructed to complete the  delivery  process.
H     This file is also created in the recipient's home directory.  The
H     directives  previously  read  from  the  MAIL.DELIVERY  file  are
H     compared  with  the  message.   Any  directories that match cause
H     commands to be written to the command  file  that  implement  the
     requested action.
H(5)  After the list of directives is exhausted DELIVER checks  to  see
H     that  at  least  one  directive caused an action to be taken.  If
H     none did, DELIVER writes a default action command to deliver  the
H     message  normally  into the command file.  Commands to delete the
H     message file (unless the MESSAGE_DELETE flag is set  to  "NO"  by
H     one  of  the  actions) and the command file itself are written to
7     the command file and the command file is closed.
lH(6)  The command file is queued to the batch queue  DELIVER_BATCH  for
H     processing.  (SYS$BATCH is used if DELIVER_BATCH does not exist.)
H     The file is queued so  that  it  will  execute  just  as  if  the
H     recipient  had  submitted  it  for processing from his or her own
H     account.  (Note:   This  requires  CMKRNL  privilege.)  Once  the
H     command  file  is  submitted  DELIVER tidies up, deallocating any
H     storage allocated for directive lists,  and  returns  control  to
     MAIL.
2 Sending_messages
H Every foreign protocol interface to VMS MAIL has  two  parts  --  one
H which  deals  with  received messages (the outgoing part) and another
H which transfers messages to VMS MAIL (the incoming  part).   All  the
H functions  of  DELIVER  described  up  to  this point are part of the
H outgoing part.  Rather  than  include  a  null  incoming  handler  in
H DELIVER,  it  was  decided  to add a general-purpose message queueing
H system that might be useful both as a simple interface  to  VMS  MAIL
H and as an example of how this part of a foreign protocol interface is
 constructed.
h
H The message enqueueing part of DELIVER can  be  used  only  by  fully
H privileged  users  since  it  allows  arbitrary  settings  of "From:"
H addresses and so could violate MAIL security in the hands of  general
D users.  Thus, this mechanism is of little interest to most users.

H A message is sent via DELIVER to VMS MAIL with a command of the form:

(     $ MAIL/PROTOCOL=DELIVER_MAILSHR -
4           /SUBJECT="subject" message-file to-list

H where "subject" is the subject line for the  message,  "message-file"
H is  the name of a file containing the text of the message and to-list
H is a list of user names (delimited by commas) the message  is  to  be
H sent  to.   The  "From:"  address for the message is not specified as
H part of the command line; it is obtained instead by  translating  the
H DCL  symbol DELIVER_FROM.  No checking is done on the validity of the
H translation.  This mode of MAIL operation roughly corresponds to  the
. "trusted submit" mode available in MMDF-II.

H The CC:  line is obtained from the  translation  of  the  DCL  symbol
C DELIVER_CC.  No CC:  line is used if this symbol is not defined.
 
H DELIVER sets two DCL symbols to indicate the success  or  failure  of
H its  attempt  to deliver the message.  The symbol DELIVER_STATUS will
H contain the status code of the  last  error  that  occurs  while  the
H message is being sent.  If DELIVER_STATUS indicates that some sort of
H failure occurred, the symbol DELIVER_MESSAGE will  contain  the  text
 form of the error message.
u
H In the event of multiple errors while sending (e.g.  two addresses in
H the  "to-list"  are  illegal)  only  the  more  recent  error  status
H information will be returned.  This interface is somewhat  crude  but
/ should prove adequate for most applications.
e
H The incoming side of DELIVER is used by the outgoing side to  process
H the "V" and "W" actions, which correspond to "privileged deliver" and
0 "privileged forward" operations respectively.
2 Installation
H If you have received DELIVER as part of PMDF, it will be installed as
+ part of the PMDF installation procedure.
e
H If you received DELIVER as a separate  piece  of  software,  you  can
 install it as follows:
m
H(1)  Unpack the various files that comprise DELIVER into an  otherwise
  empty directory.

H(2)  Build DELIVER using the BUILD.COM  procedure  provided  with  the
H  distribution.    This   should   produce   two   executable   files,
6  DELIVER_MAILSHR_V4.EXE and DELIVER_MAILSHR_V5.EXE.

H(3)  Move the DELIVER executables to whatever directory they  will  be

  run from.
t
H(4)  Edit the file  DELIVER_STARTUP.COM  to  point  at  the  directory
H  you've chosen for the DELIVER executables.  This file should then be
H  copied to SYS$COMMON:[SYSMGR] and set up to be run  at  system  boot
H  time.  You should also execute this command file by hand to start up
  DELIVER.

H(5)  Set up a batch queue DELIVER_BATCH for DELIVER to use.  This step
H  is optional -- DELIVER will use the default batch queue SYS$BATCH if
H  DELIVER_BATCH  does  not  exist.   If  you  like,  you  can   define
H  DELIVER_BATCH  as a system logical name to point at some other queue
  for DELIVER to use.
c
*(6)  DELIVER should now be ready to use.
2 Availability
H DELIVER is distributed as part  of  the  PMDF-822,  the  Pascal  Memo
> Distribution Facility.  PMDF-822 can also be obtained from:

2                     Ned Freed (ned@ymir.bitnet)
'                     The PMDF Project
n)                     Computing Services
*                     Harvey Mudd College
*                     Claremont, CA 91711
%                     (714) 621-8006
 
D The latest version of DELIVER may be obtained independently from:

      Dick Munroe
'      Doyle, Munroe Consultants, Inc.
T      267 Cox St.
       Hudson, Ma. 01749
c      (508) 568-1618
      (FAX) (508) 562-1133
      munroe@dmc.com

2 or from a VMSNET.SOURCES archive site near you.
: Please write, call or send e-mail for more information.
2 Documentation
 D The file DELIVER.RNO contains the only documentation for DELIVER.
 (You are
aH reading a version of it right now.) DELIVER.RNO can be used either to
 produce a
= printed document or a VMS help file entry. Use the command
r
:     $ RUNOFF/NOBOLD/NOUNDER/OUT=DELIVER.HLP DELIVER.RNO

H to create the online help entry. DELIVER.HLP can be inserted into any
 VMS help
n library. Use the command
 
6     $ RUNOFF/OUT=DELIVER.MEM/VAR=MANUAL DELIVER.RNO

% to create a document for printing.
d2 Bugs
H There are no known bugs in DELIVER at this time. However, there are a
 few minor
, nuisances which users should be aware of:

H(1)  DELIVER changes the "From:" address of any message it delivers or
     forwards
aA     to the address of the owner of the MAIL.DELIVERY file. The
h     original "From:"
RD     address is not lost entirely -- it is merged into the subject
     line of the
=     message. This problem arises due to VMS MAIL's lack of
g     distinction between a
G     transport address and a header address -- DELIVER has to set the
i     "From:"
D     address to itself so that authorization code in other mailers
     will see it.
nH     Privileged users can circumvent this restriction by using the "V"
     and "W"
D     actions, but no such mechanism is available to general users.
E(2)  It is difficult to debug MAIL.DELIVERY files since there is no
e
     way to
sF     watch deliver process the file except by enabling debug code in
     DELIVER (which
mD     is not an option normal users can exercise). However, the "L"
     <action> can be
H     used to create a log file of the DCL commands DELIVER executes on
     behalf of the
&     user when processing a message:

<         ! Log commands executed in a file unconditionally
          * * * A L DELIVER.LOG
&         * * * A E @DO_SOMETHING.COM

E     Such log files are always placed in the user's home directory.
r     Also note that
H     output from command files invoked by DELIVER can be captured in a
     file by using
     the /OUTPUT qualfier:

0         ! Execute a command file with logging
>         * * * A E @DO_SOMETHING.COM/OUTPUT=DO_SOMETHING.LOG

F     DELIVER does watch for users sending messages to themselves and
     then tries to
E     be somewhat more informative than is usual about any errors it
      finds in
b     MAIL.DELIVERY files.
s@(3)  It is possible to enable debugging code within DELIVER by
6     defining either or both of these logical names:

         DELIVER_DEBUG_IN
v
C     which enables debugging output for mail input processing and
e
         DELIVER_DEBUG_OUT

@     which enable debugging output for mail output processing.

?     This allows you to observe the inner workings of DELIVER
      interactively.

G(4)  Enabling the COPY_SELF feature in MAIL while DELIVER is also set
      to send
D     messages to the user's mailbox may send MAIL into an infinite
     loop. The
A     COPY_SELF facility should not follow forwarding addresses;
      unfortunately it
rD     does do this in the present implementation. Thus a message is
     sent by DELIVER
G     to the user's mailbox, which in turn re-activates DELIVER, which
.     sends the
0     message to the user's mailbox, and so on.
A(5)  Lines in all files processed by DELIVER are limited to, at
      most, 256
@     characters. Individual directive items as well as message
     "From:", "To:" and
 C     "Subject:" lines are also limited to 256 characters. DELIVER
Q     truncates these
F     lines to this length. This limit can be changed by altering the
     constant
 H     PARAMETER_SIZE in DELIVER.PAS. However, these lines will still be
     truncated in
 B     the DCL DELIVER produces since DCL is also limited to lines
     containing no more
A     than 256 characters.
"