The MAIL.DELIVERY file controls DELIVER and tells it how to
handle each incoming message. A MAIL.DELIVERY file consists of
a series of directives with one directive on each line of the
file. Each directive specifies how a certain kind of message is
to be handled. A particular directive may or may not apply to a
given message. An attempt is made to apply every directive in the
MAIL.DELIVERY file to each message, thus more than one directive
may apply to (and more than one action may be the result of) a
single message.
Any line in the file which begins with a semicolon or an
exclamation point is considered to be a comment and is ignored.
A directive line consists of the following items in order from
left to right:
1-pattern 2-pattern 3-pattern accept action 1-parameter 2-parameter
Items must be delimited by one or more spaces or tabs. Quoted
strings (use double quotes, not single quotes) are allowed as
single items; the quotes are removed from the items as they
are read. A double quote can be obtained by using two double
quotes with no space between them. This form of quote handling is
consistent with that of OpenVMS DCL.
The 1-PARAMETER and 2-PARAMETER items are both optional and can
be omitted if the action ACTION requires no parameters. The first
five items are mandatory and must appear in every directive line.
1 – Directive Applicability
The 1-PATTERN, 2-PATTERN, 3-PATTERN, and ACCEPT items determine
whether or not the directive applies to a particular message. In
most cases a string comparison is performed between the patterns
1-PATTERN, 2-PATTERN, and 3-PATTERN and, respectively, the FROM:,
TO: and SUBJECT: fields that would be seen in VMS MAIL. Note
that these fields do not correspond exactly to the RFC 822 header
lines of the same name; a complex set of mapping criteria are
used to convert the RFC 822 header lines into VMS MAIL headers.
Moreover, it is possible to rearrange the strings the patterns
are compared against in complex ways using the 1, 2, and 3
actions.
The comparison is not case sensitive. The usual OpenVMS wildcard
characters, * and %, can be used in the patterns. The pattern *
will match anything. For partial matches, the pattern * is used
to indicate a field that should be ignored.
The default string comparison operations can optionally be
replaced with numeric comparisons. This is controlled by the
second and third characters in the ACCEPT item. If present, both
the column values and the comparison strings are converted to
integer values. The match fails if the conversion fails. A single
asterisk in the comparison string disables comparisons for that
column completely. Once converted, the ACCEPT item determines the
type of comparison:
> Match if comparison string is greater than the column value.
>= Match if comparison string is greater than or equal to the
column value.
< Match if comparison string is less than the column value.
<= Match if comparison string is less than or equal to the
column value.
<> Match if comparison string is not equal to the column value.
Once the comparisons, string or numeric, have been performed,
the ACCEPT item determines if the directive should be applied
to the message. Only the first two characters of ACCEPT are
significant at this point. The first character should be one
of the following:
A Always apply this directive; ignore the results of the
comparisons. Note that this directive does not count as
an applied directive (see the O, B, S, and E actions below).
X Never apply this directive; ignore the results of the
comparisons.
T, Apply this directive if the patterns all matched.
Y
F, Apply this directive if the patterns did not all match (i.e.
N some or all failed).
P Apply this directive if at least one of the patterns matched
(i.e. some or all matched). In this case the pattern * is
not treated as a match.
O, Apply this directive if the patterns all matched and
? no previous directive has been applied to the message.
Directives that used the A accept item don't count as having
been applied. DELIVER can also be told to forget the fact
the some directive has been applied by clearing the R flag
with the R action.
B, Apply this directive if a pattern did not match and no
Q previous directive has been applied to the message.
Directives that used the A accept item don't count as having
been applied.
S Apply this directive if at least one pattern matched and
no previous directive has been applied to the message.
Directives that used the A accept item don't count as having
been applied.
E This directive applies if all the patterns matched or no
other directive has been applied so far. Directives that
used the A accept item do not count as having been applied.
Any other character is interpreted as an X.
If the second character is an asterisk, *, then the ACCEPT item
is modified in that it does not count as an applied directive.
This makes it possible for any ACCEPT item to be treated like the
A item (which never sets the applied flag).
Directives are tested in the order they appear in the
MAIL.DELIVERY file.
For example, suppose JIM@EXAMPLE.COM sends a message to
BOB@SAMPLE.COM. The subject line of the message is "Re: Mooses".
BOB's MAIL.DELIVERY file contains the following lines (the
function of the last two columns of each line, the ACTION and
1-PARAMETER items, is described later):
"*FRED@SAMPLE.COM*" * * T Q
"*JIM@EXAMPLE.COM*" * * T A JIM.LOG
* * *mooses* T A MOOSE.LOG
* * * O A OTHER.LOG
* * * A D
The first directive does not apply since the message is not from
FRED@SAMPLE.COM. The second and third directives both apply since
JIM@EXAMPLE.COM is the sender and the subject line contains the
string "mooses". The fourth directive's patterns all match, but
a preceeding directive has applied, so it does not itself apply.
The final directive applies since it would apply to any message.
The result is that three directives apply to this message, and
thus three separate actions are taken in processing the message.
Note that the patterns "*FRED@SAMPLE.COM*" and
"*JIM@EXAMPLE.COM*" are useful since personal name fields
and possibly other addresses and source routes can appear in
addresses; (e.g., the address FRED@SAMPLE.COM might actually
appear as "Fred Smith <fred@sample.com>"). Depending on personal
name fields for message handling is not a good idea since some
users have a tendency to change personal names frequently and
without warning. The use of the leading and trailing asterisks
makes the pattern match any string that contains the address,
regardless of the context of the address; the result is a
MAIL.DELIVERY file which is insensitive to personal names.
If none of the directives in the file are found to apply to and
process the message in some way, the message is just delivered
normally. (Note, however, that an empty MAIL.DELIVERY file by
default is considered an error; unless your system manager has
configured DELIVER otherwise, your e-mail messages will not be
delivered if you have an empty MAIL.DELIVERY file.) The effect of
having no matching directives (in a non-empty MAIL.DELIVERY file)
is similar to the following directive:
* * * A D
Note that the J, K, L, M, R, S, 1, 2, and 3 actions are not
thought of as having "processed" the message and hence do not
block the application of this default.
2 – Actions
The ACTION and 1-PARAMETER items specify what action is taken
when a directive is applied to a message. The first character
of ACTION specifies what type of action to take. The legal
characters for ACTION and what they do are:
A
Append the body (or contents) of the message to a file. The
message header is not included. The 1-PARAMETER item specifies
the file name. The file need not already exist: if necessary,
it will be created. The recipient must have write access to the
file, if it exists, and write access to its directory if it needs
to be created; DELIVER grants the user no special file access
privileges.
B
Same as D but with the message headers appearing at the bottom of
any messages delivered to VMS MAIL. PMDF's FOLDER utility is used
to deliver the mail.
C
Copy the body of the message to a file whose name is 1-PARAMETER
. Write access to the directory where the file is to be created
is required.
D, V
Deliver the message normally to VMS MAIL. 1-PARAMETER is the name
of the folder the message is to be placed in. If 1-PARAMETER is
omitted the message is placed in the VMS MAIL's NEWMAIL folder
by default. Delivery to VMS MAIL's NEWMAIL is done directly by
PMDF; delivery to other folders is done using the FOLDER utility.
The V action is identical to the D action; it is retained for
compatibility with earlier versions of DELIVER.
If an additional parameter, 2-PARAMETER, is specified, then that
additional parameter will be interpreted as the name of the mail
file to use in the case of VMS MAIL delivery. The user's default
mail file and default directory are used if 2-PARAMETER is not
specified.
The following example shows an action that delivers to the
NEWMAIL folder in an alternate mail file:
* "*+gripes*" * T D NEWMAIL GRIPES.MAI
E
Execute the specified command. The DCL command specified by 1-
PARAMETER is executed. The command is executed in the environment
of the recipient's own account. Any noninteractive DCL command is
valid, including an indirect command file specification. The DCL
symbols shown in the table below can be used in the command to
facilitate message processing.
Table 1 DCL Symbols Available to DELIVER Command Files
Symbol Equivalence value
FROM The message's From: address (selected
as described under the topic Directive
Applicability)
TO The message's To: address
SUBJECT The message's Subject:
CC The message's cc:
QFROM From: with quotes doubled (selected as described
under the topic Directive Applicability)
QQFROM From: with quotes quadrupled (selected
as described under the topic Directive
Applicability)
QTO To: with quotes doubled
QQTO To: with quotes quadrupled
QSUBJECT Subject: with quotes doubled
QQSUBJECT Subject: with quotes quadrupled
QCC Cc: with quotes doubled
QQCC Cc: with quotes quadrupled
C1, C2, C3 See S action
QC1, QC2, QC3 See S action
QQC1, QQC2, See S action
QQC3
MESSAGE_FILE The name of the file containing the body of the
message; MESSAGE_FILE always contains a full
file path
MESSAGE_HEADER The name of the file containing the headers of
the message; MESSAGE_HEADER always contains a
full file path
MESSAGE_DELETE Initially set to "YES", if this symbol is set to
"NO", no attempt will be made to delete MESSAGE_
FILE and MESSAGE_HEADER after all actions are
complete; the M action sets MESSAGE_DELETE to
"NO"
The Q forms are useful if the symbol must be expanded inside a
quoted string. The MESSAGE_DELETE flag is useful if MESSAGE_
FILE or MESSAGE_HEADER (or both) have to be queued for further
processing at a later time, or if one of the actions has already
deleted them.
F, W
Forward the message. The message is forwarded to the address
specified by 1-PARAMETER.
VMS MAIL is used to send the message. As such, the address
specified by 1-PARAMETER must be one that VMS MAIL will accept;
PMDF addresses will probably require the use of an IN% construct,
for instance. A new message header is added; the original header
is lost. The new header refers to the forwarding user as the
message originator.
H
Append the header and the body (or contents) of the message to
a file. One blank line is written between the header and the
body. The 1-PARAMETER item specifies the file name. The file
need not already exist: if necessary, it will be created. The
recipient must have write access to the file, if it exists, and
write access to its directory if it needs to be created; DELIVER
grants the user no special file access privileges.
J
Set the batch queue or a queue parameter used to run the command
file produced by DELIVER. DELIVER uses the queue DELIVER_BATCH
by default; if this queue is not defined or is inaccessible by
the message recipient (the owner of the MAIL.DELIVERY file) the
queue SYS$BATCH will be used instead. The J action provides a way
to specify an alternate queue and/or a job parameter. If a single
1-PARAMETER is specified it is the name of the queue. If both 1-
PARAMETER and 2-PARAMETER are specified the former gives the name
of the job parameter to set and the latter gives the value to set
the parameter to. Currently the only parameters supported are P1
through P8, which set the corresponding positional job parameter
to the string specified in 2-PARAMETER.
If the queue specified with the J action cannot be used, the
DELIVER_BATCH queue or SYS$BATCH queue will be used instead.
K
Save the command file after execution. Normally the command
file created on behalf of the user is deleted automatically
after execution. This action, if used, inhibits this automatic
deletion.
L
Save the batch log of the DCL commands executed by DELIVER
for each message processed in the file 1-PARAMETER in the
user's login directory. This option is useful for debugging
MAIL.DELIVERY files and command scripts. If more than one L
action is triggered only the last one has any effect.
M
Save the message and header files after execution of the batch
job. The message and header files are normally deleted as the
last step of processing by the batch job. This action suppresses
automatic deletion of these files; the same effect can be
obtained by setting the MESSAGE_DELETE flag to NO.
O
Same as D but with the message headers omitted from messages
delivered to VMS MAIL. PMDF's FOLDER utility is used to deliver
the mail.
P
Forward the message. The message is forwarded to the address
specified by 1-PARAMETER.
PMDF is used to send the message. As such, the address specified
by 1-PARAMETER should be a standard RFC 822 style address.
The original message header is retained and supplemented with
additional information describing the forwarder as the sender of
the message.
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 lose messages when this
action is employed.
R
Reset specified flag or flags. This action examines its first
argument one character at a time and clears any associated flag.
Two flags are defined at present. The R flag is set whenever
DELIVER finds an applicable directive. This flag is tested by
the B, O, Q, S, and ? ACCEPT items. The A flag is set whenever
DELIVER applies some directive that is thought of as having
processed the message.
S
Save the current column strings for pattern matching of columns
one, two, and three in special DCL column variables C1, C2,
and C3, respectively. The DCL variables QC1, QC2, QC3 (quotes
doubled), QQC1, QQC2, and QQC3 (quotes quadrupled), are also
defined in the same way as the variables FROM, QFROM, and QQFROM
are defined.
This action makes it possible to save and act upon the results
produced by the 1, 2, and 3 actions in ways that cannot be
accommodated by the facilities DELIVER provides directly.
One, Two, Three (1, 2, 3)
Rebuild the strings the DELIVER patterns are matched against. 1
rebuilds the string 1-PATTERN is compared with, 2 rebuilds the
string 2-PATTERN is compared with, and 3 rebuilds the string 3-
PATTERN is compared with. 1-PARAMETER is either the keyword RESET
or an expression that describes the processing to be applied to
the message header to produce the resultant column string. The
expression is written in what amounts to a miniature language
specialized for just this purpose.
The expression language is very simple; it consists of tokens
that describe either atoms (in the spirit of RFC 822) or
operators. There are only two types of atoms and four operators.
The simplest form of atom is simply the field-name of a message
header. Any possible message header field-name can be specified,
including standardized ones like MESSAGE-ID, RESENT-FROM, and
REFERENCES and nonstandard ones like X-VMS-CC, ORGANIZATION,
and FRUIT-OF-THE-DAY. Any field-name can be specified, including
field-names that PMDF does not recognize or use itself.
Two special field-names with special meanings are provided.
ENVELOPE-FROM refers to the envelope FROM: address (which
usually, but not always, appears on the RETURN-PATH: header)
and ENVELOPE-TO refers to the ENVELOPE TO: address that describes
the current message recipient. The latter envelope information
usually appears on one of the various recipient headers (TO:,
RESENT-TO:, BCC:, etc.), but can be hard to locate in some cases
or completely missing in other cases.
The presence of such an atom amounts to a request to extract the
text from the header (or possibly headers) that correspond to
the specified field-name and use this text as the column string
result. If the specified field-name is not used in the message
header the atom extracts an empty or null string.
The other sort of atom is simply a quoted string. Single quotes
are used instead of double quotes since double quotes usually
surround the entire 1-PARAMETER. The contents of the quoted
string are used as the column string. This atom is not useful
by itself; it is designed to be used in conjunction with other
atoms and operators.
The most straightforward operator is concatenation. Two or more
atoms appearing side by side (with only spaces and/or tabs in
between) are concatenated to form a composite result.
A comma acts as a special form of concatenation. The expressions
on either side are evaluated and concatenated. If the expressions
on both sides of the comma produce non-null results, then a
comma-space sequence is inserted between them. The comma-space
is not inserted if either side produces only an empty string as a
result.
A forward slash, /, acts as a form of alternation. It will
"return" the result of the evaluation of the left hand side if
it is not empty, and the result of the right hand side if the
left hand side result is null. (The similarity of these operators
to those used in RFC 822 is not coincidental.)
An asterisk, *, is used as a special modifier to any expression.
When it precedes an expression, it requests that the evaluation
of any field-name atom return all header lines with the specified
field-name concatenated together, rather than simply the first
such line. A quoted string atom can be specified directly after
the asterisk, and if such a string is specified it is inserted
between any concatenated header lines.
Finally, the various operators bind differently. Asterisk binds
the tightest (similar to exponentiation in regular mathematical
expressions), followed by concatenation, and finally alternation.
Parentheses can be used to alter the binding order as needed.
Here are a few examples of 1-PARAMETER expressions:
* * * A 1 "MESSAGE-ID, RESENT-MESSAGE-ID, ALTERNATE-MESSAGE-ID"
The MESSAGE-ID:, RESENT-MESSAGE-ID:, and the (nonstandard)
ALTERNATE-MESSAGE-ID: headers are concatenated with commas
inserted between them.
* * * A 1 "(RESENT-TO,RESENT-CC,RESENT-BCC)/(TO,CC,BCC)/ENVELOPE-TO"
The various Resent- recipient headers are concatenated, and if
none of them exist the regular set of recipient headers are used
instead. If these in turn don't exist the envelope TO: address is
used (presumably as a last resort).
* * * A 1 "* ' ' RECEIVED"
All of the Received: headers are concatenated into a single
string separated by spaces.
Considerably more complex expressions can be built as the need
arises.
The keyword RESET restores the original value of the
corresponding column. This would be used after another 1, 2,
or 3 directive has modified the string. It is used for example as
follows:
* * * A 1 RESET
3 – Example
For example, suppose that BOB@SAMPLE.COM sends JIM@EXAMPLE.COM
a message. JIM@EXAMPLE.COM has the following (rather complex)
MAIL.DELIVERY file:
"*JIM@EXAMPLE.COM*" * "Loopback" T D
* * "Loopback" O F """''F$ELEMENT(0,"" "",QFROM)'"""
* * "Loopback" T Q
* * * A E @LOGALL.COM
"*TERRY@ISI.COM*" * * T Q
"*JIM@EXAMPLE.COM*" * "Archives" T Q
"*BOB@SAMPLE.COM*" * * T A BOB.LOG
* * * A D
JIM@EXAMPLE.COM's LOGALL.COM contains the following commands:
$ from == "From: " + from
$ to == "To: " + to
$ subject == "Subject: " + subject
$ 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
Note that a similar effect could be achieved by substituting
* * * A H MESSAGE.LOG
for
* * * A E @LOGALL.COM
but would log the entire header rather than a few selected lines.
If the subject line of BOB@SAMPLE.COM's message is not the string
"Loopback", the message will be logged with a header in the file
MESSAGE.LOG (located in JIM@EXAMPLE.COM's SYS$LOGIN directory),
appended to the file BOB.LOG without any header and delivered to
JIM@EXAMPLE.COM's NEWMAIL folder. If subject line is the string
"Loopback", JIM@EXAMPLE.COM's MAIL.DELIVERY file will bounce the
message right back to BOB@.SAMPLE.COM.
The F$ELEMENT DCL lexical function is used in this example to
eliminate the personal name field from the address, if one is
present. Care must be taken to deal with personal name fields
attached to VMS MAIL addresses in a proper manner. The approach
of using F$ELEMENT is simple and usually very effective; note
that it can fail if the address part of the VMS MAIL header line
contains spaces.
As another example, if TERRY@ISI.COM sends a message to
JIM@EXAMPLE.COM, the message is logged only in JIM@EXAMPLE.COM's
MESSAGE.LOG file; JIM@EXAMPLE.COM never receives any notification
that the message arrived. Apparently, TERRY@ISI.COM never says
anything of importance to JIM@EXAMPLE.COM.
It is clear that the ability to execute an arbitrary set of DCL
commands in response to a message is a very powerful tool. It
must, however, be used with care, since processing is initiated
whenever a message is received and operates in a completely
unattended environment.