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.

5.2.1 Directive Applicability

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.
=	Match if comparison string is 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, Y	Apply this directive if the patterns all matched.
F, N	Apply this directive if the patterns did not all match (i.e. 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, Q	Apply this directive if a pattern did not match and no 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 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.

5.2.2 Actions

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 Table 5-1 can be used in the command to facilitate message processing.

Table 5-1 DCL Symbols Available to DELIVER Command Files

Symbol	Equivalence value
FROM	The message's From: address (selected as described in Section 5.2.1)
TO	The message's To: address
SUBJECT	The message's Subject:
CC	The message's cc:
QFROM	From: with quotes doubled (selected as described in Section 5.2.1)
QQFROM	From: with quotes quadrupled (selected as described in Section 5.2.1)
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, QQC3	See S action
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.

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

For example, suppose that BOB@SAMPLE.COM sends JIM@EXAMPLE.COM a message. JIM@EXAMPLE.COM has the following (rather complex) MAIL.DELIVERY file:

! Messages with subject "Loopback" are returned to sender "*JIM@EXAMPLE.COM*" * "Loopback" T D * * "Loopback" O F """''F$ELEMENT(0,"" "",QFROM)'""" * * "Loopback" T Q ! All other messages are logged * * * A E @LOGALL.COM ! Just log messages from TERRY@ISI.COM "*TERRY@ISI.COM*" * * T Q ! Just log archive messages from myself "*JIM@EXAMPLE.COM*" * "Archives" T Q ! Save messages from BOB@STATEU.COM in a special file "*BOB@SAMPLE.COM*" * * T A BOB.LOG ! Then deliver anything that gets this far * * * 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.

5.2.4 Summary of Directives and Actions

Table 5-2 Summary of DELIVER Directive Applicability

Accept
Code	Directive applicability
A	Directive always applies
B, Q	Directive only applies if one or more patterns failed to match and no previous directives, except for A, have applied
E	Directive only applies if all patterns matched or no previous directives, except for A, have applied
F, N	Directive only applies if one or more patterns failed to match
O, ?	Directive only applies if all patterns matched and no previous directives, except for A, have applied
P	Directive only applies if one or more patterns matched
S	Directive only applies if one or more patterns matched and no previous directives, except for A, have applied
T, Y	Directive only applies if all patterns matched
X	Directive never applies

Table 5-3 Summary of DELIVER Actions

Action
Code	Parameters	Action taken
A	filename	Append the message body to the specified file
B	folder, filename	Same as D but with the message header appearing at the end of the message
C	filename	Copy the message body to the specified file
D, V	folder, filename	Deliver the message to the specified folder in the specified mail file; if filename not supplied then the default mail file is used
E	command	Execute the specified DCL command
F, W	address	Forward the message with VMS MAIL to the specified address
H	filename	Append the message, header and body, to the specified file
J	queue	Run the DELIVER batch job in the specified batch queue
K	---	Retain the DELIVER processing command file; do not delete it after DELIVER is done running
L	filename	Log DELIVER batch job processing to the specified log file
M	filename	Retain message header and message body files; do not delete them after DELIVER has finished running
O	folder, filename	Same as D but with the message header omitted
P	address	Forward the message with PMDF SEND to the specified address
Q	---	Quit immediately; execute no actions
R	---	Reset specified flags
S	---	Save as DCL symbols the pattern matching strings
1,2,3	---	Rebuild the strings used for pattern matching