DELIVER screens and automatically processes your incoming mail based on guidelines that you provide. Different actions can be taken based on a message's envelope or header addresses, subject, or content. These actions include delivering the message, filing the message away, forwarding the message, or even invoking a DCL command procedure to perform complex processing. Any actions taken occur immediately upon receipt of each message; you do not need to be logged in at the time a message is received in order for actions to be taken on your behalf. DELIVER is modelled after the MAILDELIVERY facility of the MMDF mail system. DELIVER is, however, completely distinct from MMDF and the formats of .MAILDELIVERY files for MMDF and MAIL.DELIVERY files for DELIVER are dissimilar.
1 – Setting Up DELIVER
In order to use DELIVER, you must first take two steps: 1. Create a MAIL.DELIVERY file in your default login directory. For security reasons this file must be located in your default login directory - it cannot be stored elsewhere. The format of a MAIL.DELIVERY file is described under the subtopic "MAIL.DELIVERY File format". This first step is all that is required to cause DELIVER to process mail delivered to you by PMDF. That is, the presence of a MAIL.DELIVERY file is all that is required to activate DELIVER for messages you receive via PMDF. 2. Set your mail forwarding address to "IN%""~USERNAME""" (OpenVMS 7.0 or earlier) or to IN%"~USERNAME" (OpenVMS 7.1 or later) where USERNAME is your username. Refer to the PMDF User's Guide for further information on using the SET FORWARD command. This step is required to cause DELIVER to process mail you receive in your VMS MAIL mailbox by means other than PMDF. Once these two steps have been taken, DELIVER will be invoked automatically to handle all mail as it is delivered to you. For example, suppose the user BOB on an OpenVMS 7.0 system wants to have DELIVER process his incoming messages. BOB should create a MAIL.DELIVERY file in his login directory and then set his forwarding address, $ MAIL MAIL> SET FORWARD "IN%""~BOB""" MAIL> EXIT $
2 – MAIL.DELIVERY File format
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.
2.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.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
2.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.
3 – Operation
As it delivers messages to local users PMDF checks to see if the user has a MAIL.DELIVERY file in their default login directory. DELIVER is invoked if this file exists. DELIVER takes the following steps: 1. DELIVER reads and parses the MAIL.DELIVERY file. By default the message is returned to the sender if any errors occur during the reading and parsing of the MAIL.DELIVERY file. Note that an empty MAIL.DELIVERY file is considered an error. The system administrator can configure DELIVER to change this behavior. If the logical name PMDF_IGNORE_MAIL_DELIVERY_ERRORS is defined /SYSTEM/EXECUTIVE, any errors in the MAIL.DELIVERY file (including an empty file) are ignored. The mail is delivered normally to the user's NEWMAIL folder as if the MAIL.DELIVERY file did not exist. 2. DELIVER writes the headers of the message to a temporary file in the recipient's home directory. 3. DELIVER writes the body of the message to a temporary file in the recipient's home directory. 4. A command file is constructed to complete the delivery process. This file is also created in the recipient's home directory. The directives previously read from the MAIL.DELIVERY file are compared with the message. Any directives that match will cause commands to be written to the command file that implements the requested action. 5. After the list of directives is exhausted DELIVER checks to see that at least one directive caused an action to be taken. If none did, DELIVER writes to the command file a default action command to deliver the message normally. Commands to delete the message file (unless the MESSAGE_DELETE flag is set to NO by one of the actions) and the command file itself are written to the command file and the command file is closed. 6. The command file is queued to the batch queue specified by the MAIL.DELIVERY file for processing. If the MAIL.DELIVERY files not specify a queue, the DELIVER_BATCH queue will be tried, and if that fails the queue SYS$BATCH will be used. The file is queued so that it will execute just as if the recipient had submitted it for processing from his or her own account. Once the command file is submitted DELIVER tidies up, deallocating any storage allocated for directive lists, and returns control to PMDF. DELIVER does not bother to create the batch job if there's no work for it to do. 7. DELIVER passes responsibility for delivery back to PMDF if it was asked to deliver the message to the user's NEWMAIL folder and the requested handling of headers matches the the handling specified by the local channel. This does not preclude other actions using the message in other ways.
4 – Subaddresses
Subaddresses provide a convenient handle for screening e-mail messages with DELIVER. To screen mail based upon a subaddress, you must use a 1, 2, or 3 action to obtain the envelope TO: address associated with the mail message being delivered to you. You cannot use headers since there is no requirement that your address has to appear in the header of messages you receive, either with or without the subaddress. For instance, to detect the subaddress "junk-mail", use the directives * * * T 2 "ENVELOPE-TO" * "*+junk-mail*" * T D WASTEBASKET The first of these two directives tells DELIVER to use the envelope TO: address for 2-PATTERN. The second directive then causes any messages with +junk-mail appearing in the envelope TO: address to be filed to your WASTEBASKET folder.
5 – Limitations
There are no known bugs in PMDF's DELIVER subsystem at this time. However, there are a few minor nuisances which users should be aware of: 1. It is difficult to debug MAIL.DELIVERY files since there is no way to watch deliver process the file except by enabling debug code in DELIVER (which is not an option normal users can exercise). However, the L action can be 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 Such log files are always placed in the user's home directory. Also note that output from command files invoked by DELIVER can be captured in a file by using the /OUTPUT qualifier: ! Execute a command file with logging * * * A E @DO_SOMETHING.COM/OUTPUT=DO_SOMETHING.LOG DELIVER does watch for users sending messages to themselves and then tries to be somewhat more informative than is usual about any errors it finds in MAIL.DELIVERY files. 2. Much of the line and symbol processing done by DELIVER uses 252 character buffers. In particular, parameters in MAIL.DELIVERY files are limited to a maximum of 252 characters each. Most lines processed by DELIVER are limited to PMDF's usual 1024 character maximum. Lines output to command files are a special case; DELIVER must respect DCL's builtin 256- character line length limit. This might impose even more severe restrictions on symbol assignments and other commands than DELIVER does. DELIVER silently truncates lines rather than complaining about line lengths.