B Here's an all too brief description of the foreign mail interface.  K This information comes from the VMS MAIL source listings on the microfiche. J The best place to look is in routine NETJOB in module MAIL$MAIL (page 230,K frame E-2), for incoming mail, and in the various routines in NETSUBS (also ? page 230, frame N-11), which cover both in- and out-bound mail.   L The fundamental mechanism here is that MAIL recognizes certain address formsK as foreign, and uses two mechanisms to hook into a foreign delivery system.  Any address of the form:   	protocol-name%address  J is an indicator to MAIL that it should be using a foreign mechanism.  MAIL7 first attempts to translate a logical name of the form:    	MAIL$PROTOCOL_protocol-name  / If this translates to a string that looks like:    	%decnet-task-invocation-spec   J then MAIL will set up the DECnet connection to the task spec it gets afterI stripping away the "%" and speak MAIL-11 to it.  MAIL-11 is, as near as I G can figure, the protocol that myself and others were using in VMS V3 to L speak to MAIL in order to hook our foreign delivery systems to it.  For moreL information on MAIL-11, see the code for SENDMAIL which I provided on eitherI the Spring or Fall '84 DECUS tapes.  I would assume that this protocol is I used internally within DEC to get VMS MAIL talking to other DEC operating  systems which support DECnet.   J The second mechanism that MAIL uses to invoke a foreign delivery system isK indicated by the absence of a leading "%" in the translation of the logical F name I mentioned above or by the complete absence of the logical name.? In this case, MAIL uses the new VMS V4 Run-Time Library routine J LIB$FIND_IMAGE_SYMBOL to map the interface code into it's address space atG run time.  If the logical name MAIL$PROTOCOL_protocol-name exists, then L it must point to the shareable image to be mapped.  If the logical name doesI not exist, then MAIL will map in the shareable image in SYS$SHARE called:    	protocol-name_MAILSHR.EXE  H The VAX-11 PSI product, for example, comes with a shareable image calledJ PSI_MAILSHR.EXE which it places in SYS$SHARE.  This allows the PSI productL to use MAIL for delivery of messages over a PSI network without the need for DECnet on the network.  & A little more about foreign addresses:  L I've experimented with various formats of foreign addresses and I think I'veN figured out most of the rules.  The simplest format is an address of the form:   	aaa%bbb  J In this case, the protocol is "AAA" and the address is "BBB" (MAIL upcasesM the address before doing anything else).  If you need to preserve case in the ) address, then you can use something like:   
 	aaa%"bbb"  M Unlike previous versions of MAIL, the V4 utility preserves case inside quoted F character strings.  It is possible to include double-quotes inside theM protocol portion of the address (i.e. before the "%") to preserve case within G the protocol string.  The protocol string, however, cannot start with a M double quote.  Since you, as the foreign interface implementor, have complete I control over the protocol naming conventions within the context of a MAIL F interface, I would suggest that you not use this feature and make yourM protocols distinct, regardless of the case of the letters within the protocol G name.  I say this because I'm not sure what all the rules are when MAIL I attempts to translate the logical name or reference a file spec which may  have double quotes in it.   J The foreign address conventions can be mixed with the normal DECnet syntaxK that MAIL already supports.  For example, it should be perfectly reasonable L to set up one system on your network as a gateway and have it understand theF foreign interface.  Other systems on the DECnet network can then route2 messages through the gateway with an address like:  $ 	gate::protocol-name%foreign-address  I The concept of a node name is also supported within the "foreign-address" L portion of the string, if you want to use it.  For example, MAIL routed over7 an X.25 network with the PSI product is addressed like:   # 	PSI%X.25-network-address::username   N In my foreign mailer, I could route UUCP messages with an address of the form:   	UUCP%uucp-host-name::username  J but because the UUCP network needs to have routing explicitly specified inL the address (and for consistency with address formats on other UUCP mailers)L I do not use the "host::user" format of a foreign address specification.  In7 my case, mail to be sent out with UUCP is addressed as:   2 	UUCP%"host!user" or UUCP%"host1!host2!user", etc.  L The decision to use MAIL's concept of a "node::user" specifier is completelyJ up to the implementor.  If you DO use this syntax, then MAIL will separateL the foreign node name and the foreign username before calling your interfaceL routines and will pass them separately.  If you do not use it, then you willM have to parse your foreign address yourself.  ARPAnet addresses, for example,  could be handled with either:    	arpa%sri-kl::info-vax or 	arpa%"info-vax@SRI-KL"   K The first is a little cleaner as it does not require double quoting and the O interface routines will receive "SRI-KL" and "INFO-VAX" as separate parameters; I the second is more consistent with ARPAnet address syntax (the quotes are  required because of the "@").   D Inbound foreign mail to be delivered to VMS MAIL users is handled byG including an undocumented MAIL switch on the MAIL command line.  A MAIL 
 command like:   7 	$ mail/protocol=protocol-image-name filename recipient   : will cause MAIL to map in the shareable image specified inI "protocol-image-name".  Note that the process executing this command must L have both SYSPRV and DETACH privileges or MAIL will ignore the switch.  ThisJ is, I assume, to prevent unauthorized persons from delivering forged mail.H Unfortunately, this means that you will have to come up with some way ofM granting these privileges to your network process that will trusted with mail H delivery.  I personally do not like this requirement, because my networkL entity can be trusted with MAIL delivery, but should NOT be trusted with theL SYSPRV privilege.  A much better solution, I think, would have been to checkH whether the process attempting to deliver mail posseses a special accessJ control identifier that has been granted by the system manager.  But then,' I'm a big fan of ACL's and identifiers.   K The first thing that MAIL does upon mapping in your shareable interface is  D obtain the values of the two universal symbols MAIL$C_PROT_MAJOR andJ MAIL$C_PROT_MINOR.  I assume that these exist to allow future inclusion ofH other protocol types.  For now, however, the only legal value for either symbol is 1.  I MAIL invokes the interface when it needs to by calling the entry point in M your shareable image called MAIL$PROTOCOL.  It calls the same entry point for ( all functions.  The call is of the form:  I   MAIL$PROTOCOL (context, function_code, function-dependent-arguments...)   K "context" is a variable that you may use for aything you like.  Usually, it C points to some area that your procedure allocates initially to keep I connection-dependent information.  You should maintain NO static storage, M since your routines must be completely reentrant.  Use the context pointer to ) maintain anything you need between calls.   , "function_code" refers to any of the values:  C   LNK_C_OUT_CONNECT  = 0  LNK_C_IN_CONNECT = 8  LNK_C_IO_READ  = 14 C   LNK_C_OUT_SENDER   = 1  LNK_C_IN_SENDER  = 9  LNK_C_IO_WRITE = 15 /   LNK_C_OUT_CKUSER   = 2  LNK_C_IN_CKUSER  = 10 /   LNK_C_OUT_TO       = 3  LNK_C_IN_TO      = 11 /   LNK_C_OUT_SUBJ     = 4  LNK_C_IN_SUBJ    = 12 /   LNK_C_OUT_FILE     = 5  LNK_C_IN_FILE    = 13    LNK_C_OUT_CKSEND   = 6   LNK_C_OUT_DEACCESS = 7  L which indicate exactly what function the caller expects.  Because it's oftenJ difficult or impossible to write procedures that handle varying numbers ofF arguments, I wrote a simple dispatcher in MACRO that invokes interfaceI routines with fixed argument lists.  This means that the interface may be M implemented in whatever language the developer likes.  The dispatcher (in the M file MAILSHR.MAR) is completely independent of any foreign mailer, and can be A used to dispatch to several different high-level implementations.   D For complete information on the protocol, see my UUCP_MAIL.PAS code.  5 There are some interesting tidbits I have discovered:   @   MAIL provides routines in the argument list that look like you?   are supposed to call them with error text when something goes @   wrong.  I found it a lot easier to simply use the standard VMS<   message utility and signal errors with a severity level of@   ERROR.  The error message is printed and MAIL recovers control;   and aborts the send.  There may be problems with this not @   working properly under all circumstances (e.g. when mailing toC   multiple addresses, if one of the foreign ones is incorrect, MAIL A   should still attempt to send to the other addresses -- this may A   not work with a signaled error), but until I figure out exactly ?   how to call the error text routines (UTIL$REPORT_IO_ERROR and 7   MAIL$READ_ERROR_TEXT) I will simply signal my errors.   ?   Debugging this is a real trip.  I took a copy of MAIL.EXE and :   used the new PATCH/ABSOLUTE to change the image transfer?   vectors and image activator flags to force it to come up with ;   the debugger.  Then, I assembled a BPT instruction as the :   first thing in the dispatcher so that the debugger got a>   breakpoint trap whenever my dispatcher was called.  You have8   to do this because you cannot set a breakpoint in your@   shareable image until after it's been mapped.  I was then able>   to trace the calls from MAIL.  The file MAIL_DBG.EXE is  theB   patched version of VMS MAIL that will come up with the debugger.  7 	/Kevin Carosso                          April 13, 1985  	 engvax!kvc @ CIT-VAX.ARPA 