% Librarian I01-29ٵ*Rٵ*9:5DELIVER Rٵ* 1 DELIVERF DELIVER is an adjunct to VMS MAIL which makes it possible forF incoming mail messages to be handled and processed automaticallyF based on information provided in a user-supplied file. DifferentF actions can be taken based on a message's address, subject orF contents. These actions include delivering the message, forwardingF the message or even invoking a DCL command script to perform someF complex operation. Any actions taken occ ur immediately upon receiptF of the message; the user does not need to log in for DELIVER to operate.F DELIVER is modelled after the MAILDELIVERY facility of the MMDF mailF system. DELIVER is, however, completely distinct from MMDF and theF formats of .MAILDELIVERY files for MMDF and MAIL.DELIVERY files for DELIVER are dissimiliar.F This document assumes that the reader is familiar with the VMS MAIL facility.2 SetupF Users can set up DELIVER to handle their incoming mail by doing just two things:F(a) Create a MAIL.DELIVERY file in their accounts' initial defaultF directory (SYS$LOGIN). For security reasons this file MUST beF located in the initial default directory -- it cannot be storedF anyplace else. The format of a MAIL.DELIVERY file is described below.F(b) Set their mail forwarding address for the account toF "DELIVER%user", where "user" is the username associated with theF user's account. The MAIL command to change or set a forwardingF address is SET FORWARD. Specifying another user's name inF conjunction with "DELIVER%" will perform no useful function --F mail will simply be forwarded and handled by that user's- MAIL.DELIVERY file, assuming one exists.F Once these two steps have been taken, DELIVER will be invokedF automatically to handle all mail as it is delivered. For example,F suppose user BOB wants to tell DELIVER to h andle incoming messages.6 BOB should create a MAIL.DELIVERY file and then type: $ MAIL" MAIL> SET FORWARD DELIVER%BOB MAIL>2 FormatF The MAIL.DELIVERY file controls DELIVER and tells it how to handleF each message. A MAIL.DELIVERY file consists of a series ofF directives with one directive on each line of the file. EachF directive specifies how a certain kind of message is to be handled.F A particular directive may or may not apply to a given mes sage. AnF attempt is made to apply every directive in the MAIL.DELIVERY file toF each message, thus more than one directive may apply to (and more8 than one action may be the result of) a single message.F Any line in the file which begins with a semicolon or an exclamation4 point is considered to be a comment and is ignored.F A directive line consists of the following items in order from left to right:D F Ite ms must be delimited by one or more spaces or tabs. QuotedF strings (use double quotes, not single quotes) are allowed as singleF items; the quotes are removed from the items as they are read. AF double quote can be obtained by using two double quotes with no spaceF between them. This form of quote handling is consistent with that of VMS DCL.3 ApplicabilityF The , , and items determineF whether or not the directive applies to a particular message. AF string comparison is performed between the patterns ,F and and the "From:", "To:" and "Subject:"F fields of the message header respectively. The comparison is notF case sensitive. The usual VMS wildcard characters ("*" and "%") can? be used in the patterns. The pattern "*" will match anything.F Once the comparisons have been performed, the itemF determines if the directive should be applied to th e message. OnlyF the first character of 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.@ F - apply this directive if the patterns did not all match.= O - apply this directive if the patterns all matched and? no previous directi ve has been applied to the message.< B - apply this directive if a pattern did not match and? no previous directive has been applied to the message.; E - this directive applies if all the patterns matched7 OR no other directive has been applied so far.F Any character whatsoever is legal: Y is the same as T, N is the sameF as F, question mark is the same as O, Q is the same as B and all$ other characters are the same as X.F Directives are tested in the orde r they appear in the MAIL.DELIVERY file.F For example, suppose JIM sends a message to BOB. The subject line ofF the message is "Re: Mooses". BOB's MAIL.DELIVERY file contains theF following lines (the function of the last two columns of each line,9 the and items, is described later): "FRED *" * * T Q% "JIM *" * * T A JIM.LOG' * * *mooses* T A MOOSE.LOG' * * * O A OTHER.LOG * * *  A DF The first directive in the file does not apply since the message isF not from FRED. The second and third directives both apply since JIMF is the sender and the subject line contains the string "mooses". TheF fourth directive's patterns all apply, but a preceeding directive hasF applied, so it does not apply. The final directive applies since itF would apply to any message. The result is that three directivesF apply to this message, and thus three separate actions are tak en in processing the message.F Note: The patterns "FRED *" and "JIM *" are useful since VMS MAILF lets users set up personal name fields which become part of theF "From:" field of the message -- the personal name is enclosed inF quotes and appended to the user name. Depending on personal nameF fields for message handling is not a good idea since some users haveF a tendency to change personal names frequently and without warning.F The use of the space followed by an a sterisk will match any personalF name field a user sets up; the result is a MAIL.DELIVERY file which" is insensitive to personal names.F If none of the directives in the file are found to apply to theF message, the message is just delivered normally. In effect, each7 MAIL.DELIVERY file implicitly ends with the directive: * * * O D 3 ActionsF The and items specify what action is taken whenF a directive is applied to a message. The first character  of F specifies what type of action to take. The legal characters for and what they do are:@ A - append the body (or contents) of the message to a file.? The item specifies the file name. The fileD must already exist and the recipient must have write accessD 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= . Writ e access to the directory where the+ file is to be created is required.? D - deliver the message normally. The message is placed in; the user's NEWMAIL folder. is ignored.> V - deliver the message normally using system privileges.A This action is identical to action "D" above except that@ the "From:" field of the message header is set to match? the name of the original sender instead of the name of? the user. This action  makes use of the DELIVER foreign? mail interface in incoming mode which in turn requires@ that the user be fully privileged. General users should use action "D" instead.B This form of delivery requires the account delivering the* message to have BYPASS privilege.A E - execute the specified command. The DCL command specified? by is executed. The command is executed in< the environment of the recipient's own account. A ny: noninteractive DCL command is valid, including anA indirect command file specification. Several DCL symbols9 can be used in the command to facilitate message processing:8 FROM - the message's "From:" address.6 TO - the message's "To:" address.3 SUBJECT - the message's "Subject:".. CC - the message's "Cc:".6 QFROM - "From:" with quotes doubled.9 QQFROM  - "From:" with quotes quadrupled.4 QTO - "To:" with quotes doubled.7 QQTO - "To:" with quotes quadrupled.9 QSUBJECT - "Subject:" with quotes doubled.< QQSUBJECT - "Subject:" with quotes quadrupled.4 QCC - "Cc:" with quotes doubled.7 QQCC - "Cc:" with quotes quadrupled.= MESSAGE_FILE - the name of the file containing the; body of the message. MESSAGE _FILE4 is always fully qualified.9 MESSAGE_DELETE - initially set to "YES", if this? symbol is set to "NO" no attempt will> be made to delete MESSAGE_FILE afterB all actions are complete. The M > sets MESSAGE_DELETE to "NO" as well.@ The "Q" forms are useful if the symbol must be expandedB inside a quoted string. The MESSAGE_DELETE fl ag is useful@ 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 .A W - forward the message using system privileges. This actionA is identical to action "F" above except that the "From:"@ field of the message header is set to match the name ofB the original sender i nstead of the name of the user. ThisB action makes use of the DELIVER foreign mail interface in> incoming mode which in turn requires that the user be? fully privileged. General users should use action "F" instead.B This form of delivery requires the account delivering the* message to have BYPASS privilege.@ 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 to4 lose messages when this action is employed.D K - save the command file after execution. Normally the commandD file created on behalf of the user is deleted automatically< after execution. This action, if used inhibits this automatic deletion.C L - save the batch log of the DCL commands executed by DELIVERB for each message processed in the file in theD user's login directory. This option is useful for debuggingB MAIL.DELIVERY files and command scripts. If more than oneB L is triggered only the last one has any effect.D M - save the message file after execution of the batch job. The= message file is normally deleted as the last step of@ processing by the batch job. This action suppresses the? automatic deletion; the same effect can be obtained b y1 setting the MESSAGE_DELETE flag to "NO".F For example, suppose that BOB sends JIM a message. JIM has the/ following (rather complex) MAIL.DELIVERY file:> ! Messages with subject "Loopback" are returned to sender "JIM *" * "Loopback" T DA * * "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/ ! Save messages from BOB in a special file' "BOB *" * * T A BOB.LOG/ ! Then deliver anything that gets this far * * * A D2 JIM's LOGALL.COM contains the following commands:$ $ from == "From: " + from" $ to == "To: " + to' $ subject == "Subject: " + subject/ $ open/append/error=make_one x message.lo"g $ 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 nextF If the subject line of BOB's message is not the string "Loopback",F the message will be logged with a header in the file MESSAGE.LOGF (located in JIM's SYS$LOGIN directory), appended to the # file BOB.LOGF without any header and delivered to JIM's NEWMAIL folder. If subjectF line is the string "Loopback", JIM's MAIL.DELIVERY file will bounce the message right back to BOB.F As another example, if TERRY sends a message to BOB, the message isF logged only in BOB's MESSAGE.LOG file; BOB never receives anyF notification that the message arrived. Apparently TERRY never says anything of importance to BOB.F It is clear that the ability to execute an arbitrary $set of DCLF commands in response to a message is a very powerful tool. It must,F however, be used with care, since processing is initiated whenever aF message is received and operates in a completely unattended environment.2 ImplementationF Warning: The details in this section are technical in nature and are< probably of interest only to system managers or programers.F DELIVER is implemented as foreign interface to VMS MAIL. DELIVER isF activated when a message addres %sed to "DELIVER%user" is sent. MAILF invokes DELIVER by loading the DELIVER_MAILSHR shareable image andF calling a set of routines DELIVER provides to interface to MAIL. DELIVER does the following:F(1) The $GETUAI system service is used to validate the address.F DELIVER will signal an error if an attempt is made to deliverF mail to someone who does not exist. The recipient's defaultF directory is retrieved to use when opening the recipient's & MAIL.DELIVERY file.F(2) DELIVER checks to see that the recipient has a MAIL.DELIVERY fileF in his or her home directory. If this file does not existF DELIVER signals an error. If the file exists it is read and parsed.F(3) DELIVER writes the body of the message to a temporary file in the recipient's home directory.F(4) A command file is constructed to complete the delivery process.F This file is also created in the recipient's home directory. TheF ' directives previously read from the MAIL.DELIVERY file areF compared with the message. Any directories that match causeF commands to be written to the command file that implement the requested action.F(5) After the list of directives is exhausted DELIVER checks to seeF that at least one directive caused an action to be taken. IfF none did, DELIVER writes a default action command to deliver theF message normally into the command file. Comman (ds to delete theF message file (unless the MESSAGE_DELETE flag is set to "NO" byF one of the actions) and the command file itself are written to5 the command file and the command file is closed.F(6) The command file is queued to the batch queue DELIVER_BATCH forF processing. (SYS$BATCH is used if DELIVER_BATCH does not exist.)F The file is queued so that it will execute just as if theF recipient had submitted it for processing from his or her ownF ) account. (Note: This requires CMKRNL privilege.) Once theF command file is submitted DELIVER tidies up, deallocating anyF storage allocated for directive lists, and returns control to MAIL.2 Sending_messagesF Every foreign protocol interface to VMS MAIL has two parts -- oneF which deals with received messages (the outgoing part) and anotherF which transfers messages to VMS MAIL (the incoming part). All theF functions of DELIVER described up to * this point are part of theF outgoing part. Rather than include a null incoming handler inF DELIVER, it was decided to add a general-purpose message queueingF system that might be useful both as a simple interface to VMS MAILF and as an example of how this part of a foreign protocol interface is constructed.F The message enqueueing part of DELIVER can be used only by fullyF privileged users since it allows arbitrary settings of "From:"F addresses and so could vi +olate MAIL security in the hands of generalB users. Thus, this mechanism is of little interest to most users.F A message is sent via DELIVER to VMS MAIL with a command of the form:& $ MAIL/PROTOCOL=DELIVER_MAILSHR -2 /SUBJECT="subject" message-file to-listF where "subject" is the subject line for the message, "message-file"F is the name of a file containing the text of the message and to-listF is a list of user names (delimited by commas) the message is to beF sent , to. The "From:" address for the message is not specified asF part of the command line; it is obtained instead by translating theF DCL symbol DELIVER_FROM. No checking is done on the validity of theF translation. This mode of MAIL operation roughly corresponds to the, "trusted submit" mode available in MMDF-II.F The CC: line is obtained from the translation of the DCL symbolA DELIVER_CC. No CC: line is used if this symbol is not defined.F DELIVER sets two DCL symbols to i -ndicate the success or failure ofF its attempt to deliver the message. The symbol DELIVER_STATUS willF contain the status code of the last error that occurs while theF message is being sent. If DELIVER_STATUS indicates that some sort ofF failure occurred, the symbol DELIVER_MESSAGE will contain the text form of the error message.F In the event of multiple errors while sending (e.g. two addresses inF the "to-list" are illegal) only the more recent error statusF inf .ormation will be returned. This interface is somewhat crude but- should prove adequate for most applications.F The incoming side of DELIVER is used by the outgoing side to processF the "V" and "W" actions, which correspond to "privileged deliver" and. "privileged forward" operations respectively.2 InstallationF If you have received DELIVER as part of PMDF, it will be installed as) part of the PMDF installation procedure.F If you received DELIVER as a separate piece of software, /you can install it as follows:F(1) Unpack the various files that comprise DELIVER into an otherwise empty directory.F(2) Build DELIVER using the BUILD.COM procedure provided with theF distribution. This should produce two executable files,4 DELIVER_MAILSHR_V4.EXE and DELIVER_MAILSHR_V5.EXE.F(3) Move the DELIVER executables to whatever directory they will be run from.F(4) Edit the file DELIVER_STARTUP.COM to point at the directoryF you've chose 0n for the DELIVER executables. This file should then beF copied to SYS$COMMON:[SYSMGR] and set up to be run at system bootF time. You should also execute this command file by hand to start up DELIVER.F(5) Set up a batch queue DELIVER_BATCH for DELIVER to use. This stepF is optional -- DELIVER will use the default batch queue SYS$BATCH ifF DELIVER_BATCH does not exist. If you like, you can defineF DELIVER_BATCH as a system logical name to point at some other queue 1for DELIVER to use.((6) DELIVER should now be ready to use.2 AvailabilityF DELIVER is distributed as part of the PMDF-822, the Pascal Memo< Distribution Facility. PMDF-822 can also be obtained from:0 Ned Freed (ned@ymir.bitnet)% The PMDF Project' Computing Services( Harvey Mudd College( Claremont, CA 91711# (714) 621-8006B The latest version of DELIVER m2ay be obtained independently from: Dick Munroe% Doyle, Munroe Consultants, Inc. 267 Cox St. Hudson, Ma. 01749 (508) 568-1618 (FAX) (508) 562-1133 munroe@dmc.com0 or from a VMSNET.SOURCES archive site near you.8 Please write, call or send e-mail for more information.2 DocumentationB The file DELIVER.RNO contains the only documentation for DELIVER. (You areF reading a version of it right now.) DELIVER.RNO can be used either to produce a3; printed document or a VMS help file entry. Use the command8 $ RUNOFF/NOBOLD/NOUNDER/OUT=DELIVER.HLP DELIVER.RNOF to create the online help entry. DELIVER.HLP can be inserted into any VMS help library. Use the command4 $ RUNOFF/OUT=DELIVER.MEM/VAR=MANUAL DELIVER.RNO# to create a document for printing.2 BugsF There are no known bugs in DELIVER at this time. However, there are a few minor* nuisances which users should be aware of:F(1) DELIVER changes the "From:" a 4ddress of any message it delivers or forwards? to the address of the owner of the MAIL.DELIVERY file. The original "From:"B 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 distinction between aE transport address and a header address -- DELIVER has to set the "From:"B address to itself so that authorization code in other mailers will see it.F Privile 5ged users can circumvent this restriction by using the "V" and "W"B actions, but no such mechanism is available to general users.C(2) It is difficult to debug MAIL.DELIVERY files since there is no way toD watch deliver process the file except by enabling debug code in DELIVER (whichB is not an option normal users can exercise). However, the "L" can beF used to create a log file of the DCL commands DELIVER executes on behalf of the$ u6ser when processing a message:: ! Log commands executed in a file unconditionally * * * A L DELIVER.LOG$ * * * A E @DO_SOMETHING.COMC Such log files are always placed in the user's home directory. Also note thatF output from command files invoked by DELIVER can be captured in a file by using the /OUTPUT qualfier:. ! Execute a command file with logging< * * * A E @DO_SOMETHING.COM/OUTPUT=DO_SOMETHING.LOGD DELIVER d7oes watch for users sending messages to themselves and then tries toC be somewhat more informative than is usual about any errors it finds in MAIL.DELIVERY files.>(3) It is possible to enable debugging code within DELIVER by4 defining either or both of these logical names: DELIVER_DEBUG_INA which enables debugging output for mail input processing and DELIVER_DEBUG_OUT> which enable debugging output for mail output processing.= 8 This allows you to observe the inner workings of DELIVER interactively.E(4) Enabling the COPY_SELF feature in MAIL while DELIVER is also set to sendB messages to the user's mailbox may send MAIL into an infinite loop. The? COPY_SELF facility should not follow forwarding addresses; unfortunately itB does do this in the present implementation. Thus a message is sent by DELIVERE to the user's mailbox, which in turn re-activates DELIVER, which 9 sends the. message to the user's mailbox, and so on.?(5) Lines in all files processed by DELIVER are limited to, at most, 256> characters. Individual directive items as well as message "From:", "To:" andA "Subject:" lines are also limited to 256 characters. DELIVER truncates theseD lines to this length. This limit can be changed by altering the constantF PARAMETER_SIZE in DELIVER.PAS. However, these lines will still be truncated in@ the DCL DELIVER produces since DCL is also limited to lines containing no more than 256 characters.ww