   Subj:  VMSMAIL alternate protocol interface                Page 2
   THE ALTERNATE PROTOCOL

   2  PROTOCOL NAMING CONVENTIONS

   As is the convention throughout the rest of VMS, Digital reserves  all
   protocol names containing the "$" character.

   3  ACCESSING THE ALTERNATE PROTOCOL

   3.1  Outgoing MAIL

   MAIL parses the addressee specification provided.  A logical  name  of
   the  form  MAIL$PROTOCOL_pnam is translated in the LNM$FILE_DEV table.
   If this logical name translation succeeds, then the resulting name  is
   used.   If  the translation fails, the name pnam_MAILSHR (PSI_MAILSHR,
   for instance) is used.  In either case, the default file specification
   is  SYS$SHARE:.EXE.   This  alternate protocol shareable image must be
   INSTALLed if MAIL is installed with privilege.



   3.2  Incoming MAIL

   MAIL must be activated as a DCL command with the /PROTOCOL  qualifier.
   The  value  of  this  qualifier  is  the  file  specification  for the
   alternate protocol shareable image (/PROTOCOL=PSISHR, for instance).



   3.3  Image Format

   The alternate protocol shareable  image  must  contain  the  following
   symbols:

         o  MAIL$PROTOCOL - The address of the routine which will service
            the calls from MAIL (described below).

         o  MAIL$C_PROT_MAJOR - This literal value is the  major  version
            of  the  VMSMAIL  alternate  protocol interface.  The current
            value may be 1 or 2.  This is provided so that older protocol
            interfaces  may  still  be  used  in  the  future, should the
            interface change.  Advanced features denoted as  "Version  2"
            items  will be available only if MAIL$C_PROT_MAJOR is defined
            as 2.

         o  MAIL$C_PROT_MINOR - This literal value is the  minor  version
            of  the  VMSMAIL  alternate  protocol interface.  The current
            value is 1.

   Subj:  VMSMAIL alternate protocol interface                Page 2
   ACCESSING THE ALTERNATE PROTOCOL


   3.4  Life After Image Activation

   After MAIL has merged the protocol interface image  into  its  address
   space  by  using  LIB$FIND_IMAGE_SYMBOL,  it  looks  up  the  required
   symbols, and checks that the version is legal.   If  it  is  not,  the
   operation is terminated.

   MAIL then calls the MAIL$PROTOCOL routine within the  shareable  image
   for  the  various functions needed to send a message.  These functions
   are described in the next section.



   4  REQUEST CALLS TO MAIL$PROTOCOL ROUTINE

   4.1  Arguments Passed For All Functions

   There are 2 arguments which are  passed  regardless  of  the  function
   requested.

         o  4(AP) is the address of a longword for the  MAIL$PROTOCOL  to
            use  as  a  context for the current request.  If the protocol
            handler needs any  link-specific  information  (such  as  the
            channel  number,  or  an  internal  index)  it  may  use this
            longword.  MAIL  uses  a  longword  that  is  in  a  per-link
            specific data structure.

         o  8(AP) is the immediate value  of  the  function  to  perform.
            These  functions  and  their values are described in the next
            section.

                                        NOTE

                    These functions basically correspond with the
                    functions  necessary to implement the MAIL-11
                    protocol.  



   4.2  Outbound Connect Function (0)

   This function has 7 additional arguments:

         o  12(ap) - The address of a descriptor of the protocol name  as
            specified by the user.

         o  16(ap) - The  address  of  a  descriptor  of  the  node  name
            requested.

   Subj:  VMSMAIL alternate protocol interface                Page 3
   REQUEST CALLS TO MAIL$PROTOCOL ROUTINE


         o  20(ap) - The immediate value of MAIL$_LOGLINK  which  can  be
            used to signal a connect failure.  This condition value takes
            one argument, which is the address of a string descriptor  of
            the node name.

         o  24(ap) - The  immediate  value  of  the   record   attributes
            (FAB$B_RAT) of the message file.

         o  28(ap) - The immediate value of the record format (FAB$B_RFM)
            of the message file.

         o  32(ap) - The immediate value of the high sixteen bits of  the
            binary value of the logical name MAIL$SYSTEM_FLAGS).

         o  36(ap) - 0 or the address of a descriptor of  the  attachment
            file.   Use  of  this  without  consulting  with  the VMSmail
            maintainer is strongly discouraged.

         o  40(ap) - The immediate value of the "system" attribute  flags
            longword.  The flags are defined as follows:

             -  Bit 0  -  The message to be sent is "foreign" to  VMSmail
                and  should  be  stored in an external file regardless of
                the message size.



   This is the first request that will be made of the alternate  protocol
   handler  to  process  an  outbound  addressee.   If,  for  example,  a
   connection must be made to a remote node,  this  procedure  must  make
   that connection.

   Note that if the to-list contains more than one  addressee  using  the
   same  protocol (and node name, if specified), this procedure will only
   be called once, in accordance with the mail-11 protocol.



   4.3  Sender's Username (1)

   This function has two additional arguments:

         o  12(ap) - The address of a descriptor  of  the  (remote)  node
            name.

         o  16(ap) - The address of a descriptor of the sender's name.


   This procedure  must  accept  the  sender's  username  descriptor  for
   transmission  to  the  recipient.  The sender's name will not have the
   current nodename prefixed, that is expected to be done by the receiver
   (MAIL-11  protocol).   Note,  however,  that  it will contain any
   previous nodenames, should this be forwarded mail.

   Subj:  VMSMAIL alternate protocol interface                Page 4
   REQUEST CALLS TO MAIL$PROTOCOL ROUTINE


   The sender's name will only be sent once per node, even if  there  are
   more than one addressee using a particular protocol.



   4.4  Check Addressee (2)

   This function has three additional arguments:

         o  12(ap) - The address of a descriptor of the node name.

         o  16(ap) - The address of a descriptor of the addressee.

         o  20(ap) - The address of the error routine to read the text of
            the sent-back error.


   This procedure accepts the addressee specification and  validates  it.
   If  the  validation  is  deferred,  this  routine should always return
   success.

   A username consisting of a single byte of 0 will signal the end of the
   addressee checking phase of the mail-11 protocol.

   If there is an error in the address checking, then this procedure must
   call  back  to  mail (via @20(ap)) with the address of a routine which
   will provide the error text.  



   4.5  Send "to" String (3)

   This function has two additional arguments:

         o  12(ap) - The address of a descriptor of the node name.

         o  16(ap) - The address of a descriptor of the "to" string.


   This procedure accepts the original 'to' string, as typed by the user.



   4.6  Send "CC" String (17) (Version 2)

   This function has two additional arguments:

         o  12(ap) - The address of a descriptor of the node name.

         o  16(ap) - The address of a descriptor of the "CC" string.


   Subj:  VMSMAIL alternate protocol interface                Page 5
   REQUEST CALLS TO MAIL$PROTOCOL ROUTINE


   This procedure accepts the original 'CC' string, as typed by the user.



   4.7  Send "subject" String (4)

   This function has two additional arguments:

         o  12(ap) - The address of a descriptor of the node name.

         o  16(ap) - The address of a descriptor of the "subject" string.


   This procedure accepts the subject string of the message being sent.



   4.8  Send Message Attributes (19) (Version 2)

   This function has two additional arguments:

         o  12(ap) - The immediate value of the "system" attribute  flags
            longword.  The flags are defined as follows:

             -  Bit 0  -  The message to be sent is "foreign" to  VMSmail
                and  should  be  stored in an external file regardless of
                the message size.


         o  16(ap) - The address of the TLD structure which describes the
            attributes  of  a  "foreign"  message.   See appendix C for a
            description of the TLD attributes.




   4.9  Send Message Text (5)

   This function has three additional arguments:

         o  12(ap) - The address of a descriptor of the node name.

         o  16(ap) - The address of a rab of the open message file.

         o  20(ap) - The address of an RMS error routine for the  message
            file.


   This procedure must check RAB$V_BIO in the  RAB  to  ensure  that  the
   record processing on the input file will be as desired.  If it is not,
   then $disconnect, set/clear RAB$V_BIO as appropriate, and $connect.

   Subj:  VMSMAIL alternate protocol interface                Page 6
   REQUEST CALLS TO MAIL$PROTOCOL ROUTINE


   The error routine (@20(ap)) which is provided may be used in two ways.
   In  both  cases,  it  expects a condition code in the CTX field of the
   FAB/RAB, such as OPENIN, OPENOUT, READERR, WRITEERR, etc.   These  are
   the  shared  messages ($SHRMSG) and must be used.  One way to use this
   routine is as the ERR= argument to an RMS service call.  The other  is
   to explicitly call the routine, passing either a FAB or RAB address as
   the argument.



   4.10  Check Status Of Sending To One User (6)

   This routine is called with three additional arguments:

         o  12(ap) - The address of a descriptor of the nodename.

         o  16(ap) - The address of a descriptor of the username.

         o  20(ap) - The address of an error routine to read the response
            in case not success.


   After the message text has been sent, MAIL will check  the  status  of
   sending to the addressees, in the same order they were address-checked
   before sending.

   If there is an error in the address checking, then this procedure must
   call  back  to  mail (via @20(ap)) with the address of a routine which
   will provide the error text.  



   4.11  Deaccess (7)

   There are no function dependent parameters.

   This procedure should do any cleanup desired, the outbound  connection
   is terminated.



   4.12  Accept Inbound Connect (8)

   There are six additional parameters:

         o  12(ap) - The address of a descriptor of  the  translation  of
            SYS$NET.

         o  16(ap) - The address of a longword in  which  to  return  the
            record attributes of the incoming message (FAB$B_RAT).

         o  20(ap) - The address of a longword in  which  to  return  the
            record format of the incoming message (FAB$B_RFM).

   Subj:  VMSMAIL alternate protocol interface                Page 7
   REQUEST CALLS TO MAIL$PROTOCOL ROUTINE


         o  24(ap) - The immediate value of the high sixteen bits of  the
            translation of MAIL$SYSTEM_FLAGS.

         o  28(ap) - The  address  of  a  descriptor  of  the   /protocol
            qualifier value when mail was invoked.

         o  32(ap) - The address of a longword in which to return control
            flags to mail.  Flags:

             -  Bit 0  -  Continuously loop in the inbound  mail  server.
                If  this  flag  is not set, MAIL will exit after a single
                message has been processed.   Setting  this  flag  causes
                MAIL  to loop after completing the delivery of a message.
                MAIL will  recall  the  MAIL$PROTOCOL  routine  with  the
                'connect for inbound mail' function again.



   This procedure is responsible for accepting the  incoming  connection,
   and  redefining  the  translation of SYS$NET so that MAIL will use the
   correct remote node name.  The descriptor for SYS$NET that  is  passed
   has  the  length  field  describing  the  length of the translation of
   SYS$NET.  The address field points to a  buffer  which  contains  that
   description.   The  total  length  of  the  buffer  is 2*NAM$C_MAXRSS.
   Redefining the translation of SYS$NET (to at least  put  the  protocol
   specification  in  to allow return mail) involves copying a new string
   into the buffer described by the SYS$NET descriptor and  then  setting
   the length in the descriptor.



   4.13  Accept Sender's Name (9)

   This routine has 1 additional argument:

         o  12(ap) - The address of a dynamic string descriptor in  which
            to  return  the  sender's  name.   Copy  using STR$COPY_DX or
            similar.




   4.14  Accept Addressee And Check For Existence (10)

   This routine has 1 additional argument:

         o  12(ap) - The address of a dynamic string descriptor in  which
            to  return  the  addressee's name.  Copy using STR$COPY_DX or
            similar.


   If MAIL detects an error in checking  the  address  specification,  it
   will  SIGNAL the error.  This will result in the failure error text to
   be passed through the write record procedure in  accordance  with  the

   Subj:  VMSMAIL alternate protocol interface                Page 8
   REQUEST CALLS TO MAIL$PROTOCOL ROUTINE


   MAIL-11 protocol.  



   4.15  Accept "to" List (11)

   This routine has 1 additional argument:

         o  12(ap) - The address of a dynamic string descriptor in  which
            to return the "to" list.  Copy using STR$COPY_DX or similar.




   4.16  Accept "CC" List (16) (Version 2)

   This routine has 1 additional argument:

         o  12(ap) - The address of a dynamic string descriptor in  which
            to return the "CC" list.  Copy using STR$COPY_DX or similar.




   4.17  Accept "subject" List (12)

   This routine has 1 additional argument:

         o  12(ap) - The address of a dynamic string descriptor in  which
            to  return  the  message  subject.  Copy using STR$COPY_DX or
            similar.




   4.18  Accept Message Attributes (18) (Version 2)

   This function has two additional arguments:

         o  12(ap) - The address of the longword in which to  return  the
            "system" attribute flags.  The flags are defined as follows:

             -  Bit 0  -  The message to be sent is "foreign" to  VMSmail
                and  should  be  stored in an external file regardless of
                the message size.


         o  16(ap) - The address of the TLD structure which describes the
            attributes  of  a  "foreign"  message.   See appendix C for a
            description of the TLD attributes.


   Subj:  VMSMAIL alternate protocol interface                Page 9
   REQUEST CALLS TO MAIL$PROTOCOL ROUTINE


   4.19  Accept Message Text (13)

   This routine has 3 additional arguments:

         o  12(ap) - Not used.  Here  for  symmetry  with  'send  message
            text'.

         o  16(ap) - The address of a RAB opened for the output file.

         o  20(ap) - The address of an error routine for  RMS  errors  on
            the  output  file.   See  the  discussion under 'send message
            text'.




   4.20  Read A Single Record (14) (currently Not Used)

   This routine has 1 additional argument:

         o  12(ap) - The address of a descriptor of a buffer in which  to
            read the record.




   4.21  Write A Single Record (15)

   This routine has 1 additional argument:

         o  12(ap) - The address of a string descriptor for the record to
            write.


   MAIL uses this function to pass back status and  error  text  to  your
   alternate  protocol  routines,  as  described  in  section 3.  If your
   interface requires more extensive context than the mail-11 protocol (a
   store/forward  mailer,  for  instance)  you  may need to keep track of
   where you are in processing the protocol so that when this function is
   called, you know what to do with the data provided.

   This is one part of the interface that would be a prime candidate  for
   extensive  enhancements  in  a  future  release.  However, the current
   internal  structure  of  MAIL  made  any  reasonable  interface  quite
   difficult.



   5  ADDITIONAL NOTES ON THE INTERFACE

   The functions 'check addressee',  'check  status  of  sending  to  one
   user',   and  'accept  addressee  and  check  for  existence'  require
   additional explanation.

   Subj:  VMSMAIL alternate protocol interface               Page 10
   ADDITIONAL NOTES ON THE INTERFACE


   5.1  Check Addressee

   If the addressee check succeeds, this routine should  return  success.
   MAIL will SIGNAL a status of 1, which will result in the 'write single
   record' routine being called with the status.

   If the addressee check fails, this procedure should call  the  routine
   specified   @20(ap)  to  retrieve  the  records  of  the  error  text,
   terminated by a record of a byte of 0.  If MAIL is running as a  slave
   mail  (inbound mail processing), MAIL then calls 'write single record'
   routine with the error text records.  If MAIL is being run as a master
   mail  (outbound  mail  processing,  typically an interactive user) the
   text will be displayed to SYS$OUTPUT:.



   5.2  Check Status Of Sending To One User

   If the remote node  reports  success,  this  procedure  should  return
   success.   MAIL  will  SIGNAL success which results in a longword of 1
   being passed to 'write single record'  (if  in  server  mode),  or  to
   SYS$OUTPUT (if run in non-server mode).

   If the remote node reports an error, this procedure  should  call  the
   routine  specified  @20(ap) to retrieve the records of the error text,
   terminated by a record of a byte of 0.  MAIL then calls 'write  single
   record' routine with the error text records (if in server mode), or to
   SYS$OUTPUT (if run in non-server mode).



   5.3  Accept Addressee And Check For Existence

   This procedure returns the  addressee  specification  to  MAIL.   Mail
   processes  it  as  a  normal  addressee specification, and will SIGNAL
   either a success or failure (longword of 1  or  error  status),  which
   will  result  in  'write single record' being called.  MAIL then calls
   'write single record' with the error text records, terminated  with  a
   null.



   5.4  The Error Message Reading Routine

   This routine (used by 'check status of sending' and 'check addressee')
   is  called with two arguments.  The first is a context longword, which
   may be anything the  protocol  handler  wishes.   The  second  is  the
   address of a routine to return the next error text record.

   This routine is called with two arguments.  The first is  the  context
   passed  to  the  error  message reading routine, and the second is the
   address of a descriptor of a buffer.  This routine  should  place  the
   text  in  the  specified  buffer,  and  modify the length field in the
   descriptor to reflect its actual length.

   Subj:  VMSMAIL alternate protocol interface               Page 11
   ANOTHER METHOD OF INTERFACING TO MAIL FOR OUTBOUND MESSAGES


   6  ANOTHER METHOD OF INTERFACING TO MAIL FOR OUTBOUND MESSAGES

   As an alternative, you may interface to MAIL in the following manner:

           $ define pseudonode gateway%
           $ define mail$protocol_gateway "%anode::""TASK=cfile"

   For instance,

           $ define decwrl decwrlgate%::
           $ define MAIL$PROTOCOL_DECWRLGATE "%RHEA::""TASK=MAILGATE"
           $ mail testmsg decwrl::lipman /subj="here is a test"


                                    NOTE

           It is extremely important that you get the  number  of
           quotation marks correct.


   Use of this method causes MAIL to do a normal DECnet  connect  to  the
   specified  node/command procedure.  In this method, MAIL speaks normal
   MAIL-11 protocol to the slave receiver.

