MULTICS TECHNICAL BULLETIN                                MTB-613

To:       MTB Distribution

From:     Gary M.  Palter

Date:     1 June 1983

Subject:  Multics Mail System Programmer's Reference Manual

     This  MTB  is  the  Programmer's  Reference  Manual  for the
Multics  Mail  System.   This  manual  contains  all  information
necessary  to  write  application  programs  or  subsystems which
interface to the mail system.

     This  MTB documents  the programmer's interface  to the mail
system as it will appear in the MR10.2 release.  It is being made
available at this time to allow the conversion of Emacs RMAIL and
the Extended Mail Facility to the interface in MR10.2.

Please direct any comments on this documentation to the author

     by electronic mail to:

          Gary M.  Palter <GMP@MIT-Multics.ARPA>

     by the forum teleconferencing system to the meeting:

          >udd>Multics>Palter>forums>Mail_System on System-M

     or by the U.S.  Postal service to:

          Honeywell Information Systems, CISL
          575 Technology Square
          Cambridge, Mass.  02139

_________________________________________________________________

Multics  Project  internal  working  documentation.   Not  to  be
distributed outside the project without the consent of the author
or the Director of Multics System Development.


MTB-613         Mail System Programmer's Reference        MTB-613

                             CONTENTS

                                                            Page

Section 1     Mail System Objects  . . . . . . . . . .      1-1
                    Constraints on the Use of Mail
                     System Objects  . . . . . . . . .      1-1
                 Addresses . . . . . . . . . . . . . .      1-1
                    Address Types  . . . . . . . . . .      1-2
                    Address Names  . . . . . . . . . .      1-4
                    Address Comments . . . . . . . . .      1-4
                    Address Routes . . . . . . . . . .      1-4
                       The address_route Structure . .      1-5
                    Printed Representations of an
                     Address . . . . . . . . . . . . .      1-6
                       Printed Representation of an
                        Address Name . . . . . . . . .      1-8
                       Printed Representation of an
                        Address Comment  . . . . . . .      1-8
                       Printed Representation of an
                        Address Route  . . . . . . . .      1-8
                       Special Characters  . . . . . .      1-9
                    Control Argument Representations
                     of an Address . . . . . . . . . .      1-9
                 Address Lists . . . . . . . . . . . .      1-11
                    The address_list Structure . . . .      1-12
                    Printed Representation of an
                     Address List  . . . . . . . . . .      1-12
                 Messages  . . . . . . . . . . . . . .      1-12
                    The message Structure  . . . . . .      1-13
                    The message_envelope Structure . .      1-18
                       The message_trace Structure . .      1-19
                    The message_redistributions_list
                     Structure . . . . . . . . . . . .      1-21
                       The message_redistribution
                        Structure  . . . . . . . . . .      1-22
                    The message_user_fields_list
                     Structure . . . . . . . . . . . .      1-23
                       The message_user_field
                        Structure  . . . . . . . . . .      1-24
                          Type Specific
                           message_user_field
                           Structures  . . . . . . . .      1-25
                       Canonicalization of
                        User-Defined Field Names . . .      1-26
                    The message_references_list
                     Structure . . . . . . . . . . . .      1-27
                       The message_reference Structure      1-28
                    The message_text_field Structure .      1-28
                    The message_body_section Structure      1-29


MTB-613         Mail System Programmer's Reference        MTB-613

                                                            Page

                       Type Specific
                        message_body_section
                        Structures . . . . . . . . . .      1-30
                    Printed Representation of a
                     Message . . . . . . . . . . . . .      1-31
                       Printed Representation of the
                        Message Envelope . . . . . . .      1-32
                          Printed Representation of a
                           Message Trace . . . . . . .      1-33
                       Printed Representation of the
                        Message Header . . . . . . . .      1-34
                       Printed Representation of the
                        Redistributions List . . . . .      1-37
                       Printed Representation of the
                        Message Body . . . . . . . . .      1-38
                 Mailboxes . . . . . . . . . . . . . .      1-38
                    The mailbox Structure  . . . . . .      1-39

Section 2     Subroutines  . . . . . . . . . . . . . .      2-1
                    mail_system_ . . . . . . . . . . .      2-2
                       abort_delete_operation  . . . .      2-2
                       acknowledge_message . . . . . .      2-3
                       add_address . . . . . . . . . .      2-5
                       add_body_section  . . . . . . .      2-6
                       add_reply_reference . . . . . .      2-8
                       add_user_field  . . . . . . . .      2-9
                       close_mailbox . . . . . . . . .      2-12
                       compare_addresses . . . . . . .      2-14
                       create_address_list . . . . . .      2-15
                       create_foreign_address  . . . .      2-16
                       create_forum_address  . . . . .      2-18
                       create_invalid_address  . . . .      2-19
                       create_logbox_address . . . . .      2-20
                       create_mail_table_address . . .      2-21
                       create_mailbox_address  . . . .      2-23
                       create_mailing_list_address . .      2-24
                       create_message  . . . . . . . .      2-25
                       create_named_group_address  . .      2-26
                       create_savebox_address  . . . .      2-28
                       create_user_mailbox_address . .      2-29
                       delete_address  . . . . . . . .      2-31
                       delete_body_section . . . . . .      2-32
                       delete_reply_reference  . . . .      2-33
                       delete_user_field . . . . . . .      2-34
                       deliver_message . . . . . . . .      2-35
                       expand_list_address . . . . . .      2-51
                       expunge_messages  . . . . . . .      2-53
                       free_address  . . . . . . . . .      2-56
                       free_address_list . . . . . . .      2-56
                       free_message  . . . . . . . . .      2-57


MTB-613         Mail System Programmer's Reference        MTB-613

                                                            Page

                       get_address_comment . . . . . .      2-58
                       get_address_name  . . . . . . .      2-59
                       get_address_pathname  . . . . .      2-60
                       get_address_route . . . . . . .      2-61
                       get_address_string  . . . . . .      2-62
                       get_address_system  . . . . . .      2-63
                       get_address_type  . . . . . . .      2-64
                       get_mail_table_address  . . . .      2-65
                       get_message_counts  . . . . . .      2-66
                       get_user_field_id . . . . . . .      2-67
                       get_user_field_name . . . . . .      2-68
                       log_message . . . . . . . . . .      2-69
                       mark_message_for_deletion . . .      2-71
                       merge_address_lists . . . . . .      2-72
                       open_mailbox  . . . . . . . . .      2-73
                       read_message  . . . . . . . . .      2-77
                       read_new_messages . . . . . . .      2-78
                       redistribute_message  . . . . .      2-79
                       replace_address . . . . . . . .      2-81
                       replace_body  . . . . . . . . .      2-82
                       replace_body_section  . . . . .      2-83
                       replace_reply_reference . . . .      2-85
                       replace_subject . . . . . . . .      2-87
                       replace_user_field  . . . . . .      2-88
                       save_message  . . . . . . . . .      2-90
                       set_access_class  . . . . . . .      2-92
                       unmark_message_for_deletion . .      2-93
                       validate_address  . . . . . . .      2-94
                    mlsys_info_  . . . . . . . . . . .      2-95
                       user_default_mailbox_address  .      2-96
                       user_logbox_address . . . . . .      2-96
                       user_mail_table_address . . . .      2-97
                    mlsys_utils_ . . . . . . . . . . .      2-98
                       add_mailbox_acl_entries . . . .      2-98
                       create_default_mailbox  . . . .      2-101
                       create_logbox . . . . . . . . .      2-102
                       create_mailbox  . . . . . . . .      2-103
                       create_reply_message  . . . . .      2-104
                       create_savebox  . . . . . . . .      2-107
                       delete_mailbox  . . . . . . . .      2-108
                       delete_mailbox_acl_entries  . .      2-111
                       format_access_class_field . . .      2-113
                       format_address_field  . . . . .      2-115
                       format_address_list_field . . .      2-117
                       format_body_section . . . . . .      2-118
                       format_date_time_field  . . . .      2-121
                       format_message  . . . . . . . .      2-122
                       format_message_body . . . . . .      2-126
                       format_message_envelope . . . .      2-127
                       format_message_header . . . . .      2-129


MTB-613         Mail System Programmer's Reference        MTB-613

                                                            Page

                       format_message_id_field . . . .      2-131
                       format_message_redistributions_list  2-133
                       format_message_references_list_field 2-135
                       format_message_trace  . . . . .      2-137
                       format_text_field . . . . . . .      2-139
                       list_mailbox_acl  . . . . . . .      2-141
                       parse_address_control_arguments      2-143
                       parse_address_list_control_arguments 2-147
                       parse_address_list_text . . . .      2-153
                       parse_address_text  . . . . . .      2-157
                       parse_mailbox_control_arguments      2-159
                       parse_message_text  . . . . . .      2-164
                       print_access_class_field  . . .      2-168
                       print_address_field . . . . . .      2-170
                       print_address_list_field  . . .      2-171
                       print_body_section  . . . . . .      2-172
                       print_date_time_field . . . . .      2-174
                       print_delivery_results  . . . .      2-176
                       print_message . . . . . . . . .      2-178
                       print_message_body  . . . . . .      2-181
                       print_message_envelope  . . . .      2-182
                       print_message_header  . . . . .      2-183
                       print_message_id_field  . . . .      2-185
                       print_message_redistributions_list   2-186
                       print_message_references_list .      2-188
                       print_message_trace . . . . . .      2-189
                       print_text_field  . . . . . . .      2-191
                       replace_mailbox_acl_entries . .      2-192
                       search_message  . . . . . . . .      2-195
                       send_message_to_recipient . . .      2-198
                       summarize_address . . . . . . .      2-200


MTB-613         Mail System Programmer's Reference        MTB-613

                            SECTION 1

                       MAIL SYSTEM OBJECTS

     The programmer's interface to the Multics Mail System allows
for  the  construction,  transmission,  and  examination  of mail
messages.   This  section  defines  the  structure  of addresses,
address  lists,  messages,  and  mailboxes  as  presented  to the
programmer by the mail system.

Constraints on the Use of Mail System Objects

     Unless   explicitly  stated   to  the   contrary,  all  data
structures  described  in  this  section  should  be  treated  as
read-only by the application or subsystem.  In addition, programs
should not create or free  these data structures except via calls
to the appropriate entrypoints in the mail system.

     Several of the data structures used to represent mail system
objects  contain arrays  with variable extents.   The mail system
provides entrypoints  to add or  delete items from  these arrays.
As these  operations require reallocation of  the containing data
structure,  these entrypoints  will normally change  the value of
the pointer  supplied by the  caller.  The caller  is responsible
for updating the values of any  copies of said pointer that it is
maintaining.  For this reason, it  is recommended that the caller
maintain only one copy of the pointer if possible.

ADDRESSES

     An  address  identifies an  originator or  a recipient  of a
message.   A single  address refers to  one of  the following:  a
Multics mailbox either by pathname or User_id, a Forum meeting, a
user (or group of users) on  another computer system, an entry in
the system's mail table, or a mailing list.

     The  actual data  structures which represent  an address are
internal  to the  operation of  the mail  system.  Subsystems and
application programs  reference an address  by a pointer  to this
internal representation; as far  as these programs are concerned,
the pointer is the address.  Entrypoints are provided by the mail
system to determine  the type of a given  address, to compare two
addresses  for  equality,  to   construct  addresses  from  their
component parts, to  examine the parts of an  address, to convert
an address  to/from its printed representation,  and to convert a
command/request's control arguments into one or more addresses.


MTB-613         Mail System Programmer's Reference        MTB-613

Address Types

     The  type  of  an  address   is  determined  by  a  call  to
mail_system_$get_address_type.   The possible  values returned by
that entrypoint are given by  the following named constants which
are declared in the include file mlsys_address_types.incl.pl1:

USER_MAILBOX_ADDRESS
          identifies a user's default  mailbox.  A user's default
          mailbox has the pathname --
               >udd>Project_id>Person_id>Person_id.mbx
          The User_id of the owner of the mailbox may be obtained
          via  a  call  to  mail_system_$get_address_string;  the
          pathname of the  mailbox may be obtained via  a call to
          mail_system_$get_address_pathname.

LOGBOX_ADDRESS
          identifies  a user's  logbox.  A user's  logbox has the
          pathname --
               >udd>Project_id>Person_id>Person_id.sv.mbx
          The User_id of the owner  of the logbox may be obtained
          via  a  call  to  mail_system_$get_address_string;  the
          pathname of  the logbox may  be obtained via  a call to
          mail_system_$get_address_pathname.

SAVEBOX_ADDRESS
          identifies a user's savebox.   A savebox is any mailbox
          with a suffix of sv.mbx.    The User_id of the owner of
          the   savebox   may   be   obtained  via   a   call  to
          mail_system_$get_address_string;  the  pathname  of the
          savebox    may    be   obtained    via   a    call   to
          mail_system_$get_address_pathname.

MAILBOX_ADDRESS
          identifies  an  arbitrary  mailbox  by  pathname.   The
          pathname of the  mailbox may be obtained via  a call to
          mail_system_$get_address_pathname.

FORUM_ADDRESS
          identifies a  forum meeting by  pathname.  The pathname
          of  the   meeting  may  be  obtained   via  a  call  to
          mail_system_$get_address_pathname.

FOREIGN_ADDRESS
          idenitifies  a  user  (or  group of  users)  on another
          computer  system.   A  foreign address  consists  of an
          arbitrary character string which  is the address on the
          foreign system, the name of  the foreign system, and an
          optional  route  to  be  used to  deliver  mail  to the
          address.  The  three parts of a  foreign address may be
          obtained via  calls to mail_system_$get_address_string,


MTB-613         Mail System Programmer's Reference        MTB-613

          mail_system_$get_address_system,                    and
          mail_system_$get_address_route, respectively.

MAIL_TABLE_ADDRESS
          identifies  an entry  in the system's  mail table.  The
          mail table  is a system-wide database  which provides a
          translation between an arbitrary character string and a
          mail system address.  The  mail table contains an entry
          for each Person_id (and alias) registered on the system
          in order to  allow a user to send  mail to another user
          without having  to know on  what projects that  user is
          registered.   In addition,  the mail  table may contain
          entries  for  system-wide  mailing  lists  and/or users
          whose mail  is to be forwarded  to another system.  The
          name of the  mail table entry for this  type of address
          may     be      obtained     via     a      call     to
          mail_system_$get_address_string;  the   actual  address
          from  the  mail table  may  be obtained  via a  call to
          mail_system_$get_mail_table_address.

MAILING_LIST_ADDRESS
          identifies a mailing list  by pathname.  A mailing list
          is  an  ASCII  segment  or archive  component  with the
          suffix mls  which contains the  printed representations
          (see  below)  of one  or  more addresses.   If multiple
          addresses  are given  on a  single line  in the mailing
          list,  they must  be separated by  commas; however, the
          comma at the  end of a line is  optional.  When mail is
          sent to a mailing list, it  is delivered to each of the
          addresses  in the  list.  The  pathname of  the mailing
          list    may    be    obtained    via    a    call    to
          mail_system_$get_address_pathname;  the actual  list of
          addresses   may    be   obtained   via    a   call   to
          mail_system_$expand_list_address.

NAMED_GROUP_ADDRESS
          identifies a  named group of addresses.   A named group
          is distinguished  from a mailing list  by the fact that
          the  individual  addresses  which  comprise  the  group
          appear  in  the printed  representation of  the address
          whereas only the pathname of  a mailing list appears in
          its  printed  representation.   Usually,  this  type of
          address is only found in messages which were created on
          another computer system.  The name  of the group may be
          obtained  via a  call to mail_system_$get_address_name;
          the actual list of addresses may be obtained via a call
          to mail_system_$expand_list_address.

INVALID_ADDRESS
          identifies an invalid address.  An invalid address will
          be created  by those entrypoints  which convert printed
          representations of addresses, etc.  into their internal


MTB-613         Mail System Programmer's Reference        MTB-613

          representation  if  requested by  their callers  when a
          character string  is found in  the printed presentation
          which  does  not  correspond  to any  of  the  types of
          address supported  by the mail system.   Any attempt to
          send  mail to  an invalid  address will,  of course, be
          detected  as an  error.  The character  string which is
          the  invalid  address may  be  obtained via  a  call to
          mail_system_$get_address_string.

Address Names

     The address name, which is an  optional part of all types of
addresses, is a character string  which identifies the person who
receives mail at a given  address.  Normally, the address name is
the  individual's full  name; however, in  the case  of a mailing
list or named group, the address  name is a global description of
the  individual addresses  within the list.   On some non-Multics
systems, several  persons are allowed to  share a single address;
in these cases, the system uses the address name to determine for
which of these individuals a given message is intended.

     The address name  of any address may be  obtained via a call
to mail_system_$get_address_name.

Address Comments

     The address comment, which is  an optional part of all types
of addresses, is a character string with no semantic meaning that
may  be  associated  with  an address.   Although  now considered
obsolete,  the  address comment  is still  supported by  the mail
system  to  provide compatibility  with  prior releases  and with
non-Multics systems  that still use the  address comment in place
of the address name.

     The  address comment  of any address  may be  obtained via a
call to mail_system_$get_address_comment.

Address Routes

     As mentioned  briefly above in  the definition of  a foreign
address,  a foreign  address may  include an  address route.  The
address route defines the path  through the network(s) which must
be  taken in  order to  deliver a  piece of  mail to  the foreign
system.  The address  route is represented as an  ordered list of
system names.  A message is sent by the local system to the first
system in  the route; that  system then sends the  message to the
second system  in the route,  etc.  until the  message arrives at
its destination.


MTB-613         Mail System Programmer's Reference        MTB-613

     The  mail system  will compute the  address route associated
with a  given foreign address  at the time that  mail is actually
sent  to that  address.  However, a  foreign address  may have an
address route  associated with it  before it is  actually used as
the recipient of a message.  If such an address route is present,
it is either an explicit route or an implicit route.

     An  explicit  route  is  the address  route  which  has been
specifically requested by a user to be used for the given foreign
address.  An explicit route is normally used to instruct the mail
system how it should deliver mail  to a system for which it would
not be able to compute an address route.  However, if present, an
explicit route will  always be used by the  mail system even when
its internal routing algorithms could  compute a shorter route to
the destination system.

     An  implicit route  is the  address route  associated with a
message that  originated on a foreign  system.  When requested to
deliver a message  to one of the addresses  given in the original
message (eg:   via the read_mail reply  request), the mail system
will attempt to compute an address route for the address.  If the
address  route computation  fails, the  mail system  will use the
implicit route as the address route for the address.

THE ADDRESS_ROUTE STRUCTURE

     The following  structure and named constants  are defined in
the include file mlsys_address_route.incl.pl1:

     dcl 1 address_route aligned based (address_route_ptr),
           2 header,
             3 version   character (8) unaligned,
             3 reserved  bit (144),
             3 flags,
               4 implicit_route
                         bit (1) unaligned,
               4 reserved
                         bit (35) unaligned,
             3 n_relays  fixed binary,
           2 relays      (address_route_n_relays refer
                         (address_route.n_relays))
                         character (256) varying;

where:

version   is the current version of this structure.  This version
          of  the structure  is given by  the value  of the named
          constant ADDRESS_ROUTE_VERSION_1.

reserved  is reserved exclusively for use by the mail system.


MTB-613         Mail System Programmer's Reference        MTB-613

flags.implicit_route
          if  "1"b,  specifies  that  this  address  route  is an
          implicit  route  as  described  above;  otherwise, this
          route  is  an explicit  route  which is  also described
          above.

flags.reserved
          is reserved exclusively for use by the mail system.

n_relays  is the number of relay systems in the address route.

relays    is the list  of relay systems.  The system  name in the
          first element  of this array  is the primary  name of a
          system   as  given   in  the   local  system's  network
          information table (NIT).  The remaining system names in
          this list need not appear in the local system's NIT.

Printed Representations of an Address

     The  printed  representation  of  an  address  is  the human
readable  form of  that address.  It  is used by  the mail system
when  displaying a  message or  searching a  message for  a given
character string.

     In   the  following   printed  representations,  braces ({})
actually  appear  as  part  of  the  printed  representation  and
brackets ([])  are  used to  denote optional  parts of  a printed
representation.   The  printed representations  used by  the mail
system are:

Person_id.Project_id
          identifies either a user's default mailbox --
               >udd>Project_id>Person_id>Person_id.mbx
          or a user's logbox --
               >udd>Project_id>Person_id>Person_id.sv.mbx
          Any  use of  this printed  representation to  create an
          address   will  create   an  address   referencing  the
          specified user's default mailbox rather than his logbox
          to insure  that other users will  never attempt to send
          mail  directly to  his logbox.   (By default,  only the
          user  can add  messages to his  logbox.)  However, when
          constructing a new message for later delivery, the mail
          system will use the  {logbox} format described below to
          represent   the   user's    logbox.    This   alternate
          representation allows  the user to  distinguish between
          his mailboxes in case he needs to change where his copy
          of the message will be delivered.

{logbox}  appears  only  in  the  printed  representation  of new
          messages and identifies the user's logbox --
               >udd>Project_id>Person_id>Person_id.sv.mbx


MTB-613         Mail System Programmer's Reference        MTB-613

          When  the  message is  actually delivered,  the printed
          representation of this address will be converted to the
          Person_id.Project_id format described above.

Person_id.Project_id (STR.sv)
          identifies a savebox belonging to the specified user.
          STR  is  the  entryname  of the  savebox  excluding the
          sv.mbx suffix.  Any use  of this printed representation
          to create an address will create an address referencing
          the  specified user's  default mailbox  rather than his
          savebox to  insure that other users  will never attempt
          to  send mail  directly to  his savebox.   (By default,
          only  the   user  can  add  messages   to  one  of  his
          saveboxes.)  However,  when constructing a  new message
          for  later  delivery,  the  mail  system  will  use the
          {save path} format described below  to represent one of
          the  user's  saveboxes.  This  alternate representation
          allows the user to distinguish between his mailboxes in
          case he needs  to change where his copy  of the message
          will be delivered.

{save path}
          appears  only  in  the  printed  representation  of new
          messages  and  identifies  a  savebox.     Path  is the
          absolute pathname  of the savebox  excluding the sv.mbx
          suffix.   When the  message is  actually delivered, the
          printed   representation  of   this  address   will  be
          converted   to   the   Person.Project (STR.sv)   format
          described above.

{mbx path}
          identifies an arbitrary mailbox  by pathname.   Path is
          the absolute pathname of  the mailbox excluding the mbx
          suffix.

{forum path}
          identifies a  Forum meeting by pathname.    Path is the
          absolute pathname of the  meeting excluding the control
          suffix.

STR at FSystem [address-route]
          identifies an address on another computer system.   STR
          identifies the user (or group  of users) to receive the
          message and is not innterpreted in any way by the local
          system.    FSystem  is the  name of  the foreign system
          where  the   address  is  located.    If  the  optional
          address-route  is  not  present,  FSystem  will  be the
          primary name of the foreign  system as specified in the
          local   system's   network   information   table (NIT).
          However, if an address-route  is specified, the foreign
          system  name does  not have  to be  known to  the local


MTB-613         Mail System Programmer's Reference        MTB-613

          system.  The printed representation of an address route
          is described below.

STR       identifies an  entry in the system's  mail table.   STR
          is   the   name   of   the  mail   table   entry.   The
          display_mailing_address command may  be used to display
          the actual address corresponding to this STR.

{list path}
          identifies a  mailing list by  pathname.   Path  is the
          absolute  pathname  of  the  mailing  list  segment  or
          archive component excluding the mls suffix.

STR: [addresses];
          identifies  a named  group of  addresses.    STR is the
          name  of  the  group.   If present,  addresses  are the
          printed representation of  the addresses which comprise
          the group and are separated by commas.

{invalid STR}
          identifies an invalid address.   STR is the text of the
          invalid address as it  appeared in the original message
          or address list.

PRINTED REPRESENTATION OF AN ADDRESS NAME

     When present, the address name  is placed before the printed
representation  of the  address which  is then  enclosed in angle
brackets ("<" and ">").

     For example:

          Site Administrators <{list >udd>ssa>SiteSAs}>
          Gary M. Palter <Palter.Multics>

PRINTED REPRESENTATION OF AN ADDRESS COMMENT

     When present, the address comment is enclosed in parentheses
and is placed after the printed representation of the address.

     For example:

          Palter.Multics (Gary M. Palter)
          Gary M. Palter <Palter.Multics (Mail system maintainer)>

PRINTED REPRESENTATION OF AN ADDRESS ROUTE

     The printed representation of an address route is:


MTB-613         Mail System Programmer's Reference        MTB-613

[via RelayN ...] via Relay1
          where  Relay1 is  the name of  a foreign  system in the
          local system's network  information table (NIT) and the
          remaining relay  names, if any, need  not appear in the
          NIT.   Mail directed  to an  address with  this address
          route  will be  forwarded to  the system  identified as
          Relay1.   From there, it will be forwared to the system
          identified as Relay2, etc.  until it reaches the system
          identified as RelayN where it  will be delivered to the
          system on which the foreign address actually resides.

     For example, the printed representation of a foreign address
with an address route would be:

          GMP at EECS.MIT via MC via MIT-MULTICS.ARPA

SPECIAL CHARACTERS

     If a STR, Person_id.Project_id, FSystem, or RelayI in one of
the  above printed  representations contains  any commas, colons,
semi-colons,   parentheses,  angle   brackets (<>),  braces ({}),
quotes ("),  commerical  at-signs (@), or  whitespace  other than
single  seuquences  of  a  space,  it  must  be  quoted  to avoid
ambiguity with  other printed representations.  Such  a string is
quoted by surrounding it with quotes and then doubling any quotes
found within the string.

     For example, the string:

          Richard "Rick" Kovalcik, Jr.

would be quoted as:

          "Richard ""Rick"" Kovalcik, Jr."

     If a  pathname in one  of the above  printed representations
contains any parentheses,  braces ({}), quotes ("), or whitespace
other  than single  sequences of  a space,  it must  be quoted as
described above in order to avoid ambiguity.

     If   the  STR   in  a  comment   contains  any  parentheses,
quotes ("), or whitespace other than single sequences of a space,
it must be quoted as described above in order to avoid ambiguity.

Control Argument Representations of an Address

     The  control argument  representation of  an address  is the
sequence of command/request line  arguments and control arguments
recognized by the mail system in order to allow a user to specify
one or more mail system addresses on a command/request line.


MTB-613         Mail System Programmer's Reference        MTB-613

     The control argument sequences recognized by the mail system
are:

-user STR specifies either  a user's default mailbox  or an entry
          in the system mail table.   If STR contains exactly one
          period  and  no  whitespace,  it  is  interpreted  as a
          User_id  which  specifies  a  user's  default  mailbox;
          otherwise, it is interpreted as the name of an entry in
          the mail table.  When interpreted as a User_id, STR may
          not contain  any angle brackets (<>) and  must have the
          form  Person_id.Project_id  where   Person_id  may  not
          exceed 28  characters in length and  Project_id may not
          exceed  32 characters  in length.   In this  case, this
          control argument is equivalent to:
               -mailbox >udd>Project_id>Person_id>Person_id.mbx
          When interpreted as the name of a mail table entry, STR
          may  not  contain   any  commas,  colons,  semi-colons,
          backslashes (),   parentheses,   angle  brackets (<>),
          braces ({}),  quotes ("),  commerical  at-signs (@), or
          whitespace  other than  spaces.  The query  of the mail
          table is  performed in a case  insensitive manner.  The
          display_mailing_address   command   may   be   used  to
          determine the actual address  corresponding to the STR.

-log      specifies the user's logbox and is equivalent to:
               -mailbox >udd>Project_id>Person_id>Person_id.sv.mbx

-save path, -sv path
          specifies the pathname of a savebox.  The suffix sv.mbx
          is added if necessary.

-mailbox path, -mbx path
          specifies the pathname of a mailbox.  The suffix mbx is
          added if necessary.

-meeting path, -mtg path
          specifies the pathname of  a Forum meeting.  The suffix
          control is  added if necessary.  If  the pathname given
          is  just an  entryname (ie:   no "<"  or ">" characters
          appear in the pathname), the  forum search path is used
          to find the meeting.

STR -at FSystem {-via RelayN ... -via Relay1}
          specifies an address on  another computer system.   STR
          identifies the user (or group  of users) to receive the
          message and is not interpreted  in any way by the local
          system.    FSystem  is the  name of  the foreign system
          where  the address  is located.   If the  optional -via
          control arguments are not  present, FSystem must be one
          of the names of a  foreign system in the local system's
          network information table (NIT).   However, if the -via


MTB-613         Mail System Programmer's Reference        MTB-613

          control  arguments  are specified,  the  foreign system
          name does not need to be known to the local system.  If
          the -via control arguments are specified, they identify
          an  explicit  route to  be  used to  reach  the foreign
          system.  In this case, Relay1  must be one of the names
          of a  foreign system in  the local system's  NIT.  Mail
          destined for this foreign  address will be forwarded to
          the system identified as Relay1.    From there, it will
          be forwarded  to the system identified  as Relay2, etc.
          until it reaches the  system identified as RelayN where
          it will be delivered to the system on which the foreign
          address actually resides.  When  the NIT is queried for
          either FSystem  or Relay1, the query  will be performed
          in a case insensitive manner.

-mailing_list path, -mls path
          specifies the  pathname of a mailing  list.  The suffix
          mls  is  added  if  necessary.   The  archive component
          pathname convention is accepted.

STR       is  any  non-control argument  interpreted by  the mail
          system.   If  STR contains  either  "<" or  ">",  it is
          interpreted as:
               -mailbox STR
          otherwise, it is interpreted as:
               -user STR

     An  address name  and/or address  comment may  be associated
with any address by using the following control arguments:

-name STR, -nm STR
          must  appear  immediately  following one  of  the above
          forms  of  an address  and  specifies the  name  of the
          address.  An  address name is usually  the full name of
          the person  who receives mail  at that address  or, for
          mailing   lists,   a  description   of   the  addresses
          comprising     the     mailing      list     (eg:
          Site Administrators).

-comment STR, -com STR
          must  appear  immediately  following one  of  the above
          forms  of  an address  and  specifies a  comment  to be
          associated with that address.  This control argument is
          considered obsolete.

ADDRESS LISTS

     An address list  is a collection of zero  or more addresses.
Address  lists are  primarily used  in the  data structures which
define a message.  They are also used by those entrypoints in the
mail  system  which require  a  set of  addresses  as one  of its


MTB-613         Mail System Programmer's Reference        MTB-613

arguments.    (For   example,   the  mail_system_$deliver_message
entrypoint uses  address lists to  specify the recipients  of the
message.)

     An address list  should not be confused with  a mailing list
or  named  group.   Unlike  mailing lists  and  named  groups, an
address  list  is not  itself  an address;  it  is simply  a data
structure used to simplify the interface to the mail system.

The address_list Structure

     The following  structure and named constants  are defined in
the include file mlsys_address_list.incl.pl1:

     dcl 1 address_list  aligned based (address_list_ptr),
           2 version     character (8) unaligned,
           2 reserved    bit (144),
           2 n_addresses fixed binary,
           2 addresses   (address_list_n_addresses refer
                         (address_list.n_addresses)) pointer;

where:

version   is the current version of this structure.  This version
          of  the structure  is given by  the value  of the named
          constant ADDRESS_LIST_VERSION_2.

reserved  is reserved exclusively for use by the mail system.

n_addresses
          is the number of addresses in the address list.

addresses are pointers to the actual addresses.

Printed Representation of an Address List

     The printed  representation of an address  list is the human
readable  form  of that  address list.   It is  used by  the mail
system  when displaying  a message or  searching a  message for a
given character string.  The printed representation of an address
list   is  composed   of  the  printed   representations  of  its
constituent addresses separated by commas.  For example:

          Gary M.  Palter <Palter.Multics>, GMP at MIT-MC.ARPA

MESSAGES

     A message is the basic  unit of communication between users.
There are  two types of  message:  ordinary and  interactive.  An


MTB-613         Mail System Programmer's Reference        MTB-613

interactive message  is a message which  is displayed immediately
on the user's terminal when it is delivered.  An ordinary message
is  a  message which  is  only displayed  at the  user's explicit
request after  it has been  delivered.  Whenever the  mail system
delivers  an  ordinary message  to  a user,  it also  delivers an
interactive message to inform the  user that the ordinary message
was just delivered.

     The mail system represents a  message as a structured object
comprised   of   four   parts:    an   envelope,   a   header,  a
redistributions list, and a body.  The message envelope describes
when,  by whom,  and via  what route  the message  was mailed and
subsequently   delivered.   The   message  header   contains  the
message's  subject, author(s),  and recipient(s).   For a message
which  is  a  reply  to   other  messages,  the  header  contains
information which identifies those original messages.  The header
may also contain additional fields which are used by user written
application programs.  The redistributions list records each time
the message was redistributed (forwarded) by one user to another.
The  information  recorded for  each redistribution  includes the
user(s)  who requested  the redistribution, the  date/time it was
requested,  the  recipient(s)  of   the  redistribution,  and  an
optional comment.  The message body  is the actual content of the
message.  The  body is divided  into one or  more sections.  Each
section  may  have  its  own  distinct  structure  and formatting
instructions.

     The  mail  system  distinguishes   between  two  classes  of
messages in  order to determine  which fields in  the message and
which operations on the message are valid.  An in-mailbox message
is  a message  which has  already been  delivered to  one or more
users and, therefore,  resides in a mailbox.  A  new message is a
message which  is under construction by  a program for subsequent
delivery  to one  or more users.   New messages do  not use those
fields  in  the  following   data  structures  which  are  marked
in-mailbox only.

The message Structure

     The following structures and  named constants are defined in
the include file mlsys_message.incl.pl1:

     dcl 1 message       aligned based (message_ptr),
           2 version     character (8) unaligned,
           2 reserved    bit (144),
           2 n_reply_references
                         fixed binary,
           2 n_user_fields
                         fixed binary,
           2 n_redistributions
                         fixed binary,


MTB-613         Mail System Programmer's Reference        MTB-613

           2 n_body_sections
                         fixed binary,
           2 flags,
             3 interactive
                         bit (1) unaligned,
             3 can_be_deleted
                         bit (1) unaligned,
             3 marked_for_deletion
                         bit (1) unaligned,
             3 must_be_acknowledged
                         bit (1) unaligned,
             3 reserved  bit (32) unaligned,
           2 pad         bit (36),
           2 envelope    like message_envelope,
           2 header,
             3 message_id
                         bit (72),
             3 access_class
                         bit (72),
             3 date_time_created
                         fixed binary (71),
             3 from      pointer,
             3 reply_to  pointer,
             3 to        pointer,
             3 cc        pointer,
             3 bcc       pointer,
             3 subject   like message_text_field,
             3 reply_references
                         pointer,
             3 user_fields_list
                         pointer,
           2 redistributions_list
                         pointer,
           2 body,
             3 total_lines
                         fixed binary (21),
             3 pad       bit (36),
             3 body_sections
                         (message_n_body_sections refer
                         (message.n_body_sections)) like
                         message_body_section;

where:

version   is the current version of this structure.  This version
          of  the structure  is given by  the value  of the named
          constant MESSAGE_VERSION_2.

reserved  is reserved exclusively for use by the mail system.


MTB-613         Mail System Programmer's Reference        MTB-613

n_reply_references
          is the number  of messages for which this  message is a
          reply.

n_user_fields
          is  the number  of user-defined  header fields  in this
          message.

n_redistributions   (in-mailbox only)
          is  the  number of  times  that this  message  has been
          redistributed  (forwarded) by  other users  in order to
          reach this user.

n_body_sections
          is the number of sections in the body of this message.

flags               (in-mailbox only)
          reflect  the state  of this  message in  the containing
          mailbox.

  interactive
            if  "1"b,  this  message is  an  interactive message;
            otherwise, it is an ordinary message.

  can_be_deleted
            if  "1"b, the  user has  sufficient access  to delete
            this message from the  mailbox, if desired.  If "0"b,
            the user can not delete this message.

  marked_for_deletion
            if  "1"b,  this  message  will  be  deleted  from the
            mailbox     when     mail_system_$close_mailbox    or
            mail_system_$expunge_messages  is called.   A message
            is    marked    for   deletion    by   a    call   to
            mail_system_$mark_message_for_deletion;  the  pending
            deletion may  be cancelled, however, by  a later call
            to mail_system_$unmark_message_for_deletion.

  must_be_acknowledged
            if  "1"b, a  call to mail_system_$acknowledge_message
            should be made when this message is read by the user.
            The definition of the user  reading a message is left
            to  the  subsystem   or  application  processing  the
            mailbox.  (For  read_mail, a message is  read when it
            is printed, saved/logged, written, or answered; it is
            not read as a result of the list request.)

  reserved  is reserved exclusively for use by the mail system.

envelope            (in-mailbox only)
          is   the  message   envelope  covering   the  original,


MTB-613         Mail System Programmer's Reference        MTB-613

          non-redistribution,  mailing  of   this  message.   The
          contents of the envelope is described below.

header    is the message's header.

  message_id          (Message-ID field) (in-mailbox only)
            is the unique identifier  associated with the body of
            this message.   This field is maintained  by the mail
            system  to  permit  subsystems  and  applications  to
            determine if two messages  have identical bodies.  If
            two messages have the same value for this field, they
            contain  the   same  message  body;   however,  their
            envelopes,  headers,  and  redistribution  lists  may
            differ.

  access_class        (Access-Class field) (in-mailbox only)
            is the Access Isolation  Mechanism (AIM) access class
            of this  message.  A user may  read this message only
            if  their authorization  is greater than  or equal to
            this  access class;  a user  may delete  this message
            only  if the  authorization is  equal to  this access
            class.   (See  Multics Programmer's  Reference  for a
            more complete description of AIM.)

  date_time_created   (Date field) (in-mailbox only)
            is a standard Multics  clock reading representing the
            date/time that the message body was created.

  from                (From field)
            is a pointer to an address_list structure which lists
            the  user(s)  responsible  for  the  content  of this
            message.  These  users are also known  as the authors
            of the message.

  reply_to            (Reply-To field)
            is a pointer to an address_list structure which lists
            the  recipients  for  any   future  replies  to  this
            message.   If this  field is null,  replies should be
            sent  to  the  author(s),  listed above  in  the From
            field.

  to                  (To field)
            is a pointer to an address_list structure which lists
            the primary  recipients of this  message.  This field
            may be null if there are no primary recipients.

  cc                  (cc field)
            is a pointer to an address_list structure which lists
            the secondary recipients of this message.  This field
            may be null if there are no secondary recipients.


MTB-613         Mail System Programmer's Reference        MTB-613

  bcc                 (bcc field)
            is a pointer to an address_list structure which lists
            any  additional  recipients  of  this  message.  This
            field may  be null if  there are no  such recipients.
            The  copies of  the message delivered  to the primary
            and secondary recipients do  not include this list of
            recipients.

  subject             (Subject field)
            is  the subject  of this  message.  The  include file
            contains    a    declaration    for    the   variable
            message_subject  which  may  be  used  to  access the
            subject.   The   exact  content  of   this  field  is
            described  below  in  case  this  variable  does  not
            satisfy the requirements of the program examining the
            message.

  reply_references    (In-Reply-To field)
            is a pointer  to a message_references_list structure,
            described  below, which  identifies the  messages for
            which  this message  is a  reply.  This  field may be
            null if this message is not a reply.

  user_fields_list
            is a pointer to a message_user_fields_list structure,
            described  below,  which  contains  the  user-defined
            fields for  this message.  This field  may be null if
            this message does not have any user-defined fields.

redistributions_list
                    (in-mailbox only)
          is   a   pointer   to   a  message_redistributions_list
          structure,    described    below,    which    is    the
          redistributions list for this  message.  This field may
          be null if this message has never been redistributed.

body      is the body of this message.

  total_lines
            is the  total number of  lines in the  body.  If some
            sections of  the body are  not composed of  text (eg:
            voice)  or  must be  formatted  at display  time, the
            value of this  field will be -1 to  indicate that the
            length of the body is variable.

  body_sections
            are the  actual sections of the  body.  Each entry in
            this  array  describes  a single  section  giving its
            type, formatting options, and content.  See below for
            a description of the content of this field.


MTB-613         Mail System Programmer's Reference        MTB-613

The message_envelope Structure

     As  stated above,  every message contains  an envelope which
describes  when,  by whom,  and  via what  route the  message was
mailed and subsequently delivered.  In fact, the message envelope
describes the original mailing and  delivery of the message; each
entry in the redistributions list also contains an envelope which
describes  that  redistribution's   mailing  and  delivery.   For
simplicity, the descriptions given below  are written in terms of
the    message    envelope   and,    therefore,    the   original
mailing/delivery.

     Both  the message  envelope and  redistribution envelope are
represented by  the following structure  which is defined  in the
include file mlsys_message.incl.pl1:

     dcl 1 message_envelope
                         aligned based (message_envelope_ptr),
           2 date_time_mailed
                         fixed binary (71),
           2 sender      pointer,
           2 trace       pointer,
           2 date_time_delivered
                         fixed binary (71),
           2 delivered_by
                         pointer,
           2 acknowledge_to
                         pointer;

where:

date_time_mailed    (Posted-Date field)
          is  a standard  Multics clock  reading representing the
          date/time that the message was given to the mail system
          for delivery.

sender              (Sender field)
          is a pointer to an address representing the actual user
          who gave  the message to the  mail system for delivery.
          This  field  is only  used  if there  is more  than one
          author of the message or if the author was not the user
          who gave the message to the mail system.  If the sender
          is identical  to the author,  this field will  be null.
          (For  example,  an executive  might have  his secretary
          type and transmit a message; the executive would be the
          author and the secretary would be the sender).

trace     is  a pointer  to a  message_trace structure, described
          below, which describes the  route taken by this message
          through  the various  networks in  order to  reach this
          recipient.  This field will be null if no networks were
          involved in the delivery of the message.


MTB-613         Mail System Programmer's Reference        MTB-613

date_time_delivered (Delivery-Date field)
          is  a standard  Multics clock  reading representing the
          date/time that  the mail system  delivered this message
          to the user's mailbox.

delivered_by        (Delivery-By field)
          is a pointer to an address representing the actual user
          in whose process the mail system delivered this message
          to the  user's mailbox.  If this  delivery agent is the
          same as the sender, this field will be null.

acknowledge_to      (Acknowledge-To field)
          is a pointer to an address representing the user who is
          to receive an acknowledgement when this message is read
          by a  recipient provided that  the must_be_acknowledged
          flag in the message is  set.  The content of this field
          is  only  valid  in  the most  recent  envelope  in the
          message.

     The field names  listed above are the names  of these fields
within the message envelope.  In a redistribution envelope, these
field  names  are prefixed  by the  string Redistributed-.    For
example,  the date_time_mailed  field in  the above  structure is
named Redistributed-Posted-Date in a redistribution envelope.

     The most recent envelope in a message either is the envelope
of the  last redistribution or, if  there are no redistributions,
it is the message envelope itself.

     When    a    message    is    logged   via    a    call   to
mail_system_$log_message    or    saved    via    a    call    to
mail_system_$save_message,     the     date_time_delivered    and
delivered_by fields  of the most  recent envelope in  the message
are updated  to reflect the date/time  and person responsible for
the log or save operation.

THE MESSAGE_TRACE STRUCTURE

     As mentioned above, an  envelope contains the description of
the route  taken by its  message through the  various networks in
order to reach  the recipient.  This description is  known as the
message trace.

     The message trace includes an  address route which lists the
exact  path taken  by the  message through  the various networks.
This  address  route  will be  used  by  the mail  system  as the
implicit route for all addresses in the message.

     The  message  trace  also  the  description  of  each  relay
operation  listed in  the above implicit  route.  The information


MTB-613         Mail System Programmer's Reference        MTB-613

recorded  for  a relay  operation includes  the date/time  of the
relay, the sending and receiving hosts, and the protocols used.
     The following  structure and named constants  are defined in
the include file mlsys_message.incl.pl1:

     dcl 1 message_trace aligned based (message_trace_ptr),
           2 version     character (8) unaligned,
           2 reserved    bit (144),
           2 implicit_route
                         pointer,
           2 pad         bit (36),
           2 n_relays    fixed binary,
           2 relays      (message_trace_n_relays refer
                         (message_trace.n_relays)),
             3 date_time_relayed
                         fixed binary (71),
             3 sending_host
                         character (256) varying,
             3 communications_media
                         character (32) unaligned,
             3 communications_protocol
                         character (32) unaligned,
             3 mail_protocol
                         character (32) unaligned,
             3 relay_id  bit (72),
             3 relay_recipient
                         pointer;

where:

version   is the current version of this structure.  This version
          of  the structure  is given by  the value  of the named
          constant MESSAGE_TRACE_VERSION_2.

reserved  is reserved exclusively for use by the mail system.

implicit_route      (Route field)
          is a  pointer to an  address_route structure, described
          above, which lists the exact  path taken by the message
          through  the various  networks.  This  address route is
          the implicit route of the message.

n_relays  is the number of relay  operations used to deliver this
          message.

relays              (Relayed fields)
          describes  the  relay operations.   Each entry  in this
          array  describes a  single relay  operation.  The first
          entry describes  the oldest relay (ie:   the relay from
          the originating host) and  the last entry describes the
          newest relay (ie:  to the local host).


MTB-613         Mail System Programmer's Reference        MTB-613

  date_time_relayed
            is a standard Multics  clock reading representing the
            date/time that this relay operation took place.

  sending_host
            is the  name of the system  which relayed the message
            to  the  next system.   For  all but  the  last relay
            operation listed, the receiving host of a given relay
            is the sending  host of the next relay;  for the last
            relay  operation,  the  receiving host  is  the local
            host.

  communications_media
            is   a   character   string   which   identifies  the
            communication medium (eg:  ARPA network, Tymnet) used
            for this relay.  This field may be a null string.

  communications_protocol
            is   a   character   string   which   identifies  the
            communication protocol (eg:  TCP, X.25) used for this
            relay.  This field may be a null string.

  mail_protocol
            is  a  character  string  which  identifies  the mail
            transport  protocol  (eg:  SMTP,  NBS) used  for this
            relay.

  relay_id  is  a  unique  identifier assigned  by  the receiving
            system for  this relay operation.  This  field may be
            ""b if the receiving system did not assign an ID.

  relay_recipient
            is  a  pointer  to  an address  which  identifies the
            recipient as specified by the sending system for this
            relay  operation.   This  field  may  be  null.   The
            receiving system may include this field if it changes
            the  recipient address  (eg:  by  expanding a mailing
            list).

The message_redistributions_list Structure

     As  stated above,  every message  contains a redistributions
list  which  records  each  time  the  message  was redistributed
(forwarded) by one  user to another.  Like the  message itself, a
redistribution   contains   an  envelope   and  a   header.   The
redistribution envelope records when, by whom, and via what route
the  redistribution was  mailed and  subsequently delivered.  The
redistribution header  records who requested  the redistribution,
when they  requested the redistribution, to  whom the message was
redistributed,  and  an  optional  comment  associated  with  the
redistribution.


MTB-613         Mail System Programmer's Reference        MTB-613

     The following  structure and named constants  are defined in
the include file mlsys_message.incl.pl1:

     dcl 1 message_redistributions_list
                         aligned based
                         (message.redistributions_list),
           2 version     character (8) unaligned,
           2 reserved    bit (144),
           2 pad         bit (36),
           2 n_redistributions
                         fixed binary,
           2 redistributions
                         (message_n_redistributions refer
                         (message_redistrbutions_list.n_redistributions))
                         like message_redistribution;

where:

version   is the current version of this structure.  This version
          of  the structure  is given by  the value  of the named
          constant MESSAGE_REDISTRIBUTIONS_LIST_VERSION_2.

reserved  is reserved exclusively for use by the mail system.

n_redistributions
          is  the  number of  times  that this  message  has been
          redistributed  (forwarded) by  other users  in order to
          reach this user.

redistributions
          is  the  redistributions  list of  this  message.  Each
          entry in  the array describes  a signle redistribution.
          The first entry describes the oldest redistribution and
          the  last  entry describes  the  most recent  one.  The
          definition of a single redistribution follows:

THE MESSAGE_REDISTRIBUTION STRUCTURE

     The  following  structure  is  defined in  the  include file
mlsys_message.incl.pl1:

     dcl 1 message_redistribution
                         aligned based
                         (message_redistribution_ptr),
           2 envelope    like message_envelope,
           2 header,
             3 message_id
                         bit (72),
             3 date_time_created
                         fixed binary (71),
             3 from      pointer,


MTB-613         Mail System Programmer's Reference        MTB-613

             3 to        pointer,
             3 comment   like message_text_field;

where:

envelope  is  the redistribution  envelope.  The  content of this
          field is described above.

header    is the redistribution header.

  message_id          (Redistributed-Message-ID field)
            is  the   unique  identifier  associated   with  this
            redistribution.  This field is maintained by the mail
            system  to  permit  subsystems  and  applications  to
            determine if two redistributions  of the same message
            are  identical.  If  two redistributions  in multiple
            copies  of  a message  have the  same value  for this
            field, they are identical and all but one copy of the
            redistribution may be  eliminated when constructing a
            merger of the messages.

  date_time_created   (Redistributed-Date field)
            is a standard Multics  clock reading representing the
            date/time that this  redistribution was requested and
            the redistribution's comment, if any, was created.

  from                (Redistributed-From field)
            is a pointer to an address_list structure which lists
            the  user(s) who  requested that  this redistribution
            take place.

  to                  (Redistributed-To field)
            is a pointer to an address_list structure which lists
            the   user(s)   who  are   the  recipients   of  this
            redistribution.

  comment             (Redistributed-Comment field)
            is   the  optional   comment  associated   with  this
            redistribution  of  the  message.   The  include file
            contains    a    declaration    for    the   variable
            message_redistribution_comment  which may  be used to
            access the comment.  The  exact content of this field
            is  described below  in case  this variable  does not
            satisfy the requirements of the program examining the
            message.

The message_user_fields_list Structure

     As  stated  above, every  message  may contain  one  or more
user-defined  fields.   A user-defined  field is  a field  in the
message header whose content is  interpreted by an application or


MTB-613         Mail System Programmer's Reference        MTB-613

subsystem rather than by the mail system itself.  The contents of
a  user-defined field  may be a  text string, an  address list, a
date/time, or an integer.

     The following  structure and named constants  are defined in
the include file mlsys_message.incl.pl1:

     dcl 1 message_user_fields_list
                         aligned based
                         (message.user_fields_list),
           2 version     character (8) unaligned,
           2 reserved    bit (144),
           2 pad         bit (36),
           2 n_user_fields
                         fixed binary,
           2 user_fields (message_n_user_fields refer
                         (message_user_fields_list.n_user_fields))
                         like message_user_field;

where:

version   is the current version of this structure.  This version
          of  the structure  is given by  the value  of the named
          constant MESSAGE_USER_FIELDS_LIST_VERSION_2.

reserved  is reserved exclusively for use by the mail system.

n_user_fields
          is the number of user-defined fields in this message.

user_fields
          are  the  user-defined fields  for this  message.  Each
          entry  in  this array  describes a  single user-defined
          field's name  and content.  The definition  of a single
          user-defined field follows:

THE MESSAGE_USER_FIELD STRUCTURE

     The following structures and  named constants are defined in
the include file mlsys_message.incl.pl1:

     dcl 1 message_user_field
                         aligned based (message_user_field_ptr),
           2 header,
             3 field_id  fixed binary,
             3 field_type
                         fixed binary,
           2 field_type_variable
                         bit (144);

where:


MTB-613         Mail System Programmer's Reference        MTB-613

header    contains information about the user-defined field which
          is  common  amongst  all  four  types  of  user-defined
          fields.

  field_id  identifies  the  purpose of  this  user-defined field
            (eg:  postal address vs.   temperature in the machine
            room).  The  field ID may  be converted into  a field
            name   suitable   for   printing   via   a   call  to
            mail_system_$get_user_field_name; a field name may be
            converted   into   a   field   ID  via   a   call  to
            mail_system_$get_user_field_id.     The    field   ID
            assigned  to a  given field  name is  unique within a
            process.  (In  a future release,  user-defined fields
            will  registered  and  its  field ID  will  be unique
            across the system).

  field_type
            specifies the type of  this user-defined field.  This
            type  defines which  of the  type-specific structures
            listed below  should be used  to access the  value of
            this  field.  The  possible values of  this field are
            given by the following named constants:

            MESSAGE_TEXT_USER_FIELD
                      the value of this  user-defined field is an
                      arbitrary text string.

            MESSAGE_ADDRESS_LIST_USER_FIELD
                      the value  of this user-defined  field is a
                      list of addresses.

            MESSAGE_DATE_USER_FIELD
                      the value  of this user-defined  field is a
                      Multics clock reading.

            MESSAGE_INTEGER_USER_FIELD
                      the value of this  user-defined field is an
                      integer.

field_type_variable
          contains the value of  this user-defined field.  One of
          the following four structures  should be used to access
          this data based on the value of field_type above:

Type Specific message_user_field Structures

     dcl 1 message_text_user_field
                         aligned based (message_user_field_ptr),
           2 header      like message_user_field.header,
           2 text        like message_text_field;


MTB-613         Mail System Programmer's Reference        MTB-613

     dcl 1 message_address_list_user_field
                         aligned based (message_user_field_ptr),
           2 header      like message_user_field.header,
           2 address_list_ptr
                         pointer,
           2 pad         bit (72);

     dcl 1 message_date_user_field
                         aligned based (message_user_field_ptr),
           2 header      like message_user_field.header,
           2 date_time   fixed binary (71),
           2 pad         bit (72);

     dcl 1 message_integer_user_field
                         aligned based (message_user_field_ptr),
           2 header      like message_user_field.header,
           2 value       fixed binary (35),
           2 pad         bit (108);

where:

header    is  as  described   above  for  the  message_user_field
          structure.

text      is  the text  which is  the value  of this user-defined
          field.  The include file contains a declaration for the
          variable message_text_user_field_text which may be used
          to access the text.  The exact content of this field is
          described below in case  this variable does not satisfy
          the requirements of the program examining the message.

address_list_ptr
          is a pointer to the address_list structure which is the
          value of this user-defined field.

date_time is  the  standard Multics  clock  reading which  is the
          value of this user-defined field.

value     is the integer which is  the value of this user-defined
          field.

CANONICALIZATION OF USER-DEFINED FIELD NAMES

     The mail_system_$get_user_field_id entrypoint which converts
a  user-defined  field name  into  a field  ID  canonicalizes the
supplied field name before attempting  to determine its ID.  This
canonicalization  insures  that   all  user-defined  fields  with
identical purpose  are recognized as  such even though  the field
names typed by  the user may differ in  case and/or quantities of
whitespace.


MTB-613         Mail System Programmer's Reference        MTB-613

     A user-defined field name  is canonicalized by replacing all
sequences  of  whitespace in  the name  with a  single hyphen (-)
yielding a sequence of tokens  separated by hyphens.  The case of
these  tokens  is  then  canonicalized  by  converting  the first
character in each token to uppercase and the remaining characters
to  lowercase.   If the  first  character in  a  token is  not an
alphabetic, no characters in that token will be in uppercase.

     For  example,  the  following   field  names  would  all  be
canonicalized into Local-Postal-Address:

          Local-postal  address
          LoCaL POSTAL-Address
          local- postal  address

The message_references_list Structure

     A  message  often contains  a  list of  references  to other
messages.  The  mail system provides  a mechanism to  reference a
message by its ID,  date/time created, author(s), and/or subject.
This mechanism is used today to identify the messages for which a
given message is a reply, if any.  (In future releases, a message
will be able to contain  references to arbitrary messages and not
just those for which it is a reply).

     The following  structure and named constants  are defined in
the include file mlsys_message.incl.pl1:

     dcl 1 message_references_list
                         aligned based
                         (message_references_list_ptr),
           2 version     character (8) unaligned,
           2 reserved    bit (144),
           2 pad         bit (36),
           2 n_references
                         fixed binary,
           2 references  (message_references_list_n_references
                         refer
                         (message_references.list_n_references))
                         like message_reference;

where:

version   is the current version of this structure.  This version
          of  the structure  is given by  the value  of the named
          constant MESSAGE_REFERENCES_LIST_VERSION_2.

reserved  is reserved exclusively for use by the mail system.

n_references
          is the number of messages referenced in this list.


MTB-613         Mail System Programmer's Reference        MTB-613

references
          are  the  actual  references to  those  messages.  Each
          entry in this array identifies  a single message by ID,
          date/time   created,   author(s),  and   subject.   The
          definition of a single message reference follows:

THE MESSAGE_REFERENCE STRUCTURE

     The  following  structure  is  defined in  the  include file
mlsys_message.incl.pl1:

     dcl 1 message_reference
                         aligned based (message_reference_ptr),
           2 message_id  bit (72),
           2 date_time_created
                         fixed binary (71),
           2 from        pointer,
           2 subject     like message_text_field;

where:

message_id
          is  the unique  identifier associated with  the body of
          the referenced message.

date_time_created
          is  a Multics  standard clock  reading representing the
          date/time that  the body of the  referenced message was
          created.

from      is a  pointer to an address_list  structure which lists
          the  user(s)   responsible  for  the   content  of  the
          referenced message.

subject   is the subject of  the referenced message.  The include
          file   contains   a   declaration   for   the  variable
          message_reference_subject which  may be used  to access
          the  subject.   The  exact  content  of  this  field is
          described below in case  this variable does not satisfy
          the requirements of the program examining the message.

     For certain older messages, the  mail system is only able to
provide  a   reference  by  message   ID.   In  this   case,  the
date_time_created field above will have a value of zero, the from
field will be null, and the subject will be a zero-length string.


MTB-613         Mail System Programmer's Reference        MTB-613

The message_text_field Structure

     Several fields  in the message header  and envelope are text
fields.  A text field is an arbitrary string of characters which,
in fact, may extend across several lines.

     The following structure is used to represent all text fields
and is declared in the include file mlsys_message.incl.pl1:

     dcl 1 message_text_field
                         aligned based (message_text_field_ptr),
           2 text_ptr    pointer,
           2 text_lth    fixed binary (21),
           2 reserved    bit (36);

where:

text_ptr  is a pointer to the unaligned character string which is
          the text of this field.

text_lth  is the length of the text in characters.

reserved  is reserved exclusively for use by the mail system.

     In     addition    to     the    above     structure,    the
mlsys_message.incl.pl1 include  file also contains  a declaration
for  the variable  message_text_field_text which  may be  used to
access the text of any message  header or envelope field which is
defined by this structure.

The message_body_section Structure

     As stated above, every message  has a body which is composed
of one  or more sections.  Each  section of the body  has its own
structure and formatting options.

     The following structures and  named constants are defined in
the include file mlsys_message.incl.pl1:

     dcl 1 message_body_section
                         aligned based
                         (message_body_section_ptr),
           2 header,
             3 section_type
                         fixed binary,
             3 section_n_lines
                         fixed binary (21),
           2 section_type_variable
                         bit (144);

where:


MTB-613         Mail System Programmer's Reference        MTB-613

header    contains  the  information   about  this  message  body
          section  which is  common amongst all  types of message
          body sections.

  section_type
            specifies the type of this section of the body.  This
            type defines which of  the type-specific message body
            section  structures  listed below  should be  used to
            access  the  content  of   this  section.   The  only
            possible value for this field at this time is:

            MESSAGE_PREFORMATTED_BODY_SECTION
                      specifies that this section  of the body is
                      comprised  of text  which was  formatted by
                      the application or  subsystem before it was
                      added to the message.

  section_n_lines
            is  the  number of  lines in  this section.   If this
            section  of  the body  is not  composed of  text (eg:
            voice)  or must  be formatted  at display  time, this
            field will  have a value  of -1 to  indicate that the
            length of this section is variable.

section_type_variable
          contains the value of this section of the message body.
          At present, only the following structure should be used
          to access this data:

TYPE SPECIFIC MESSAGE_BODY_SECTION STRUCTURES

     dcl 1 message_preformatted_body_section
                         aligned based
                         (message_body_section_ptr),
           2 header      like message_body_section.header,
           2 text_ptr    pointer,
           2 text_lth    fixed binary (21),
           2 reserved    bit (36);

where:

header    is  as  described  above  for  the message_body_section
          structure.

text_ptr  is a pointer to the unaligned character string which is
          the text of this section of the body.  The include file
          contains    a    declaration     for    the    variable
          message_preformatted_body_section_text  which   may  be
          used to access the text.


MTB-613         Mail System Programmer's Reference        MTB-613

text_lth  is the length of the text in characters.

reserved  is reserved exclusively for use by the mail system.

Printed Representation of a Message

     The  printed  representation  of  a  message  is  the  human
readable  form of  that message.  It  is used by  the mail system
when  displaying a  message or  searching a  message for  a given
character string.

     The basic format of the  printed representation of a message
is:

          <envelope>
          <header>
          <redistributions list>

          <body>

where  <envelope> is  the printed  representation of  the message
envelope,  etc.   As  can be  seen  from the  above,  the printed
representation of  the message body  is separated from  the other
parts of the message by a blank line; the printed representations
of the  envelope, header, and redistributions  list, on the other
hand, are contiguous.

     For example:

          Posted-Date:  29 April 1983 12:00 edt
          Sender:  Palter.Multics
          Date:  Thursday, 28 April 1983 10:45 edt
          From:  Gary M. Palter <Palter>, barmar at MIT-MC.ARPA
          Subject:  Sample Message Header Format
          To:  {list >udd>m>gmp>mail_project}
          cc:  DRV
          In-Reply-To:  Message of 3 April 1983 12:35 edt from Dave Vinograd,
                        Message of 12 April 1983 22:45 edt from Dave Schimke
          Redistributed-Date:  1 May 1983 03:30 edt
          Redistributed-From:  Benson I. Margulies <Margulies>
          Redistributed-To:  Header-People at MIT-MC.ARPA
          Redistributed-Comment:  Since your people have always
                                  been interested in long
                                  headers, I'd thought I'd show
                                  you this one.
                                        - Benson
          Redistributed-Acknowledge-To:  Margulies.Multics

          This is a sample of the printed representation of a
          message as used by the Multics Mail System.  It ...


MTB-613         Mail System Programmer's Reference        MTB-613

     The entrypoints in the mail system which produce the printed
representation of a message provide support for several different
forms   of   the   message    envelope,   message   header,   and
redistributions list.  The various forms of any part of a message
differ only  in the amount  of information displayed  by the mail
system.   The  message  header  and redistributions  list  may be
displayed in  long, default, or brief  form; the message envelope
may be displayed only in long or default form.

     In the following descriptions, the meaning of the term empty
field is  dependent on the  type of data  in that field.   If the
field is a single address, it  is considered to be empty when the
pointer  in  the data  structure  is null.   If  the field  is an
address  list,  it  is considered  to  be empty  either  when the
pointer  in  the  data  structure  is  null  or  the address_list
structure referenced by said pointer contains zero addresses.  If
the field is a text field, it  is considered to be empty when the
length of the text is zero.

PRINTED REPRESENTATION OF THE MESSAGE ENVELOPE

     The long  form of the printed  representation of the message
envelope is:

          Posted-Date:  <date-string>
          Sender:  <address>
          <message-trace>
          Delivery-Date:  <date-string>
          Delivery-By:  <address>
          Acknowledge-To:  <address>

where:

<date-string>
          is  the printed  representation of  the given date/time
          field.  Its format is:
               DD Month YYYY HH:MM zone
          For example:
               9 April 1983 12:17 edt

<address> is  the printed  representation of  the address  in the
          given field.

<message-trace>
          is  the  printed  representation of  the  message trace
          contained in this envelope as described below.

     If  the Sender  field in the  envelope is  empty, the single
address in the  From field of the message  header is displayed as
the  value  of  the  Sender field.   The  message  trace  is only
displayed if it is not empty.  If the Delivery-By field is empty,


MTB-613         Mail System Programmer's Reference        MTB-613

the address in  the Sender field (or, if  needed, the From field)
is displayed as the value  of the Delivery-By field.  However, if
the Acknowledge-To  field is empty,  nothing is displayed  in its
place.

     In  the  default  form  of the  printed  representation, the
Posted-Date  field is  displayed only  it its  value differs from
that of the  Date field in the message  header.  The Sender field
is displayed only if it is not empty.  The message trace is never
displayed.   The  Delivery-Date field  is  displayed only  if its
value   differs  from   that  of  the   Posted-Date  field.   The
Delivery-By  field is  displayed only  if it  is not  empty.  The
Acknowledge-To field is displayed only if it is not empty.

Printed Representation of a Message Trace

     The printed representation of a message trace is:

          Route:  <address-route>
          <relay-operation 1>
          ...
          <relay-operation N>

where:

<address-route>
          is the  printed representation of  the implicit address
          route in the trace.

<relay-operation I>
          is  the  printed representation  of a  relay operation.
          The relay  operations are list  in chronological order;
          ie:   <relay-operation 1> is  relay operation  from the
          originating system and <relay-operation N> is the relay
          operation   to   the   local   system.    The   printed
          representation of a relay operation is:

               Relayed:  from <sending-host> to <receiving-host>
                         using <mail-protocol> with
                         <comm-procotol> via <comm-media> ID
                         <message-id> for <address>;
                         <date-string>

          where:

          <sending-host>
                    is  the name  of the sending  system for this
                    relay operation.


MTB-613         Mail System Programmer's Reference        MTB-613

          <receiving-host>
                    is the name of  the receiving system for this
                    relay operation.

          <mail-protocol>
                    is  the name  of the  mail transport protocol
                    used for this relay operation.

          <comm-procotol>
                    is  the name  of the  communications protocol
                    used for this relay operation.  If this field
                    is  not specified  for this  relay operation,
                    the  with <comm-protocol>  phrase  is omitted
                    from the above text.

          <comm-media>
                    is the name of  the communications media used
                    for this  relay operation.  If  this field is
                    not specified  for this relay  operation, the
                    via <comm-media> phrase is  ommitted from the
                    above text.

          <message-id>
                    is  the  unique identifier  assigned  to this
                    relay operation by the receiving system.  See
                    the  below for  a description  of the printed
                    representation  of  unique  identifiers.   If
                    this  field is  not specified  for this relay
                    operation,  the   ID <message-id>  phrase  is
                    ommitted from the above text.

          <address> is   the   printed   representation   of  the
                    recipient   for   this  relay   operation  as
                    specified  by  the sending  system.   If this
                    field  is   not  specified  for   this  relay
                    operation,   the   for <address>   phrase  is
                    omitted from the above text.

          <date-string>
                    is   the   printed   representation   of  the
                    date/time  when  this  relay  operation  took
                    place.

PRINTED REPRESENTATION OF THE MESSAGE HEADER

     The long  form of the printed  representation of the message
header is:

          Date:  <long-date-string>
          From:  <address-list>
          Subject:  <text-string>


MTB-613         Mail System Programmer's Reference        MTB-613

          Reply-To:  <address-list>
          To:  <address-list>
          cc:  <address-list>
          bcc:  <address>
          In-Reply-To:  <message-reference-list>
          Access-Class:  <AIM-class>
          Message-ID:  <message-id>
          <user-defined-fields-list>

where:

<long-date-string>
          is  the printed  representation of  the given date/time
          field.  Its format is:
               DayName, DD Month YYYY HH:MM zone
          For example:
               Saturday, 9 April 1983 12:17 edt

<address-list>
          is  the printed  representation of the  address list in
          the given field.

<text-string>
          is the printed representation  of the given text field.
          This  representation consists  of the  actual text with
          two  exceptions.   If the  text is  more than  one line
          long,  each  additional  line  is  indented  by  adding
          additional  whitespace  equal in  width to  the field's
          name to the beginning of each line.  If any line in the
          text is blank,  the string "--" is placed  on that line
          just before  the left margin  of the actual  text.  For
          example, if the value of the subject is:

               Sample text field that is multiple lines
                    with some lines indented more than others

               and also some blank lines.

          the  printed representation  of the  Subject field will
          be:

               Subject:  Sample text field that is multiple lines
                              with some lines indented more than others
                       --
                         and also some blank lines.

<message-reference-list>
          is  the  printed  representation  of a  set  of message
          references.   The  printed  repsentation  of  a  single
          message reference has the following format:
               Message of <date-string> from <address-name>
          where <address-name>  is the address name  of the first


MTB-613         Mail System Programmer's Reference        MTB-613

          address  in the  From field of  the referenced message.
          If this  address does not  have a name,  its comment is
          used  instead; if  the address doesn't  have a comment,
          its printed representation is used.  For example:
               Message of 1 May 1983 17:49 edt from Gary Palter
          If  the  list  contains multiple  references,  they are
          separated  from  each other  by  commas and  the second
          through  last  references  are  indented  by sufficient
          whitespace to align them with the first reference.  For
          example:
               In-Reply-To:  Message of 9 April 1983 14:50 edt ...,
                             Message of 1 May 1983 10:17 edt from ...

<AIM-class>
          is the printed representation of an AIM access class as
          returned    by    the   standard    system   subroutine
          convert_authorization_$to_string_short.

<message-id>
          is the  printed representation of  a unique identifier.
          Its format is:
               <STR {at HOST}>
          where  STR is  the actual  unique identifier  which, if
          generated by a Multics system, will be the long form of
          a request ID.  (See  Multics Programmer's Reference for
          the  format of  a request  ID).  If  the identifier was
          generated  by a  foreign system, that  system's name is
          included in the printed  representation via the at HOST
          phrase.  The  angle brackets ("<" and  ">") shown above
          are actually part of the printed representation.

<user-defined-fields-list>
          is   a   list  of   printed  representations   for  the
          user-defined fields in  the message.  Each user-defined
          field   has   one   of  the   following   four  printed
          representations  depending  on  the  type  of  data  it
          contains:
               <user-defined-field-name>:  <text-string>
               <user-defined-field-name>:  <address-list>
               <user-defined-field-name>:  <date-string>
               <user-defined-field-name>:  <integer>
          where  <user-defined-field-name>  is  the  canoicalized
          field name  of the user-defined field  and <integer> is
          the value of an integer user-defined field in decimal.

     In the  long form of  the printed representation,  the Date,
From,  Access-Class and  Message-ID fields  are always displayed.
The other fields are only displayed if they are not empty.

     In the default form of  the printed representation, the Date
and From fields are always  displayed.  The Access-Class field is
only displayed if the access class of the message is not equal to


MTB-613         Mail System Programmer's Reference        MTB-613

the user's process authorization.   The Message-ID field is never
displayed.  The other  fields are only displayed if  they are not
empty.

     In the  brief form of  the printed representation,  the Date
and From fields are always  displayed.  The Subject field is only
displayed if  it is not empty.   None of the other  fields in the
message header  are displayed.  However,  if the user  is not the
only  recipient  of the  message,  the following  psuedo-field is
displayed in place of the To, cc, and bcc fields:
          Recipients:  {Yourself and} N others
where N is the number of recipients of the message in addition to
the user.  The string Yourself and  is displayed only if the user
is explicitly mentioned in one of the To, cc, or bcc fields.

PRINTED REPRESENTATION OF THE REDISTRIBUTIONS LIST

     The printed representation of the redistributions list is:

          <redistribution 1>
          ...
          <redistribution N>

where <redistribution 1> is the  first (oldest) redistribution of
the   message  and   <redistribution N>  is   the  last  (latest)
redistribution of the message.

     The  long  form of  the printed  representation of  a single
redistribution is:

          Redistributed-Posted-Date:  <date-string>
          Redistributed-Sender:  <address>
          <redistributed-message-trace>
          Redistributed-Delivery-Date:  <date-string>
          Redistributed-Delivery-By:  <address>
          Redistributed-Acknowledge-To:  <address>
          Redistributed-Date:  <date-string>
          Redistributed-From:  <address-list>
          Redistributed-To:  <address-list>
          Redistributed-Comment:  <text-string>
          Redistributed-Message-ID:  <message-id>

where:

<redistribution-message-trace>
          is the  printed representation of the  message trace in
          the  redistribution  envelope.  This  representation is
          identical  to the  one described above  except that the
          field   names   used    are   Redistributed-Route   and
          Redistributed-Relayed, respectively.


MTB-613         Mail System Programmer's Reference        MTB-613

     The default and brief forms  of the redistributions list are
both  treated  as  the  default  form  when  determining  how the
redistribution  envelope is  to be  displayed.  With  this slight
change, the  rules given above  for the display of  the fields in
the message  envelope and header  are applied identically  to the
fields in  the redistribution envelope and  header.  (Eg:  in the
default    form     of    the    redistributions     list,    the
Redistributed-Posted-Date  field is  displayed only  if its value
differs from that of the Redistributed-Date field).  In addition,
the Redistributed-Comment  field is only  displayed if it  is not
empty.

     There is  one major exception to  the formatting rules given
above, however.   In the brief form  of the redistributions list,
the entire redistribution (header  and envelope) is not displayed
if the Redistributed-Comment field is empty.

PRINTED REPRESENTATION OF THE MESSAGE BODY

     The printed representation of the message body is:

          <body section 1>

          ...

          <body section N>

where <body section I> is the printed representation of the given
section of the body.  As can be seen from the above, each section
is separated from the others by a blank line.

     The  printed  representation  of  a  preformatted  text body
section, which is the only  type of section supported at present,
is simply the  text of the section.  Said  text was formatted for
display  before it  was added to  the message  and, therefore, no
changes  are made  to it  by the  entrypoints in  the mail system
which create/display printed representations.

MAILBOXES

     A  mailbox  is  a  repository for  messages.   Mailboxes are
implemented as protected, ring-1 segments  with the suffix mbx.
The  mailbox's extended  ACL allows the  user to  control who may
add, delete, or read messages in the mailbox.

     A  user normally  receives incoming messages  in his default
mailbox.   The pathname of the user's default mailbox is
          >udd>Project_id>Person_id>Person_id.mbx
In  addition, a  user may save  important messages in  one of his
saveboxes or in his logbox.  A savebox is a mailbox which has the


MTB-613         Mail System Programmer's Reference        MTB-613

suffix  sv.mbx  and may  reside  anywhere in  the  storage system
hierarchy.  The logbox is, in fact, the savebox whose pathname is
          >udd>Project_id>Person_id>Person_id.sv.mbx

     The  mail  system  provides  entrypoints  to  examine and/or
delete the messages  in a mailbox.  In addition,  the mail system
provides a set of entrypoints  to create and delete mailboxes and
to manipulate their extended ACLs.

     When requested to examine a mailbox, the mail system creates
the  message  structure for  each  message in  the  mailbox which
matches  the  requested selection  criteria.   It then  creates a
mailbox  structure which  locates all  the selected  messages and
contains other usefull information extracted from the mailbox.

The mailbox Structure

     Unless stated  otherwise, the following  structure and named
constants are defined in the include file mlsys_mailbox.incl.pl1:

     dcl 1 mailbox       aligned based (mailbox_ptr),
           2 version     character (8) unaligned,
           2 reserved    bit (144),
           2 mailbox_address
                         pointer,
           2 mailbox_dirname
                         character (168) unaligned,
           2 mailbox_ename
                         character (32) unaligned,
           2 mailbox_type
                         fixed binary,
           2 mode        bit (36),
           2 flags,
             3 salvaged  bit (1) unaligned,
             3 reserved  bit (35) unaligned,
           2 message_selection_mode
                         fixed binary,
           2 sender_selection_mode
                         fixed binary,
           2 message_reading_level
                         fixed binary,
           2 n_messages  fixed binary,
           2 n_ordinary_messages
                         fixed binary,
           2 n_interactive_messages
                         fixed binary,
           2 n_deleted_messages
                         fixed binary,
           2 messages    (mailbox_n_messages refer
                         (mailbox.n_messages)),


MTB-613         Mail System Programmer's Reference        MTB-613

             3 key       bit (72),
             3 message_ptr
                         pointer;

where:

version   is the current version of this structure.  This version
          of  the structure  is given by  the value  of the named
          constant MAILBOX_VERSION_2.

reserved  is reserved exclusively for use by the mail system.

mailbox_address
          is  a  pointer  to  the address  which  represents this
          mailbox.

mailbox_dirname
          is  the absolute  pathname of  the directory containing
          this mailbox.

mailbox_ename
          is  the  entryname of  this  mailbox including  the mbx
          suffix.

mailbox_type
          defines  the nature  of this  mailbox from  the vantage
          point of  the mail system.   This type is  usefull when
          printing  general  messages about  this mailbox  (eg:
          There are 5 messages in your logbox).     The  possible
          values of  this field are given  by the following named
          constants:

          USER_DEFAULT_MAILBOX
                    identifies the user's default mailbox.

          USER_LOGBOX
                    identifies the user's logbox.

          SAVEBOX   identifies  either  a savebox  or  some other
                    user's logbox.

          OTHER_MAILBOX
                    identifies  either some  other user's default
                    mailbox  or  any  other  mailbox  without the
                    sv.mbx suffix used for saveboxes.

mode      is the current user's effective extended access to this
          mailbox.  The  possible bits which  may be set  in this
          field  are  defined  by  named  constants  of  the form
          A_MBX_ACCESS  which  are  defined in  the  include file
          mlsys_mailbox_modes.incl.pl1.


MTB-613         Mail System Programmer's Reference        MTB-613

flags     reflects    the    state    of    the    mailbox   when
          mail_system_$open_mailbox was called.

  salvaged  is "1"b  if this mailbox  has been salvaged  since it
            was  last read  and indicates that  some messages may
            have been lost.  Programs should issue a warning when
            a call to mail_system_$open_mailbox returns a mailbox
            structure with this flag set.

  reserved  is reserved exclusively for use by the mail system.

message_selection_mode
          specifies  the  types  of  messages  included  in  this
          structure.  The possible values of this field are given
          by the  following named constants which  are defined in
          the include file mlsys_open_options.incl.pl1:

          ALL_MESSAGES
                    all  types  of  messages in  the  mailbox are
                    included in this structure.

          ORDINARY_MESSAGE
          INTERACTIVE_MESSAGE
                    only   ordinary   or   interactive  messages,
                    respectively,  are  included in  this mailbox
                    structure.

sender_selection_type
          specifies which messages in the mailbox are included in
          this structure according to  who sent the message.  The
          possible  values  of  this   field  are  given  by  the
          following named constants which are also defined in the
          include file mlsys_open_options.incl.pl1:

          ALL_MESSAGES
                    all  messages  of   the  types  specified  by
                    message_selection_mode  are included  in this
                    mailbox structure.

          OWN_MESSAGES
          NOT_OWN_MESSAGES
                    all  messages  of   the  types  specified  by
                    message_selection_mode  which  were  sent  by
                    this user  or by someone  else, respectively,
                    are included in this mailbox structure.

message_reading_level
          specifies whether all or only  part of each message was
          read  from the  mailbox.  The  possible values  of this
          field are given by  the following named constants which
          are    also    defined     in    the    include    file
          mlsys_open_options.incl.pl1:


MTB-613         Mail System Programmer's Reference        MTB-613

          READ_KEYS only the unique key for each message was read
                    from  the  mailbox.   This  key  is  used  by
                    subsequent calls to mail_system_$read_message
                    to  retrieve  the  actual  message  from  the
                    mailbox.

          READ_MESSAGES
                    the entire  content of each  message was read
                    from the mailbox.

n_messages
          is the total number of messages in this structure.

n_ordinary_messages
n_interactive_messages
          is  the   total  number  of   ordinary  or  interactive
          messages, respectively, in this mailbox structure.

n_deleted_messages
          is the total number of messages in this structure which
          have been  marked for later deletion  from the mailbox.
          The  messages  are  actually   deleted  by  a  call  to
          mail_system_$close_mailbox                           or
          mail_system_$expunge_messages.

messages  are the messages read from the mailbox.

  key       is the unique key for this message.

  message_ptr
            is a pointer to the message structure describing this
            message.  If message_reading_level is READ_KEYS, this
            value    will    be    null   until    a    call   to
            mail_system_$read_message is made.


MTB-613         Mail System Programmer's Reference        MTB-613

                            SECTION 2

                           SUBROUTINES

     This  section contains  the descriptions  of the subroutines
which  comprise the  programmer's interface  to the  Multics Mail
System.  These subroutines are:

SUBROUTINE NAME                        FUNCTION

mail_system_        is   the   programmer's   interface   to  the
                    primitive  operations  of  the  mail  system.
                    These primitives include  the manipulation of
                    addresses and address lists, the creation and
                    transmission   of   new  messages,   and  the
                    examination   and   deletion   of  in-mailbox
                    messages.

mlsys_info_         provides  access  to  several  static  and/or
                    constant  objects  maintained   by  the  mail
                    system.  Such objects  include the address of
                    the user's default  mailbox, logbox, and mail
                    table entry.

mlsys_utils_        provides a collection of frequently used mail
                    system  utility  functions.   These functions
                    include the conversion  of addresses, address
                    lists,  and  messages between  their internal
                    and printed representations and the creation,
                    deletion,  and  extended ACL  manipulation of
                    mailboxes.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Name:  mail_system_

     The mail_system_ subroutine is the programmer's interface to
the  primitive  operations  of  the Multics  Mail  System.  These
primitives  include  the  manipulation of  addresses  and address
lists,  the creation  and transmission  of new  messages, and the
examination and deletion of in-mailbox messages.

             ________________________________________

Entry:  mail_system_$abort_delete_operation

     This       entrypoint       aborts      a       call      to
mail_system_$expunge_messages or mail_system_$close_mailbox which
was  suspended  by the  detection  of an  error while  deleting a
message.   The  operation is  aborted  by replacing  the supplied
mailbox structure with a revised  structure that does not contain
those  messages  which  were   successfully  deleted  before  the
reported   error   occured.    See   the   description   of   the
mail_system_$expunge_messages   entrypoint   for   more  detailed
information.

USAGE

     dcl  mail_system_$abort_delete_operation entry (pointer,
               fixed binary (35));

     call mail_system_$abort_delete_operation (mailbox_ptr,
               code);

ARGUMENTS

mailbox_ptr         (Input/Output)
          is  a pointer  to the mailbox  structure describing the
          mailbox    for    which    the    currently   suspended
          mail_system_$expunge_messages                        or
          mail_system_$close_mailbox operation is  to be aborted.
          This  pointer  will be  updated  to locate  the revised
          mailbox  structure  and  the   old  structure  will  be
          destroyed.

code                (Output)
          is a standard system status code.  Amongst the possible


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_mailbox
                    The   storage  identified   by  the  supplied
                    mailbox_ptr is not a mailbox structure.

          mlsys_et_$no_pending_deletion
                    There          is          no         pending
                    mail_system_$expunge_messages              or
                    mail_system_$close_mailbox          operation
                    suspended  to  be aborted  for  the specified
                    mailbox.

             ________________________________________

Entry:  mail_system_$acknowledge_message

     This entrypoint  sends an acknowledgement  for an in-mailbox
message.

USAGE

     dcl  mail_system_$acknowledge_message entry (pointer,
               fixed binary (35));

     call mail_system_$acknowledge_message (message_ptr, code);

ARGUMENTS

message_ptr         (Input)
          is a pointer to the in-mailbox to be acknowledged.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$not_in_mailbox_message
                    The   storage  identified   by  the  supplied


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

                    message_ptr is  a new message  rather than an
                    in-mailbox message.

          mlsys_et_$no_ack_needed
                    This   message   does    not   need   to   be
                    acknowledged.

          mlsys_et_$bad_acknowledge_to
                    The   mail   system   can   not   deliver  an
                    acknowledgement   to  the   type  of  address
                    specified    in    the    Acknowledge-To   or
                    Redistributed-Acknowledge-To    field.     At
                    present, the  mail system is  capable only of
                    sending acknowledgements to mailboxes.

          mlsys_et_$cant_send_acknowledgement
                    The   mail   system    can   not   send   the
                    acknowledgement  to  the  appropriate address
                    due to  either lack of access  to the mailbox
                    or insufficient space/quota in the mailbox.

          mlsys_et_$cant_update_message
                    The  mail  system successfully  delivered the
                    acknowledgement but was unable to record this
                    fact  in  the  copy  of  the  message  in the
                    mailbox.     As    a    result,    extraneous
                    acknowledgements  may  be generated  for this
                    message.

NOTES

     The acknowledgement is sent as an interactive message to the
address  specified  either  in  the Acknowledge-To  field  if the
message   has   not   been   redistributed   or   in   the   last
Redistributed-Acknowledge-To field if it has.  If the appropriate
field is  empty or the must_be_acknowledged  flag in this message
is  not  set, no  acknowledgement is  generated.  The  message is
immediately rewrriten to the  mailbox to prevent sending multiple
acknowledgements for a given message.

     The text of the acknowledgement sent by this entrypoint is:

          Acknowledging your message of DATE; Subject:  TEXT

where DATE  is the date/time  that this message  was delivered to
this  mailbox and  TEXT is  the subject  of the  message.  If the


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

message doesn't  have a subject, the  text of the acknowledgement
ends with the date/time string.  The format of DATE is:

          DD Month YYYY HH:MM zone

             ________________________________________

Entry:  mail_system_$add_address

     This entrypoint adds  an address to the end  of the supplied
address list.

USAGE

     dcl  mail_system_$add_address entry (pointer, pointer,
               character (8), fixed binary (35)));

     call mail_system_$add_address (address_list_ptr,
               address_ptr, address_list_version, code);

ARGUMENTS

address_list_ptr    (Input/Output)
          is a  pointer to an address_list  structure or is null.
          If non-null, the supplied address  will be added to the
          end of this  list; if null, a new  address_list will be
          created with the supplied address  as the only entry in
          the list.  In either case, this pointer will be updated
          to  locate the  revised address_list  structure and the
          old structure, if any, will be destroyed.

address_ptr         (Input)
          is a pointer to the address  to be added to the address
          list.

address_list_version
                    (Input)
          is  the  version of  the  address_list structure  to be
          created by this entrypoint if address_list_ptr above is
          null on input.  The only version supported at this time
          is   given  by   the  value   of  the   named  constant
          ADDRESS_LIST_VERSION_2    in     the    include    file
          mlsys_address_list.incl.pl1.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address_list
                    The   storage  identified   by  the  supplied
                    address_list_ptr is not an address list.

          mlsys_et_$not_address
                    The   storage  identified   by  the  supplied
                    address_ptr is not an address.

          error_table_$unimplemented_version
                    The  address_list_ptr was  null on  input and
                    the  caller  requested   the  creation  of  a
                    version of the address_list structure that is
                    not supported by the mail system.

             ________________________________________

Entry:  mail_system_$add_body_section

     This entrypoint adds a section to  the message body of a new
message.

USAGE

     dcl  mail_system_$add_body_section entry (pointer, pointer,
               fixed binary, fixed binary (35));

     call mail_system_$add_body_section (message_ptr,
               message_body_section_parameter_ptr, position,
               code);

ARGUMENTS

message_ptr         (Input/Output)
          is  a  pointer  to  the  new  message  which  is  to be
          modified.  This  pointer will be updated  to locate the
          revised message structure and the old structure will be
          destroyed.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

message_body_section_parameter_ptr
                    (Input)
          is   a  pointer   to  a  message_body_section_parameter
          structure.  This structure, which describes the section
          to   be  added,   is  defined   in  the   include  file
          mlsys_message.incl.pl1 as follows:

               dcl 1 message_body_section_parameter
                                   aligned based
                                   (message_body_section_parameter_ptr),
                     2 version     character (8) unaligned,
                     2 section     like message_body_section;

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    MESSAGE_BODY_SECTION_PARAMETER_VERSION_2.

          section             (Input)
                    is  the section  to be  added to  the message
                    body.     See   the    description   of   the
                    message_body_section  structure  in Section 1
                    of this  document for a  detailed explanation
                    of the contents of this structure.

position            (Input/Output)
          specifies  where this  section is  to be  placed in the
          body  of  the message.   If  position is  0 or  1, this
          section will be placed before the first section already
          in  the body;  if position is  2, this  section will be
          placed before  the second section already  in the body,
          etc.  If the value of position is -1, this section will
          be placed  after the last section  already in the body;
          if position  is -2, this  section will be  placed after
          the  next to  last section  in the  body, etc.   If the
          absolute value of position is larger than the number of
          sections  already  in the  body,  this section  will be
          placed after  the last section if  position is positive
          or  before the  first section if  position is negative.
          This parameter will then be  set to the actual position
          of the new section within the body.

code                (Output)
          is a standard system status code.  Amongst the possible


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$not_new_message
                    The   storage  identified   by  the  supplied
                    message_ptr  is an  in-mailbox message rather
                    than a new message.

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    message_body_section_parameter structure that
                    is not supported by the mail system.

          mlsys_et_$unknown_body_section_type
                    The type of message body section specified is
                    not recognized by the mail system.

             ________________________________________

Entry:  mail_system_$add_reply_reference

     This entrypoint adds a reference to the specified in-mailbox
message at  the end of the  list of messages for  which the given
new message is a reply.

USAGE

     dcl  mail_system_$add_reply_reference entry (pointer,
               pointer, fixed binary (35));

     call mail_system_$add_reply_reference (message_ptr,
               referenced_message_ptr, code);

ARGUMENTS

message_ptr         (Input/Output)
          is  a  pointer  to  the  new  message  which  is  to be
          modified.  This  pointer will be updated  to locate the
          revised message structure and the old structure will be
          destroyed.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

referenced_message_ptr
                    (Input)
          is a pointer  to the in-mailbox message which  is to be
          referenced by the new message.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The storage identified  by either message_ptr
                    or referenced_message_ptr is not a message.

          mlsys_et_$not_in_mailbox_message
                    The   storage  identified   by  the  supplied
                    referenced_message_ptr   is  a   new  message
                    rather than an in-mailbox message.

          mlsys_et_$not_new_message
                    The   storage  identified   by  the  supplied
                    message_ptr  is an  in-mailbox message rather
                    than a new message.

          mlsys_et_$duplicate_reply_reference
                    A reference  to the given  in-mailbox message
                    is already present in the list of messages to
                    which the supplied new message is a reply.

             ________________________________________

Entry:  mail_system_$add_user_field

     This  entrypoint adds  a user-defined  field to  the message
header of a new message.

USAGE

     dcl  mail_system_$add_user_field entry (pointer, pointer,
               fixed binary, bit (1) aligned, fixed binary (35));

     call mail_system_$add_user_field (message_ptr,
               message_user_field_parameter_ptr, position,
               allow_dupicates, code);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

ARGUMENTS

message_ptr         (Input/Output)
          is  a  pointer  to  the  new  message  which  is  to be
          modified.  This  pointer will be updated  to locate the
          revised message structure and the old structure will be
          destroyed.

message_user_field_parameter_ptr
                    (Input)
          is   a   pointer   to   a  message_user_field_parameter
          structure.    This   structure,  which   describes  the
          user-defined  field  to  be  added, is  defined  in the
          include file mlsys_message.incl.pl1 as follows:

               dcl 1 message_user_field_parameter
                                   aligned based
                                   (message_user_field_parameter_ptr),
                     2 version     character (8) unaligned,
                     2 user_field  like message_user_field;

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    MESSAGE_USER_FIELD_PARAMETER_VERSION_2.

          section             (Input)
                    is the user-defined field  to be added to the
                    message.    See   the   description   of  the
                    message_user_field structure  in Section 1 of
                    this document  for a detailed  explanation of
                    the contents of this structure.

position            (Input/Output)
          specifies where this user-defined field is to be placed
          in  the  list  of  user-defined fields  in  the message
          header.   If position  is 0  or 1,  this field  will be
          placed before the first field already in the header; if
          position  is 2,  this field  will be  placed before the
          second field already in the  header, etc.  If the value
          of position is -1, this  field will be placed after the
          last field  already in the  header; if position  is -2,
          this field will be placed  after the next to last field
          in the header, etc.  If  the absolute value of position


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

          is  larger  than  the  number  of  user-defined  fields
          already in the header, this  field will be placed after
          the last  field if position  is positive or  before the
          first  field if  position is  negative.  This parameter
          will  then be  set to  the actual  position of  the new
          user-defined field within the message header.

allow_duplicates    (Input)
          if "1"b, this field will be added to the message header
          even  if there  is a  user-defined field  with the same
          field ID already present in  the header.  If "0"b, this
          field will  not be added under  these circumstances and
          the  position  parameter,  above,  will be  set  to the
          position of the first duplicate field in the header.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$not_new_message
                    The   storage  identified   by  the  supplied
                    message_ptr  is an  in-mailbox message rather
                    than a new message.

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    message_user_field_parameter  structure  that
                    is not supported by the mail system.

          mlsys_et_$unknown_user_field_id
                    The   field   ID   specified   for   the  new
                    user-defined  field  has not  been registered
                    with  the  mail system  via  a prior  call to
                    mail_system_$get_user_field_id.

          mlsys_et_$unknown_user_field_type
                    The type  of user-defined field  specified is
                    not recognized by the mail system.

          mlsys_et_$duplicate_user_field
                    At least one user-defined field with the same


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

                    field  ID  as the  supplied field  is already
                    present in the message header.

             ________________________________________

Entry:  mail_system_$close_mailbox

     This  entrypoint  closes  a  mailbox  by  freeing  all  data
structures  associated  with the  mailbox  and its  messages and,
optionally, deleting those messages indentified by prior calls to
mail_system_$mark_message_for_deletion.

USAGE

     dcl  mail_system_$close_mailbox entry (pointer, pointer,
               fixed binary (35));

     call mail_system_$close_mailbox (mailbox_ptr,
               close_options_ptr, code);

ARGUMENTS

mailbox_ptr         (Input/Output)
          is  a pointer  to the mailbox  structure describing the
          mailbox to be closed.  This pointer will be set to null
          if the mailbox is successfully closed.

close_options_ptr   (Input)
          is  a  pointer  to   a  close_options  structure.   The
          close_options structure is defined  in the include file
          mlsys_close_options.incl.pl1 as follows:

               dcl 1 close_options aligned
                                   based (close_options_ptr)
                     2 version     character (8) unaligned
                     2 flags,
                       3 perform_deletions
                                   bit (1) unaligned,
                       3 report_deletion_errors
                                   bit (1) unaligned,
                       3 mbz       bit (34) unaligned;

          where:


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    CLOSE_OPTIONS_VERSION_2.

          flags.perform_deletions
                              (Input)
                    if "1"b,  those messages marked  for deletion
                    will  be deleted  from the  mailbox as  it is
                    closed.  If "0"b, no messages will be deleted
                    from the mailbox.

          flags.report_deletion_errors
                              (Input)
                    if "1"b, any failure to delete a message will
                    be  reported  via  a   call  to  sub_err_  as
                    documented below.  If "0"b, individual errors
                    will  not  be  reported  while  deleting  the
                    marked  messages.  In  either case,  a global
                    status code will  indicate that some messages
                    were not deleted.

          flags.mbz           (Input)
                    is reserved for future  expansion and must be
                    ""b.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_mailbox
                    The   storage  identified   by  the  supplied
                    mailbox_ptr is not a mailbox structure.

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    close_options structure that is not supported
                    by the mail system.

          mlsys_et_$some_messages_not_deleted
                    The mail system was  unable to delete some of
                    the messages which  were marked for deletion.
                    If  the  report_deletion_errors  flag  in the
                    close_options   structure  was   set  by  the


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

                    caller, the exact cause of each failure would
                    have been reported by a call to sub_err_.

NOTES

     If  the  report_deletion_errors  flag  in  the close_options
structure is set by the caller,  each failure to delete a message
will result  in a call  to sub_err_.  See the  description of the
mail_system_$expunge_messages    entrypoint   for    a   complete
explanation of the implications of and data structures associated
with this call to sub_err_.

     As       explained       in       the       writeup       of
mail_system_$expunge_messages, the caller of this entrypoint must
call        either        mail_system_$expunge_messages        or
mail_system_$abort_delete_operation after handling the sub_error_
condition.   However, for  a call  to mail_system_$close_mailbox,
the  caller  must  use  mail_system_$close_mailbox  in  place  of
mail_system_$expunge_messages  after handling  the condition.  If
mail_system_$close_mailbox is called again,  the mail system will
continue  to  delete  the  marked  messages  and  then  close the
mailbox.   If mail_system_$abort_delete_operation  is called, the
mail system will not perform any more deletions nor will it close
the mailbox; instead, it will return an updated mailbox structure
which reflects  those deletions that were  successfull before the
reported error occured.

             ________________________________________

Entry:  mail_system_$compare_addresses

     This  entrypoint compares  two addresses  for equality.  Two
addresses are considered equivalent if mail transmitted to either
address will be  delivered to the same set  of mailboxes, foreign
addresses, and forum meetings.

USAGE

     dcl  mail_system_$compare_addresses entry (pointer, pointer,
               fixed binary (35)) returns (bit (1) aligned);

     same_address =
               mail_system_$compare_addresses (address_ptr_1,
               address_ptr_2, code);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

ARGUMENTS

address_ptr_1       (Input)
address_ptr_2       (Input)
          are  pointers  to  the  addresses  to  be  compared for
          equality.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address
                    The   storage  identified   by  address_ptr_1
                    and/or address_ptr_2 is not an address.

same_address        (Output)
          is  set to  "1"b if  the supplied  addresses are equal;
          otherwise, it is set to "0"b.

             ________________________________________

Entry:  mail_system_$create_address_list

     This entrypoint creates an empty address list.

USAGE

     dcl  mail_system_$create_address_list entry (character (8),
               pointer, fixed binary (35));

     call mail_system_$create_address_list (address_list_version,
               address_list_ptr, code);

ARGUMENTS

address_list_ptr    (Input)
          is the version of  address_list structure to be created
          by  this entrypoint.   The only  supported address_list
          version at this time is given by the value of the named
          constant  ADDRESS_LIST_VERSION_2  in  the  include file
          mlsys_address_list.incl.pl1.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

address_list_ptr    (Output)
          is  a   pointer  the  address  list   created  by  this
          entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    The  caller  requested   the  creation  of  a
                    version of the address_list structure that is
                    not supported by the mail system.

             ________________________________________

Entry:  mail_system_$create_foreign_address

     This  entrypoint   creates  a  mail   system  address  which
identifies a user (or group of users) on another computer system.
See  the  description  of  address types  and  address  routes in
Section 1 of this document for more information.

USAGE

     dcl  mail_system_$create_foreign_address entry
               (character (*) varying, character (256) varying,
               pointer, character (*) varying,
               character (*) varying, pointer,
               fixed binary (35));

     call mail_system_$create_foreign_address (address_string,
               foreign_system, address_route_ptr, address_name,
               address_comment, address_ptr, code);

ARGUMENTS

address_string      (Input)
          is the  address on the foreign  system.  The local mail
          system  will  not  attempt  to validate  the  syntax or
          semantics of this string.

foreign_system      (Input)
          is the  name of the  foreign system.  This  system name


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

          need   not  appear   in  the   local  system's  network
          information table (NIT).

address_route_ptr   (Input)
          is a pointer to an address_route structure or null.  If
          non-null,  the  supplied  address   route  must  be  an
          explicit route as described in Section 1.

address_name        (Input)
          is  an  optional  address  name  to  be  given  to this
          address.

address_comment     (Input)
          is  an  optional address  comment to  be given  to this
          address.

address_ptr         (Output)
          is   set  to   locate  the  address   created  by  this
          entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemnted_version
                    The  version  of the  address_route structure
                    supplied  by the  caller is  not supported by
                    the mail system.

          mlsys_et_$not_explicit_routing
                    The address  route supplied by  the caller is
                    an implicit route.

NOTES

     This   entrypoint  creates   the  foreign   address  without
verifying that  mail can actually  be delivered to  the specified
address.   The  mail_system_$validate_address  entrypoint  may be
used  to determine  whether mail can  indeed be  delivered to the
address created by this entrypoint.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$create_forum_address

     This  entrypoint   creates  a  mail   system  address  which
identifies a  Forum meeting by pathname.   See the description of
address types in Section 1 of this document for more information.

USAGE

     dcl  mail_system_$create_forum_address entry (character (*),
               character (*) varying, character (*) varying,
               pointer, fixed binary (35));

     call mail_system_$create_forum_address (address_pathname,
               address_name, address_comment, address_ptr, code);

ARGUMENTS

address_pathname    (Input)
          is  the  absolute  or  relative pathname  of  the forum
          meeting which  will receive any mail  delivered to this
          address.   The suffix  control need not  be included in
          the pathname supplied by the caller.

address_name        (Input)
          is  an  optional  address  name  to  be  given  to this
          address.

address_comment     (Input)
          is  an  optional address  comment to  be given  to this
          address.

address_ptr         (Output)
          is   set  to   locate  the  address   created  by  this
          entrypoint.

code                (Output)
          is a standard  system status code.  It may  have any of
          the values returned  by the expand_pathname_$add_suffix
          entrypoint as documented in Multics Subroutines and I/O
          Modules.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

NOTES

This entrypoint creates the  forum address without verifying that
the specified forum  actually exists or that the  user is allowed
to     enter    transactions     into    the     meeting.     The
mail_system_$validate_address entrypoint may be used to determine
whether mail  can indeed be  delivered to the  address created by
this entrypoint.

             ________________________________________

Entry:  mail_system_$create_invalid_address

     This  entrypoint   creates  a  mail   system  address  which
represents a character string found in the printed representation
of  a message  that does  not correspond to  any of  the types of
address  supported by  the mail  system.  See  the description of
address types in Section 1 of this document for more information.

USAGE

     dcl  mail_system_$create_invalid_address entry
               (character (*) varying, character (*) varying,
               character (*) varying, pointer,
               fixed binary (35));

     call mail_system_$create_invalid_address (address_string,
               address_name, address_comment, address_ptr, code);

ARGUMENTS

address_string      (Input)
          is the text which comprises the invalid address.

address_name        (Input)
          is  an  optional  address  name  to  be  given  to this
          address.

address_comment     (Input)
          is  an  optional address  comment to  be given  to this
          address.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

address_ptr         (Output)
          is   set  to   locate  the  address   created  by  this
          entrypoint.

code                (Output)
          is a standard system status code.

             ________________________________________

Entry:  mail_system_$create_logbox_address

     This  entrypoint   creates  a  mail   system  address  which
identifies the  specified user's logbox.  See  the description of
address types in Section 1 of this document for more information.

USAGE

     dcl  mail_system_$create_logbox_address entry
               (character (*) varying, character (*) varying,
               character (*) varying, pointer,
               fixed binary (35));

     call mail_system_$create_logbox_address (address_string,
               address_name, address_comment, code);

ARGUMENTS

address_string      (Input)
          is the  User_id of the  user whose logbox  will receive
          any mail delivered to this address.  The format of this
          User_id is Person_id.Project_id.

address_name        (Input)
          is  an  optional  address  name  to  be  given  to this
          address.

address_comment     (Input)
          is  an  optional address  comment to  be given  to this
          address.

address_ptr         (Output)
          is   set  to   locate  the  address   created  by  this
          entrypoint.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$invalid_user_id_syntax
                    The   supplied   User_id   is   not  properly
                    formatted.  Said  User_id contains whitespace
                    or  angle  brackets (<>),  does  not  contain
                    exactly one period (.),  contains a Person_id
                    over 25  characters in length,  or contains a
                    Project_id over 32 characters in length.

NOTES

This entrypoint creates the logbox address without verifying that
the  specified  logbox  actually  exists  or  that  the  user has
sufficient     access     to     use     the     logbox.      The
mail_system_$validate_address entrypoint may be used to determine
whether mail  can indeed be  delivered to the  address created by
this entrypoint.

             ________________________________________

Entry:  mail_system_$create_mail_table_address

     This  entrypoint   creates  a  mail   system  address  which
identifies the  specified entry in the  system's mail table.  See
the description  of address types  in Section 1 of  this document
for more information.

USAGE

     dcl  mail_system_$create_mail_table_address entry
               (character (*) varying, character (*) varying,
               character (*) varying, pointer,
               fixed binary (35));

     call mail_system_$create_mail_table_address (address_string,
               address_name, address_comment, code);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

ARGUMENTS

address_string      (Input)
          is the name of the mail table entry.

address_name        (Input)
          is  an  optional  address  name  to  be  given  to this
          address.

address_comment     (Input)
          is  an  optional address  comment to  be given  to this
          address.

address_ptr         (Output)
          is   set  to   locate  the  address   created  by  this
          entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$invalid_mte_syntax
                    The name supplied for the mail table entry is
                    not properly formatted.   Said name is either
                    over  32  characters  in  length  or contains
                    commas, colons, semi-colons, backslashes (),
                    parentheses,       angle       brackets (<>),
                    braces ({}),      quotes ("),      commerical
                    at-signs (@),   or   whitespace   other  than
                    spaces.

NOTES

This entrypoint creates the  mail table address without verifying
that the specified  mail table entry actually exists  or that the
user can actually deliver mail  to the address referenced by said
mail  table entry.   The mail_system_$validate_address entrypoint
may be used to determine whether  mail can indeed be delivered to
the address created by this entrypoint.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$create_mailbox_address

     This  entrypoint   creates  a  mail   system  address  which
identifies an arbitrary mailbox by pathname.  See the description
of  address  types  in  Section 1   of  this  document  for  more
information.

USAGE

     dcl  mail_system_$create_mailbox_address entry
               (character (*), character (*) varying,
               character (*) varying, pointer,
               fixed binary (35));

     call mail_system_$create_mailbox_address (address_pathname,
               address_name, address_comment, address_ptr, code);

ARGUMENTS

address_pathname    (Input)
          is  the absolute  or relative  pathname of  the mailbox
          which will receive any  mail delivered to this address.
          The  suffix mbx  need not  be included  in the pathname
          supplied by the caller.

address_name        (Input)
          is  an  optional  address  name  to  be  given  to this
          address.

address_comment     (Input)
          is  an  optional address  comment to  be given  to this
          address.

address_ptr         (Output)
          is   set  to   locate  the  address   created  by  this
          entrypoint.

code                (Output)
          is a standard  system status code.  It may  have any of
          the values returned  by the expand_pathname_$add_suffix
          entrypoint as documented in Multics Subroutines and I/O
          Modules.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

NOTES

This  entrypoint  creates the  mailbox address  without verifying
that the specified  mailbox actually exists or that  the user has
sufficient     access     to     use     the     mailbox.     The
mail_system_$validate_address entrypoint may be used to determine
whether mail  can indeed be  delivered to the  address created by
this entrypoint.

             ________________________________________

Entry:  mail_system_$create_mailing_list_address

     This  entrypoint   creates  a  mail   system  address  which
identifies a  mailing list by  pathname.  See the  description of
address types in Section 1 of this document for more information.

USAGE

     dcl  mail_system_$create_mailing_list_address entry
               (character (*), character (*) varying,
               character (*) varying, pointer,
               fixed binary (35));

     call mail_system_$create_mailing_list_address
               (address_pathname, address_name, address_comment,
               address_ptr, code);

ARGUMENTS

address_pathname    (Input)
          is  the absolute  or relative  pathname of  the mailing
          list  which  will receive  any  mail delivered  to this
          address.  The  suffix mls need  not be included  in the
          pathname supplied by the caller.  The archive component
          pathname convention is accepted.

address_name        (Input)
          is  an  optional  address  name  to  be  given  to this
          address.

address_comment     (Input)
          is  an  optional address  comment to  be given  to this
          address.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

address_ptr         (Output)
          is   set  to   locate  the  address   created  by  this
          entrypoint.

code                (Output)
          is a standard  system status code.  It may  have any of
          the        values         returned        by        the
          expand_pathname_$component_add_suffix   entrypoint   as
          documented in Multics Subroutines and I/O Modules.

NOTES

This  entrypoint   creates  the  mailing   list  address  without
verifying that the specified mailing list actually exists or that
the  user has  sufficient access  to use  the mailing  list.  The
mail_system_$validate_address entrypoint may be used to determine
whether mail  can indeed be  delivered to the  address created by
this entrypoint.

             ________________________________________

Entry:  mail_system_$create_message

     This entrypoint creates a new message.

USAGE

     dcl  mail_system_$create_message entry (character (8),
               pointer, fixed binary (35));

     call mail_system_$create_message (message_version,
               message_ptr, code);

ARGUMENTS

message_version     (Input)
          is the  version of the message  structure to be created
          by this entrypoint.  The only version supported at this
          time  is  given  by  the value  of  the  named constant
          MESSAGE_VERSION_2      in     the      include     file
          mlsys_message.incl.pl1.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

message_ptr         (Output)
          is a pointer the message created by this entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    The  caller  requested   the  creation  of  a
                    version of the message  structure that is not
                    supported by the mail system.

NOTES

     The message  created by this entrypoint  has no content.  In
other words, there are no sections in its message body and all of
the fields  in its message header  (authors, recipients, subject,
reply   references,   user-defined   fields)   are   empty.   The
application or  subsystem should use  the appropriate entrypoints
described elsewhere in this document to construct the message.

     See   the  mail_system_$deliver_message   entrypoint  for  a
description of  the default values  given to those  fields in the
message which  were not set  by the caller  prior to transmitting
the message.

             ________________________________________

Entry:  mail_system_$create_named_group_address

     This  entrypoint   creates  a  mail   system  address  which
identifies a  named group of  addresses.  See the  description of
address types in Section 1 of this document for more information.

USAGE

     dcl  mail_system_$create_named_group_address entry
               (character (*) varying, pointer, bit (1) aligned,
               character (*) varying, pointer,
               fixed binary (35));

     call mail_system_$create_named_group_address (address_name,


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

               address_list_ptr, display_list, address_comment,
               address_ptr, code);

ARGUMENTS

address_name        (Input)
          is the name of the group.

address_list_ptr    (Input)
          is  a  pointer to  the address  list which  defines the
          members of the named group.

display_list        (Input)
          if  "1"b,  the  members  of  the  named  group  will be
          displayed in addition  to the name of the  group in the
          printed representation  of this address;  if "0"b, only
          the name of the group  will be displayed in the printed
          representation.

address_comment     (Input)
          is  an  optional address  comment to  be given  to this
          address.

address_ptr         (Output)
          is   set  to   locate  the  address   created  by  this
          entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address_list
                    The   storage  identified   by  the  supplied
                    address_list_ptr is not an address list.

NOTES

This entrypoint creates the named group address without verifying
that  mail  can actually  be  delivered to  the addresses  in the
group.  The mail_system_$validate_address  entrypoint may be used
to determine whether mail can  indeed be delivered to the address
created by this entrypoint.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$create_savebox_address

     This  entrypoint   creates  a  mail   system  address  which
identifies  one  of  the  specified  user's  saveboxes.   See the
description of  address types in  Section 1 of this  document for
more information.

USAGE

     dcl  mail_system_$create_savebox_address entry
               (character (*) varying, character (*),
               character (*) varying, character (*) varying,
               pointer, fixed binary (35));

     call mail_system_$create_savebox_address (address_string,
               address_pathname, address_name, address_comment,
               code);

ARGUMENTS

address_string      (Input)
          is the User_id of the  user who owns the given savebox.
          The format of this User_id is Person_id.Project_id.

address_pathname    (Input)
          is  the absolute  or relative  pathname of  the savebox
          which will receive any  mail delivered to this address.
          The suffix sv.mbx need not  be included in the pathname
          supplied by the caller.

address_name        (Input)
          is  an  optional  address  name  to  be  given  to this
          address.

address_comment     (Input)
          is  an  optional address  comment to  be given  to this
          address.

address_ptr         (Output)
          is   set  to   locate  the  address   created  by  this
          entrypoint.

code                (Output)
          is a standard  system status code.  It may  have any of
          the values returned  by the expand_pathname_$add_suffix


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

          entrypoint as documented in Multics Subroutines and I/O
          Modules.   In addition,  the following status codes may
          also be returned:

          mlsys_et_$invalid_user_id_syntax
                    The   supplied   User_id   is   not  properly
                    formatted.  Said  User_id contains whitespace
                    or  angle  brackets (<>),  does  not  contain
                    exactly one period (.),  contains a Person_id
                    over 28  characters in length,  or contains a
                    Project_id over 32 characters in length.

NOTES

This  entrypoint  creates the  savebox address  without verifying
that the specified  savebox actually exists or that  the user has
sufficient     access     to     use     the     savebox.     The
mail_system_$validate_address entrypoint may be used to determine
whether mail  can indeed be  delivered to the  address created by
this entrypoint.

             ________________________________________

Entry:  mail_system_$create_user_mailbox_address

     This  entrypoint   creates  a  mail   system  address  which
identifies  the  specified  user's   default  mailbox.   See  the
description of  address types in  Section 1 of this  document for
more information.

USAGE

     dcl  mail_system_$create_user_mailbox_address entry
               (character (*) varying, character (*) varying,
               character (*) varying, pointer,
               fixed binary (35));

     call mail_system_$create_user_mailbox_address
               (address_string, address_name, address_comment,
               code);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

ARGUMENTS

address_string      (Input)
          is the  User_id of the user  whose default mailbox will
          receive any mail delivered to this address.  The format
          of this User_id is Person_id.Project_id.

address_name        (Input)
          is  an  optional  address  name  to  be  given  to this
          address.

address_comment     (Input)
          is  an  optional address  comment to  be given  to this
          address.

address_ptr         (Output)
          is   set  to   locate  the  address   created  by  this
          entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$invalid_user_id_syntax
                    The   supplied   User_id   is   not  properly
                    formatted.  Said  User_id contains whitespace
                    or  angle  brackets (<>),  does  not  contain
                    exactly one period (.),  contains a Person_id
                    over 28  characters in length,  or contains a
                    Project_id over 32 characters in length.

NOTES

This  entrypoint   creates  the  user   mailbox  address  without
verifying that  the specified default mailbox  actually exists or
that  the user  has sufficient  access to  use the  mailbox.  The
mail_system_$validate_address entrypoint may be used to determine
whether mail  can indeed be  delivered to the  address created by
this entrypoint.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$delete_address

     This entrypoint deletes an address from the supplied address
list.

USAGE

     dcl  mail_system_$delete_address entry (pointer,
               fixed binary, fixed binary (35));

     call mail_system_$delete_address (address_list_ptr,
               address_position, code);

ARGUMENTS

address_list_ptr    (Input/Output)
          is  a  pointer  to  the address  list  which  is  to be
          modified.  This  pointer will be updated  to locate the
          revised  address_list structure  and the  old structure
          will be destroyed.

address_position    (Input)
          is  the index  within the  address list  of the address
          that is to be deleted.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address_list
                    The   storage  identified   by  the  supplied
                    address_list_ptr is not an address list.

          error_table_$bad_index
                    The specified address_position is either less
                    than  one  or  greater  than  the  number  of
                    addresses in the list.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$delete_body_section

     This  entrypoint  deletes  a  section  of  the  body  in the
supplied new message.

USAGE

     dcl  mail_system_$delete_body_section entry (pointer,
               fixed binary, fixed binary (35));

     call mail_system_$delete_body_section (message_ptr,
               section_position, code);

ARGUMENTS

message_ptr         (Input/Output)
          is  a  pointer  to  the  new  message  which  is  to be
          modified.  This  pointer will be updated  to locate the
          revised message structure and the old structure will be
          destroyed.

section_position    (Input)
          is  the index  within the  message body  of the section
          that is to be deleted.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$not_new_message
                    The   storage  identified   by  the  supplied
                    message_ptr  is an  in-mailbox message rather
                    than a new message.

          error_table_$bad_index
                    The specified section_position is either less
                    than  one  or  greater  than  the  number  of
                    sections in the message body.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$delete_reply_reference

     This entrypoint  deletes a reference to  one of the messages
for which the supplied new message is a reply.

USAGE

     dcl  mail_system_$delete_reply_reference entry (pointer,
               fixed binary, fixed binary (35));

     call mail_system_$delete_reply_reference (message_ptr,
               reply_reference_position, code);

ARGUMENTS

message_ptr         (Input/Output)
          is  a  pointer  to  the  new  message  which  is  to be
          modified.  This  pointer will be updated  to locate the
          revised message structure and the old structure will be
          destroyed.

reply_reference_position
                    (Input)
          is the index within the list of reply references of the
          reference that is to be deleted.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$not_new_message
                    The   storage  identified   by  the  supplied
                    message_ptr  is an  in-mailbox message rather
                    than a new message.

          error_table_$bad_index
                    The  specified   reply_reference_position  is
                    either  less  than  one or  greater  than the
                    number  of  reply references  in  the message
                    header.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$delete_user_field

     This entrypoint  deletes a user-defined field  in the header
of the supplied new message.

USAGE

     dcl  mail_system_$delete_user_field entry (pointer,
               fixed binary, fixed binary (35));

     call mail_system_$delete_user_field (message_ptr,
               user_field_position, code);

ARGUMENTS

message_ptr         (Input/Output)
          is  a  pointer  to  the  new  message  which  is  to be
          modified.  This  pointer will be updated  to locate the
          revised message structure and the old structure will be
          destroyed.

user_field_position (Input)
          is the index within the  list of user-defined fields of
          the field to be deleted.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$not_new_message
                    The   storage  identified   by  the  supplied
                    message_ptr  is an  in-mailbox message rather
                    than a new message.

          error_table_$bad_index
                    The  specified user_field_position  is either
                    less than  one or greater than  the number of
                    user-defined fields in the message header.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$deliver_message

     This entrypoint transmits a new message to the supplied list
of recipients.

USAGE

     dcl  mail_system_$deliver_message entry (pointer, pointer,
               pointer, fixed binary (35));

     call mail_system_$deliver_message (message_ptr,
               recipients_info_ptr, deliver_options_ptr, code);

ARGUMENTS

message_ptr         (Input)
          is a pointer to the message to be transmitted.

recipients_info_ptr (Input)
          is  a  pointer  to  a  recipients_info  structure which
          defines the  recipients of the message  and the results
          of  transmission  for each  recipient.   This structure
          and,  unless  stated  otherwise,  all  named  constants
          mentioned  here   are  defined  in   the  include  file
          mlsys_deliver_info.incl.pl1.

               dcl 1 recipients_info
                                   aligned based
                                   (recipients_info_ptr),
                     2 header,
                       3 version   character (8) unaligned,
                       3 area_ptr  pointer
                       3 expanded_recipients_result_list_ptr
                                   pointer,
                       3 n_recipients
                                   fixed binary,
                       3 n_unique_recipients
                                   fixed binary,
                       3 n_failed_recipients
                                   fixed binary,
                       3 n_lists   fixed binary,
                     2 lists       (recipients_info_n_lists refer
                                   (recipients_info.n_lists)),
                       3 address_list_ptr
                                   pointer,


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

                       3 recipients_result_list_ptr
                                   pointer;

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is  given  by  the  value  of  named constant
                    RECIPIENTS_INFO_VERSION_2.

          area_ptr            (Input)
                    is  a pointer  to a  caller supplied  area in
                    which  the  mail  system  will  allocate  the
                    recipients_result_list                    and
                    expanded_recipients_result_list    structures
                    described  below.  If  this pointer  is null,
                    the  mail  system  will use  the  system free
                    area.

          expanded_recipients_result_list_ptr
                              (Output)
                    is        set       to        locate       an
                    expanded_recipients_result_list    structure,
                    described below, if  any errors were detected
                    for  one  or  more addresses  contained  in a
                    mailing list  or named group  address.  If no
                    errors  of  this   type  are  detected,  this
                    pointer will be set to null.

          n_recipients        (Output)
                    is set  to the total number  of recipients in
                    the  supplied  address lists  after expanding
                    all mailing list and named group addresses.

          n_unique_recipients (Output)
                    is  set   to  the  total   number  of  unique
                    recipients.

          n_failed_recipients (Output)
                    is set to the  number of recipients for which
                    the mail  system detected a fatal  error or a
                    transient  error when  not queueing transient
                    errors.    See   the   descriptions   of  the
                    queueing_mode  and  abort  options  below for
                    further information.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

          n_lists             (Input)
                    is the number of address lists which comprise
                    the recipients of the message.

          lists               (Input/Output)
                    describes  the  individual  recipient address
                    lists  and  the results  for each  address in
                    these lists.

            address_list_ptr    (Input)
                      is  a pointer  to one of  the address lists
                      which  defines  some of  the  recipients of
                      this message.

            recipients_result_list_ptr
                                (Ouptut)
                      is    set    to    a    pointer    to   the
                      recipients_result_list structure, described
                      below,  which defines  the results  of this
                      operation  for the  addresses in  the above
                      list.

deliver_options_ptr (Input)
          is  a  pointer  to  a  deliver_options  structure which
          defines the  options which control the  deliver of this
          message.  This structure  and, unless stated otherwise,
          all named  constants mentioned here are  defined in the
          include file mlsys_deliver_info.incl.pl1.

               dcl 1 deliver_options
                                   aligned based
                                   (deliver_options_ptr),
                     2 version     character (8) unaligned,
                     2 delivery_mode
                                   fixed binary,
                     2 queueing_mode
                                   fixed binary,
                     2 queued_notification_mode
                                   fixed binary,
                     2 flags,
                       3 abort     bit (1) unaligned,
                       3 send_if_empty
                                   bit (1) unaligned,
                       3 recipient_notification
                                   bit (1) unaligned,
                       3 acknowledge
                                   bit (1) unaligned,


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

                       3 queue_mailing_lists
                                   bit (1) unaligned,
                       3 mbz       bit (31) unaligned;

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    DELIVER_OPTIONS_VERSION_2.

          delivery_mode       (Input)
                    specifies how the message should be delivered
                    to the recipients.  The possible settings for
                    this  option are  given by the  values of the
                    following named constants:

                    ORDINARY_DELIVERY
                              specifies that the message is to be
                              delivered  as an  ordinary message.
                              If the recipient  is logged in when
                              the   message   arrives   and   the
                              recipient_notification   option  is
                              requested,  an indication  that the
                              message has arrived is displayed on
                              the recipient's terminal.

                    INTERACTIVE_DELIVERY
                              specifies that the message is to be
                              delivered    as    an   interactive
                              message.    If  the   recipient  is
                              logged in when the message arrives,
                              it will be immediately displayed on
                              his   terminal.    Otherwise,   the
                              message  will be  delivered like an
                              ordinary  message but  marked as an
                              interactive  message so  that, when
                              the  recipient  next logs  into the
                              system, it will be displayed on his
                              terminal.

                    EXPRESS_DELIVERY
                              specifies that the message is to be
                              delivered as an interactive message
                              but only if the recipient is logged
                              in   when   it  arrives.    If  the


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

                              recipient is not logged in when the
                              message  arrives, the  message will
                              be discarded.

          queueing_mode       (Input)
                    specifies when  (if ever) the  message should
                    be  queued  for  later delivery  by  a mailer
                    daemon  process.   The possible  settings for
                    this  option are  given by the  values of the
                    following named constants:

                    NEVER_QUEUE
                              specifies  that   the  mail  system
                              should   attempt  to   deliver  the
                              message    to     all    recipients
                              immediately.  Any  transient errors
                              (see  below) are  considered fatal.
                              However  as  these  errors  are not
                              detected until  after processing of
                              the   abort  option,   it  will  be
                              possible  for  the  message  to  be
                              delivered/queued  for some  but not
                              all  of the  recipients against the
                              caller's wishes.

                    QUEUE_FOREIGN_WHEN_NEEDED
                              specifies  that   the  mail  system
                              should   attempt  to   deliver  the
                              message    to     all    recipients
                              immediately.  Any  transient errors
                              for  foreign recipients  will cause
                              the message to  be queued for those
                              recipients.   Any  transient errors
                              for   local   recipients   will  be
                              considered fatal.  However as these
                              errors are not detected until after
                              processing of the  abort option, it
                              will be possible for the message to
                              be  delivered/queued  for  some but
                              not  all of  the recipients against
                              the caller's wishes.

                    QUEUE_WHEN_NEEDED
                              specifies  that   the  mail  system
                              should   attempt  to   deliver  the
                              message    to     all    recipients
                              immediately.  Any  transient errors


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

                              for  any recipients  will cause the
                              message  to  be  queued  for  those
                              recipients.

                    ALWAYS_QUEUE_FOREIGN
                              specifies  that   the  mail  system
                              should  queue  the message  for all
                              foreign  recipients  without making
                              any attempt  to deliver it  to them
                              immediately.  For local recipients,
                              the  mail  system  will  attempt to
                              deliver  the   message  immediately
                              and, if transient  errors occur, it
                              will  queue  the message  for those
                              local recipients.

                    ALWAYS_QUEUE
                              specifies  that   the  mail  system
                              should  queue  the message  for all
                              recipients   without   making   any
                              attempt to deliver it immediately.

          queued_notification_mode
                              (Input)
                    specifies  when (if  ever) the  sender of the
                    message should be notified  of the success or
                    failure  of  the mail  system to  deliver the
                    message to  a queue recipient.   The possible
                    settings  for  this option  are given  by the
                    values of the following named constants:

                    NEVER_NOTIFY
                              specifies that the  sender is never
                              to  be notified  of the  success or
                              failure  of  the   mail  system  to
                              deliver   the  message   to  queued
                              recipients.

                    NOTIFY_ON_ERROR
                              specifies  that  the  sender  is to
                              receive a notification  only if the
                              mail  system could  not deliver the
                              message to a queued recipient.  The
                              notification    consists    of   an
                              explanation  of  the failure  and a
                              copy  of  the actual  message which
                              allows  the  sender  to  retry  the


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

                              delivery with a different recipient
                              address, etc.

                    ALWAYS_NOTIFY
                              specifies  that  the  sender  is to
                              receive  a   notification  of  both
                              success  and  failure  of  the mail
                              system to deliver  the message to a
                              queue   recipient.    The   failure
                              notification is as described above.
                              The  notification of  a successfull
                              delivery is sent  as an interactive
                              message  indicating  which  message
                              was   delivered    and   to   which
                              recipient(s).

          flags.abort         (Input)
                    if "1"b, specifies that the message is not to
                    be  delivered  to  any of  the  recipients if
                    fatal  errors  are detected  for one  or more
                    recipients;  if  "0"b,   specifies  that  the
                    message  is  to  be   delivered  to  as  many
                    recipients  as  possible  regardless  of  the
                    presence  of  any  fatal  errors.   Transient
                    errors which are  converted into fatal errors
                    by    the    caller's   selection    of   the
                    queueing_mode  option  are  still  considered
                    transient errors with respect to this option.

          flags.send_if_empty (Input)
                    if "1"b, specifies that  the message is to be
                    delivered even if the  message body is empty;
                    if "0"b, specifies that  the message is to be
                    delivered  only  if the  message body  is not
                    empty.

          flags.recipient_notification
                              (Input)
                    if    "1"b    and    the    ORDINARY_DELIVERY
                    delivery_mode  option is  selected, specifies
                    that  any  recipient who  is logged  into the
                    system when the message arrives is to receive
                    a  notification  of  the  message  arrival at
                    their    terminal;    otherwise,    no   such
                    notification message is displayed.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

          flags.acknowledge   (Input)
                    if  "1"b,  specifies that  the sender  of the
                    message  is  to   receive  an  acknowledgment
                    message  from each  recipient the  first time
                    that  the  recipient  reads  the  message; if
                    "0"b, specifies that  no such acknowledgments
                    are to be sent.

          flags.queue_mailing_lists
                              (Input)
                    if  "1"b,  specifies that  the message  is to
                    always be queued for any recipient which is a
                    mailing list regardless of the setting of the
                    queueing_mode option; if "0"b, specifies that
                    mailing  list  recipients are  to  be treated
                    according to the setting of the queueing_mode
                    option.

          flags.mbz           (Input)
                    is reserved for future  expansion and must be
                    ""b.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    recipients_info or delivery_options structure
                    that is not supported by the mail system.

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$not_new_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a new message.

          mlsys_et_$empty_message
                    The   message   body   is   empty   and   the
                    send_if_empty option was not requested by the
                    caller.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

          mlsys_et_$unknown_delivery_mode
                    The delivery mode requested  by the caller is
                    not one of the supported values listed above.

          mlsys_et_$unknown_queueing_mode
                    The queueing mode requested  by the caller is
                    not one of the supported values listed above.

          mlsys_et_$unknown_queued_notification_mode
                    The  notification  mode requested  for queued
                    mail  is  not  one  of  the  supported values
                    listed above.

          mlsys_et_$message_not_sent
                    The  message was  not delivered  to or queued
                    for  any  of  the  recipients  because  fatal
                    errors  were  detected before  attempting any
                    deliveries and the caller specified the abort
                    option.

          mlsys_et_$message_partially_sent
                    The  message was  delivered to  or queued for
                    some of the recipients even though it was not
                    possible   to   deliver/queue   it   for  all
                    non-duplicated recipients  because the caller
                    did not request the abort option or transient
                    errors  were  detected during  delivery which
                    were  converted   to  fatal  errors   at  the
                    caller's request.

COMPLETION OF THE MESSAGE CONTENT

     This entrypoint supplies default  values for those fields in
the  message  which   were  not  set  by  the   caller  prior  to
transmitting the message as follows:

     If  the caller  does not set  the From field  in the message
header, this entrypoint will set the From field to the address of
the user's  entry in the  system's mail table as  returned by the
mlsys_info_$user_mail_table_address entrypoint.

     If the caller  does not set the Reply-To  field but does set
the  From field  to one  or more addresses  all of  which can not
receive  mail,  this  entrypoint  will set  the  Reply-To  to the
address of the user's entry in the system mail table.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

     If  the caller  does not  set the  Subject, To,  cc, bcc, or
In-Reply-To fields, this entrypoint will leave them empty.

TRANSIENT VERSUS FATAL ERRORS

     There are two classes of errors which may be detected by the
mail  system when  attempting to deliver  mail to  a recipient --
fatal and transient errors.

     A fatal error is an error which will prevent the mail system
from  delivering  mail to  that  recipient without  some  form of
intervention  by  either  the  sender   of  the  message  or  the
recipient.  Although  the mail system could  queue the message in
this  case,  it is  likely  that the  message will  eventually be
returned as undeliverable and, therefore, the mail system rejects
the  attempt  immediately.   Examples  of  fatal  errors  include
non-existant  mailboxes,  forum meetings,  mail table  entries or
mailing  lists, incorrect  access on  these objects,  and foreign
addresses for which a route can not be computed.

     A transient  error is an  error which will  prevent the mail
system from delivering mail to that recipient but which is likely
to correct itself within a short  period of time.  As such errors
are likely  to be self-correcting,  the mail system  provides the
caller with the option of queueing  the message when it detects a
transient error  or converting the  transient error into  a fatal
error  and  rejecting  the   message  immediately.   Examples  of
transient errors  include record quota  overflows when delivering
to  a mailbox  or forum  meeting, some  foreign system  along the
route   selected   for   a  foreing   system   being  temporarily
unavailable, or the user lacking sufficient access to establish a
network  connection.  The  last error is  considered transient as
the mailer daemon which will attempt to deliver the message after
it is queued is guarenteed to have sufficient access.

THE RECIPIENTS_RESULT_LIST STRUCTURE

     As   mentioned   above,   the   mail   system   allocates  a
recipients_result_list  data  structure  for  each  address  list
supplied   by   the   caller.   This   structure   describes  the
success/failure  of the  mail system  to deliver  the message for
each address in the corresponding address list.

     The  recipients_result_list  structure  is  defined  in  the
include file mlsys_deliver_info.incl.pl1 as follows:


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

     dcl 1 recipients_result_list
                         aligned based
                         (recipients_result_list_ptr),
           2 n_addresses fixed binary,
           2 pad,
           2 results     (recipients_result_list_n_addresses
                         refer
                         (recipients_result_list.n_addresses)),
             3 code      fixed binary (35),
             3 expanded_list_info,

               4 first_entry_idx
                         fixed binary (18) unaligned unsigned,
               4 n_entries
                         fixed binary (18) unaligned unsigned,
             3 duplicate_info,

               4 list_idx
                         fixed binary (18) unaligned unsigned,
               4 address_idx
                         fixed binary (18) unaligned unsigned,
             3 reason_queued
                         character (128) varying;

where:

n_addresses
          is  the  number of  addresses  in the  caller's address
          list.  There  is one entry  in this structure  for each
          address in the list.

results   describes  the  results  of attempting  to  deliver the
          message  to the  corresponding address  in the caller's
          address list.

  code      is  a standard  system status code  which defines the
            success or failure of the  attempt to deliver mail to
            this  address.   This  code  will  have  one  of  the
            following values:

            mlsys_et_$message_delivered
                      The  message was  successfully delivered to
                      this address.

            mlsys_et_$message_queued
                      The message  was queued for  later delivery
                      to this address.  If the message was queued


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

                      as  the  result of  a transient  error, the
                      reason_queued  field below  will contain an
                      explanation of  why the message  was queued
                      for this address.

            mlsys_et_$message_queued_and_delivered
                      This  address  is a  mailing list  or named
                      group address and the message was delivered
                      to some of the members  of the list but was
                      queued  for  later  delivery  to  the other
                      members.  If the message  was queued as the
                      result of transient errors, the reasons for
                      queuing will be included for the individual
                      members                in               the
                      expanded_recipients_result_list   structure
                      described below.

            mlsys_et_$duplicate_address
                      This address identifies  the same recipient
                      as a prior address  in this address list or
                      in a prior address list.  In this case, the
                      duplicate_info  fields  below  identify the
                      first  address of  which this  address is a
                      duplicate.

            mlsys_et_$no_mailbox
                                (fatal)
                      The  mailbox  specified   by  this  address
                      either  by  pathname  or  User_id  does not
                      exist.

            mlsys_et_$no_a_permission
                                (fatal)
                      The user does not have a extended access to
                      the mailbox specified by this address.

            mlsys_et_$mailbox_full
                                (transient)
                      The  mailbox specified  by this  address is
                      temporarily  full  and  can  not  accept  a
                      message of the size supplied by the caller.

            mlsys_et_$rqover    (transient)
                      The  mail  system  was  unable  to  add the
                      message  to  the mailbox  or  forum meeting
                      specified  by  this  address  because  of a
                      record overflow condition.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

            forum_et_$no_forum  (fatal)
                      The forum meeting specified by this address
                      by pathname does not exist.

            forum_et_$not_participant
                                (fatal)
                      The user is not  an eligible participant of
                      the   forum   meeting  specified   by  this
                      address.

            forum_et_$read_only_participant
                      The   user   is   not   allowed   to  enter
                      transactions   into   the   forum   meeting
                      specified by  this address although  he may
                      read transactions in the meeting.

            network_et_$unknown_system
                                (fatal)
                      Either the foreign system name specified by
                      this  address  or  the  first  relay system
                      specified  by the  explicit route  for this
                      address is not a  recognized system name in
                      the  local   system's  network  information
                      table (NIT).

            mlsys_et_$no_mail_service
                                (fatal)
                      The mail system has determined that foreign
                      system specified  by this address  does not
                      support incoming electronic mail.

            mlsys_et_$no_address_route
                                (fatal)
                      The  mail  system was  unable to  compute a
                      route to be used  to deliver the message to
                      the   foreign  system   specified  by  this
                      address.

            mlsys_et_$route_out_of_service
                                (transient)
                      The  mail  system  could  not  deliver  the
                      message to foreign system specified by this
                      address  as  the route  used to  reach that
                      system is  temporarily out of  service (eg:
                      a host system in the route is down).


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

            mlsys_et_$no_mail_table_entry
                                (fatal)
                      There  is  no  entry in  the  system's mail
                      table corresponding to the name supplied by
                      this address.

            mlsys_et_$no_mailing_list
                                (fatal)
                      The mailing list  specified by this address
                      by pathname does not exist.

            error_table_$no_r_permission
                                (fatal)
                      The user  does not have  read permission on
                      the mailing list specified by this address.

            mlsys_et_$errors_in_list_address
                      Fatal or transient errors were detected for
                      some  of  the   addresses  listed  in  this
                      mailing list  or named group  address.  The
                      results for the  individual members of this
                      list  which did  not succeed  are listed by
                      the      mail       system      in      the
                      expanded_recipients_result_list   allocated
                      by this entrypoint.

            mlsys_et_$invalid_address
                                (fatal)
                      This  address  is  an  invalid  address  as
                      described in Section 1 of this document.

  expanded_list_info
            is  used if  fatal or transient  errors were detected
            for some of the addresses  in a mailing list or named
            group  address  to  identify  which  entries  in  the
            expanded_recipients_result_list   structure   defined
            below  refer to  the addresses from  this list.  This
            information  is also  used if the  mail system queued
            the message  for some of addresses  in a mailing list
            or named group address because of transient errors.

    first_entry_idx
              is   the  index   in  the  entries   array  of  the
              expanded_recipients_result_list  structure  of  the
              first entry  describing an address  in this mailing
              list or named group address.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

    n_entries is the  number of consecutive entries  in the above
              array  which describe  addresses from  this mailing
              list or named group address.

  duplicate_info
            if     the     value    of     code,     above,    is
            mlsys_et_$duplicate_address,  this  field  identifies
            the  first  address  for  which  this  address  is  a
            duplicate.

    list_idx  is   the   index  in   the   lists  array   of  the
              recipients_info  structure  described above  of the
              address list containing the  address for which this
              address is a duplicate.

    address_idx
              is  the  index in  the  address list  identified by
              list_idx  above  of  the  address  for  which  this
              address is a duplicate.

  reason_queued
            is the  reason why the  message was queued  for later
            delivery  to this  address if the  mail system queued
            the message due to a transient error.  This reason is
            formatted in a manner suitable  for use as the object
            of  the  preposition because  as  seen in  the Notes,
            below.

THE EXPANDED_RECIPIENTS_RESULT_LIST STRUCTURE

     As mentioned  in the discussion  of the recipients_list_info
structure above,  the mail system  will often detect  errors when
trying  to  deliver  a message  to  the individual  members  of a
mailing list or named group  address.  When this occurs, the mail
system  creates  an expanded_recipients_result_list  structure in
which it places a description of  the errors detected for each of
these mailing list or named group members.

     The expanded_recipients_result_list structure  is defined in
the include file mlsys_deliver_info.incl.pl1 as follows:

     dcl 1 expanded_recipients_result_list
                         aligned based
                         (expanded_recipients_result_list_ptr),
           2 n_entries   fixed binary,
           2 pad         bit (36),


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

           2 entries     (expanded_recipients_result_list_n_entries
                         refer
                         (expanded_recipients_result_list.n_entries)),
             3 address_ptr
                         pointer,
             3 code      fixed binary (35),
             3 parent_address,

               4 list_idx
                         fixed binary (18) unaligned unsigned,
               4 address_idx
                         fixed binary (18) unaligned unsigned,
             3 reason_queued
                         character (128) varying;

where:

n_entries is the number of entries in this data structure.

entries   describes  the  results  of attempting  to  deliver the
          message  to one  of the  members of  a mailing  list or
          named group address in the caller's list of recipients.

  address_ptr
            is a pointer to the  address from the mailing list or
            named group address described by this entry.

  code      is a standard system  status code which describes the
            fatal or  transient error detected  for this address.
            It may have any of  the values described above in the
            description  of the  recipients_result_list structure
            except         mlsys_et_$message_delivered        and
            mlsys_et_$message_delivered_and_queued.

  parent_address
            identifies the mailing list or named group address in
            the caller's list of recipients of which this address
            is a member.

    list_idx  is   the   index  in   the   lists  array   of  the
              recipients_info  structure  described above  of the
              address list  containing the mailing  list or named
              group address.

    address_idx
              is  the  index in  the  address list  identified by


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

              list_idx above  of the mailing list  or named group
              address.

  reason_queued
            is the  reason why the  message was queued  for later
            delivery  to this  address if the  mail system queued
            the message due to a transient error.  This reason is
            formatted in a manner suitable  for use as the object
            of  the  preposition because  as  seen in  the Notes,
            below.

NOTES

     The entrypoint mlsys_utils_$print_delivery_results described
elsewhere in this document may be  used to display the results of
a call to this entrypoint or mail_system_$redistribute_message in
a compact,  easy-to-read format.  An  example of the  output from
this subroutine is

     Mail delivered to Palter.Multics, your logbox, and GMP at MIT-MC.
     Mail not delivered to all addresses in the mailing list >udd>m>gmp>mail_project:
         You are not a participant of the forum >udd>m>gmp>meetings>Mail_System.
     Mail queued for MRC at SU-SCORE and Header-People at MIT-MC.
     Mail queued for Sibert.SiteSA because of record quota overflow.

             ________________________________________

Entry:  mail_system_$expand_list_address

     This entrypoint returns the address list associated with the
given  mail system  address.  Only  mailing list  and named group
addresses have  an associated address list.   See the description
of  address  types  in  Section 1   of  this  document  for  more
information.

USAGE

     dcl  mail_system_$expand_list_address entry (pointer,
               character (8), pointer, fixed binary (35));

     call mail_system_$expand_list_address (address_ptr,
               address_list_version, address_list_ptr, code);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

ARGUMENTS

address_ptr         (Input)
          is a pointer to the address which is to be examined.

address_list_ptr    (Input)
          is the version of  address_list structure to be created
          by  this entrypoint.   The only  supported address_list
          version at this time is given by the value of the named
          constant  ADDRESS_LIST_VERSION_2  in  the  include file
          mlsys_address_list.incl.pl1.

address_list_ptr    (Output)
          is a  pointer to the  address list associated  with the
          given address.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address
                    The   storage  identified   by  the  supplied
                    address_ptr is not an address.

          mlsys_et_$no_address_list
                    The supplied address is not a mailing list or
                    named  group address  and, therefore,  has no
                    associated address list.

          error_table_$unimplemented_version
                    The  caller  requested   the  creation  of  a
                    version of the address_list structure that is
                    not supported by the mail system.

NOTES

     For mailing  list addresses, this entrypoint  will parse the
printed  representations  of  the  addresses  in  the  segment or
archive component  into an address  list.  Any pieces  of text in
the  mailing  list whose  syntax  is not  recognized by  the mail
system are converted into invalid addresses.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$expunge_messages

     Given  a  mailbox structure,  this entrypoint  deletes those
messages    which   were    identified   by    prior   calls   to
mail_system_$mark_message_for_deletion.  A  new mailbox structure
containing  the   remaining  messages  from   the  input  mailbox
structure is created, replacing the supplied mailbox structure.

USAGE

     dcl  mail_system_$expunge_messages entry (pointer,
               fixed binary (35));

     call mail_system_$expunge_messages (mailbox_ptr, code);

ARGUMENTS

mailbox_ptr         (Input/Output)
          is  a pointer  to the mailbox  structure describing the
          mailbox  from  which  the  marked  messages  are  to be
          deleted.   This  pointer  will  be  set  to  locate the
          revised mailbox structure and the old structure will be
          destroyed.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_mailbox
                    The   storage  identified   by  the  supplied
                    mailbox_ptr is not a mailbox structure.

          mlsys_et_$some_messages_not_deleted
                    The mail system was  unable to delete some of
                    the messages which  were marked for deletion.
                    The exact cause of  each failure was reported
                    by a call to sub_err_ as described below.

          mlsys_et_$all_messages_deleted
                    The mail  system deleted all  messages listed
                    in  the  input  mailbox  structure.   The new
                    mailbox structure returned by the mail system
                    contains no messages.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

NOTES

     Each  failure to  delete a  message by  this entrypoint will
result in a call to  sub_err_.  As this entrypoint is implemented
in a lower  ring, the sub_error_ condition signalled  by the call
to sub_err_ can not be  restarted.  Therefore, after handling the
condition in  whatever fashion is deemed  appropriate, the caller
of this entrypoint must either call this entrypoint again or call
mail_system_$abort_delete_operation.    If  this   entrypoint  is
called again, the mail system  will continue to delete the marked
messages  and  then  return  the updated  mailbox  structure.  If
mail_system_$abort_delete_operation  is  called, the  mail system
will not perform  any more deletions; instead, it  will return an
updated  mailbox  structure which  reflects those  deletions that
were successfull before the reported error occured.

     The program  name specified in  the sub_error_info structure
supplied  with   the  sub_error_  condition   signalled  by  this
entrypoint is mail_system_.   The  data structure supplied by the
mail  system  with  the  sub_error_ condition  signalled  by this
entrypoint     is     defined     in     the     include     file
mlsys_delete_error_info.incl.pl1 as follows:

     dcl 1 delete_error_info
                         aligned based (delete_error_info_ptr),
           2 version     character (8) unaligned,
           2 message_number
                         fixed binary,
           2 code        fixed binary (35),
           2 additional_info
                         character (256) varying;

where:

version   is the current version  of this structure.  The version
          of the  structure described here is  given by the value
          of the named constant DELETE_ERROR_INFO_VERSION_1 which
          is also declared in the above include file.

message_number
          is  the  index in  the input  mailbox structure  of the
          message which could not be deleted.

code      is  a standard  system status  code indicating  why the
          message could not be deleted.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

additional_info
          is a character string containing additional information
          which may be included in  error messages printed by the
          caller of this entrypoint.

EXAMPLES

     An example of the use of this entrypoint follows:

on condition (sub_error_)
     begin;                   /* in case it can't delete some ... */

dcl  1 ci aligned like condition_info;

          ci.version = condition_info_version_1;
          call find_condition_info_ (null (), addr (ci), code);

          sub_error_info_ptr = ci.info_ptr;
          if sub_error_info.name ^= "mail_system_" then do;
                              /* only handle sub_error_ condition if it
                                 is from the mail system proper */
               call continue_to_signal_ ((0));
               go to CONTINUE_FROM_HANDLER;
          end;

          delete_error_info_ptr = sub_error_info.info_ptr;

          call com_err_ (delete_error_info.code, "sample_program",
                    "Unable to delete message #^d.  ^a",
                    delete_error_info.message_number,
                    delete_error_info.additional_info);

          go to EXPUNGE_MESSAGES;       /* try to finish the operation */

CONTINUE_FROM_HANDLER:        /* continue to signal if we didn't handle
                                 this sub_error_ condition */
     end;

EXPUNGE_MESSAGES:
call mail_system_$expunge_messages (mailbox_ptr, code);
                                        /* all interesting errors are
                                           reported in the above on-unit */
revert condition (sub_error_);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$free_address

     This entrypoint frees all storage occupied by an address.

USAGE

     dcl  mail_system_$free_address entry (pointer,
               fixed binary (35));

     call mail_system_$free_address (address_ptr, code);

ARGUMENTS

address_ptr         (Input/Output)
          is  a pointer  to the  address whose  storage is  to be
          released.   This  pointer will  be set  to null  if the
          address is successfully freed.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address
                    The   storage  identified   by  the  supplied
                    address_ptr is not an address.

             ________________________________________

Entry:  mail_system_$free_address_list

     This  entrypoint frees  all storage  occupied by  an address
list and all addresses that it references.

USAGE

     dcl  mail_system_$free_address_list entry (pointer,
               fixed binary (35));

     call mail_system_$free_address_list (address_list_ptr,
               code);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

ARGUMENTS

address_list_ptr    (Input/Output)
          is a pointer to the address list whose storage is to be
          released.   This  pointer will  be set  to null  if the
          address list is successfully freed.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address_list
                    The   storage  identified   by  the  supplied
                    address_list_ptr is not an address list.

             ________________________________________

Entry:  mail_system_$free_message

     This  entrypoint  frees all  the storage  occupied by  a new
message and its subsidiary data structures.

USAGE

     dcl  mail_system_$free_message entry (pointer,
               fixed binar (35));

     call mail_system_$free_message (message_ptr, code);

ARGUMENTS

message_ptr         (Input/Output)
          is a pointer to the new  message whose storage is to be
          released.   This  pointer will  be set  to null  if the
          message is successfully freed.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$not_new_message
                    The   storage  identified   by  the  supplied
                    message_ptr  is an  in-mailbox message rather
                    than a new message.

             ________________________________________

Entry:  mail_system_$get_address_comment

     This  entrypoint  returns  the   address  comment,  if  any,
associated  with   the  given  mail  system   address.   See  the
description of address comments in Section 1 of this document for
more information.

USAGE

     dcl  mail_system_$get_address_comment entry (pointer,
               character (*) varying, fixed binary (35));

     call mail_system_$get_address_comment (address_ptr,
               address_comment, code);

ARGUMENTS

address_ptr         (Input)
          is a pointer to the address which is to be examined.

address_comment     (Output)
          is set to  the address comment of the  given address or
          to  a  null  string  if the  address  does  not  have a
          comment.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address
                    The   storage  identified   by  the  supplied
                    address_ptr is not an address.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

          error_table_$smallarg
                    The address_comment parameter provided by the
                    caller is too small to  hold the value of the
                    address comment.

             ________________________________________

Entry:  mail_system_$get_address_name

     This entrypoint returns the address name, if any, associated
with  the  given mail  system  address.  See  the  description of
address names in Section 1 of this document for more information.

USAGE

     dcl  mail_system_$get_address_name entry (pointer,
               character (*) varying, fixed binary (35));

     call mail_system_$get_address_name (address_ptr,
               address_name, code);

ARGUMENTS

address_ptr         (Input)
          is a pointer to the address which is to be examined.

address_name        (Output)
          is set to the address name of the given address or to a
          null string if the address does not have a name.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address
                    The   storage  identified   by  the  supplied
                    address_ptr is not an address.

          error_table_$smallarg
                    The  address_name  parameter provided  by the
                    caller is too small to  hold the value of the
                    address name.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$get_address_pathname

     This  entrypoint  returns the  pathname associated  with the
given  mail system  address.  Addresses  with pathnames  are user
mailbox addresses,  logbox addresses, savebox  addresses, mailbox
addresses, forum addresses, and  mailing list addresses.  See the
description of  address types in  Section 1 of this  document for
more information.

USAGE

     dcl  mail_system_$get_address_pathname entry (pointer,
               character (*), fixed binary (35));

     call mail_system_$get_address_pathname (address_ptr,
               address_pathname, code);

ARGUMENTS

address_ptr         (Input)
          is a pointer to the address which is to be examined.

address_pathname    (Output)
          is  set to  the pathname of  the given address  or to a
          null  string if  the address  does not  have a pathname
          (eg:   foreign  addresses,  named groups,  etc).   As a
          mailing list address may  be an archive component, this
          parameter  should  be  made  large  enough  to  hold an
          archive  component  pathname  of  maximum  length  (194
          characters).

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address
                    The   storage  identified   by  the  supplied
                    address_ptr is not an address.

          mlsys_et_$no_address_pathname
                    The  specified  address   does  not  have  an
                    associated pathname.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$get_address_route

     This  entrypoint returns  the address  route associated with
the given  mail system address.  Only  foreign addresses may have
an  address  route.  See  the  description of  address  types and
address   routes  in   Section 1  of   this  document   for  more
information.

USAGE

     dcl  mail_system_$get_address_route entry (pointer, pointer,
               fixed binary (35));

     call mail_system_$get_address_route (address_ptr,
               address_route_ptr, code);

ARGUMENTS

address_ptr         (Input)
          is a pointer to the address which is to be examined.

address_route_ptr   (Output)
          is set to locate  an address_route structure as defined
          in Section 1 of this document or  is set to null if the
          address does not have an associated route.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address
                    The   storage  identified   by  the  supplied
                    address_ptr is not an address.

          mlsys_et_$no_address_route
                    The  specified  address   does  not  have  an
                    associated route.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$get_address_string

     This entrypoint  returns a character  string associated with
the given  mail system address.  This  address string has various
interpretations dependent on the type of address of which it is a
part.  Addresses with address strings are user mailbox addresses,
logbox  addresses,  savebox  addresses,  foreign  addresses, mail
table addresses,  and invalid addresses.  See  the description of
address types in Section 1 of this document for more information.

USAGE

     dcl  mail_system_$get_address_string entry (pointer,
               character (*) varying, fixed binar (35));

     call mail_system_$get_address_string (address_ptr,
               address_string, code);

ARGUMENTS

address_ptr         (Input)
          is a pointer to the address which is to be examined.

address_string      (Output)
          is set to the address string of the given address or to
          a null string  if the address does not  have an address
          string.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address
                    The   storage  identified   by  the  supplied
                    address_ptr is not an address.

          mlsys_et_$no_address_string
                    The  specified  address   does  not  have  an
                    associated address string.

          error_table_$smallarg
                    The address_string parameter  provided by the
                    caller is too small to  hold the value of the
                    address string.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$get_address_system

     This  entrypoint  returns  the  name of  the  foreign system
associated  with  the given  mail  system address.   Only foreign
address have  an associated system name.   See the description of
address types in Section 1 of this document for more information.

USAGE

     dcl  mail_system_$get_address_system entry (pointer,
               character (256) varying, fixed binary (35));

     call mail_system_$get_address_system (address_ptr,
               address_system, code);

ARGUMENTS

address_ptr         (Input)
          is a pointer to the address which is to be examined.

address_system      (Output)
          is  set to  the name  of the  foreign system associated
          with the given address.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address
                    The   storage  identified   by  the  supplied
                    address_ptr is not an address.

          mlsys_et_$not_foreign_address
                    The supplied address is not a foreign address
                    and, therefore,  does not have  an associated
                    foreign system name.

NOTES

     The  system  name  returned  by  this  entrypoint  does  not
necessarily  appear  in  the local  system's  network information
table (NIT).   In  this case,  the address  will also  contain an


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

address route  which defines the  path used to  reach the foreign
system.

             ________________________________________

Entry:  mail_system_$get_address_type

     This entrypoint  returns the address type  of the given mail
system address.

USAGE

     dcl  mail_system_$get_address_type entry (pointer,
               fixed binary, fixed binary (35));

     call mail_system_$get_address_type (address_ptr,
               address_type, code);

ARGUMENTS

address_ptr         (Input)
          is a pointer to the address whose address type is to be
          returned.

address_type        (Output)
          is set to  the address type of the  given address.  The
          possible returned values of this parameter are given in
          the  include file  mlsys_address_types.incl.pl1 and are
          defined  in   the  description  of   address  types  in
          Section 1 of this document.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address
                    The   storage  identified   by  the  supplied
                    address_ptr is not an address.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$get_mail_table_address

     This entrypoint  returns the actual address  in the system's
mail table corresponding to the  given mail system address.  Only
mail table addresses  have such an entry in  the mail table.  See
the description  of address types  in Section 1 of  this document
for more information.

USAGE

     dcl  mail_system_$get_mail_table_address entry (pointer,
               pointer, fixed binary (35));

     call mail_system_$get_mail_table_address (address_ptr,
               mail_table_address_ptr, code);

ARGUMENTS

address_ptr         (Input)
          is a pointer to an the address which is to be examined.

mail_table_address_ptr
                    (Output)
          is set to be a  pointer to the actual address extracted
          from the  mail table which corresponds  to the supplied
          address.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address
                    The   storage  identified   by  the  supplied
                    address_ptr is not an address.

          mlsys_et_$not_mail_table_address
                    The  supplied  address  is not  a  mail table
                    address  and,  therefore,  does  not  have  a
                    corresponding entry in the mail table.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$get_message_counts

     This entrypoint returns the number  of messages in a mailbox
and,  optionally,  the  number  of  ordinary  versus  interactive
messages in the mailbox.

USAGE

     dcl  mail_system_$get_message_counts entry (character (*),
               character (*), bit (1) aligned, fixed binary,
               fixed binary, fixed binary, fixed binary (35));

     call mail_system_$get_message_counts (mailbox_dirname,
               mailbox_ename, include_by_type, n_messages,
               n_ordinary_messages, n_interactive_messages,
               code);

ARGUMENTS

mailbox_dirname     (Input)
          is  the absolute  pathname of  the directory containing
          the mailbox.

mailbox_ename       (Input)
          is the  entryname of the  mailbox; the suffix  mbx need
          not be supplied by the caller.

include_by_type     (Input)
          if "1"b, individual counts of ordianary and interactive
          messages  will  be returned  in  addition to  the total
          message count; otherwise, only  the total message count
          is returned.   The user must have  r extended access to
          the  mailbox  to  determine  the  type-specific message
          counts.

n_messages          (Output)
          is set to the total number of messages in the mailbox.

n_ordinary_messages (Output)
          is   set  to   the  number  of   ordinary  messages  if
          include_by_type is "1"b.

n_interactive_messages
                    (Output)


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

          is  set  to  the  number  of  interactive  messages  if
          include_by_type is "1"b.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$no_s_permission
                    The user  does not have s  extended access to
                    the mailbox  which is necessary  to determine
                    the total number of  messages in the mailbox.
                    The   type-specific   messages   counts,   if
                    requested, are also not returned.

          mlsys_et_$no_r_permission
                    The user  does not have r  extended access to
                    the mailbox  which is necessary  to determine
                    the type-specific message  counts.  The total
                    number of messages in the mailbox is returned
                    regardless of this error.

             ________________________________________

Entry:  mail_system_$get_user_field_id

     This  entrypoint  returns  the   unique  ID  for  the  given
user-defined   field   name.    See   the   description   of  the
message_user_field  structure in  Section 1 of  this document for
more information.

USAGE

     dcl  mail_system_$get_user_field_id entry
               (character (*) varying, fixed binary,
               character (*) varying, fixed binary (35));

     call mail_system_$get_user_field_id (field_name, field_id,
               canonical_field_name, code);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

ARGUMENTS

field_name          (Input)
          is the user-defined field name.

field_id            (Output)
          is set to the field ID corresponding to the given field
          name.

canonical_field_name
                    (Output)
          is set to the  canonical representation of the supplied
          field name.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$reserved_field_name
                    The supplied  field name is  reserved for use
                    by the mail  system and can not be  used as a
                    user-defined field name.

          error_table_$smallarg
                    The  canonical_field_name  parameter supplied
                    by  the  caller  is  too  small  to  hold the
                    canonicalized  field name.   The field  ID is
                    returned regardless of this error.

             ________________________________________

Entry:  mail_system_$get_user_field_name

     This  entrypoint   returns  the  canonicalized   field  name
corresponding  to  the  given  user-defined  field  ID.   See the
description of  the message_user_field structure  in Section 1 of
this document for more information.

USAGE

     dcl  mail_system_$get_user_field_name entry (fixed binary,
               character (*) varying, fixed binary (35));


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

     call mail_system_$get_user_field_name (field_id,
               canonical_field_name, code);

ARGUMENTS

field_id            (Input)
          is the user-defined field ID.

canonical_field_name
                    (Output)
          is  set  to  the  canonicalized  representation  of the
          user-defined  field  name  corresponding  to  the given
          field ID.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$unknown_field_id
                    The  supplied field  ID is  not known  to the
                    mail  system.  (Ie:   the value  supplied was
                    not   obtained   by   an   earlier   call  to
                    mail_system_$get_user_field_id).

          error_table_$smallarg
                    The  canonical_field_name  parameter supplied
                    by  the  caller  is  too  small  to  hold the
                    canonicalized field name.

             ________________________________________

Entry:  mail_system_$log_message

     This  entrypoint copies  a message  into the  user's logbox.
The  logbox  may optionally  be  created if  it does  not already
exist.

USAGE

     dcl  mail_system_$log_message entry (pointer,
               bit (1) aligned, fixed binary (35));


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

     call mail_system_$log_message (message_ptr,
               create_if_not_found, code);

ARGUMENTS

message_ptr         (Input)
          is a pointer to the message to be logged.

create_if_not_found (Input)
          if  "1"b, the  logbox will  be created  if it  does not
          already exist; if "0"b, the  logbox must exist prior to
          the execution of this entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$no_logbox
                    The  user's  logbox  does not  exist  and the
                    value of create_if_not_found is "0"b.

          mlsys_et_$no_a_permission
                    The user  does not have a  extended access to
                    his logbox.

          mlsys_et_$logbox_created
                    The  user's   logbox  was  created   by  this
                    entrypoint   and   the   message   was   then
                    successfully copied into the logbox.

NOTES

     See  the   writeup  of  mlsys_utils_$create_logbox   for  an
alternative mechanism to create the  user's logbox if it does not
already exist.

     See   the  mail_system_$deliver_message   entrypoint  for  a
description of  the default values  given to those  fields in the
message  which were  not set by  the caller prior  to logging the
message if it is a new message.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$mark_message_for_deletion

     This entrypoint marks an  in-mailbox message for deletion by
a    subsequent    call    to    mail_system_$close_mailbox    or
mail_system_$expunge_messages.   The  requested  deletion  may be
cancelled by a call to mail_system_$unmark_message_for_deletion.

USAGE

     dcl  mail_system_$mark_message_for_deletion entry (pointer,
               fixed binary (35));

     call mail_system_$mark_message_for_deletion (message_ptr,
               code);

ARGUMENTS

message_ptr         (Input)
          is a pointer to the in-mailbox message to be marked for
          deletion.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$not_in_mailbox_message
                    The   storage  identified   by  the  supplied
                    message_ptr is  a new message  rather than an
                    in-mailbox message.

          mlsys_et_$cant_be_deleted
                    The user  does not have  sufficient access to
                    delete this message from the mailbox.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$merge_address_lists

     This entrypoint merges two address  lists together to form a
new  address list  and optionally  eliminates duplicate addresses
from the new list.

USAGE

     dcl  mail_system_$merge_address_lists entry (pointer,
               pointer, bit (1) aligned, pointer,
               fixed binary (35));

     call mail_system_$merge_address_lists (address_list_ptr_1,
               address_list_ptr_2, eliminate_duplicates,
               new_address_list_ptr, code);

ARGUMENTS

address_list_ptr_1  (Input)
address_list_ptr_2  (Input)
          are  pointers  to  the  address_list  structures  to be
          merged into a single list.

eliminate_duplicates
                    (Input)
          if "1"b,  duplicate addresses in the  two address lists
          will be replaced  by a single address in  the new list;
          if "0"b, all addresses from  the original lists will be
          included in the new list.

new_address_list_ptr
                    (Output)
          is  set to  locate the address_list  structure which is
          the merger of the two input lists.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address_list
                    The storage  identified by address_list_ptr_1
                    and/or  address_list_ptr_2 is  not an address
                    list.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

NOTES

If   new_address_list_ptr   is   the  same   pointer   as  either
address_list_ptr_1  or  address_list_ptr_2, the  old address_list
structure will be destroyed and replaced by the merger of the two
lists.

             ________________________________________

Entry:  mail_system_$open_mailbox

     This entrypoint  opens a mailbox  for perusal by  creating a
mailbox structure describing the  mailbox and optionally creating
message structures  for each message of  interest in the mailbox.
The  caller  may  specify  which  messages  in  the  mailbox  are
interesting by type (ordinary versus interactive) and sender (the
user versus other users).

USAGE

     dcl  mail_system_$open_mailbox entry (character (*),
               character (*), pointer, character (8), pointer,
               fixed binary (35));

     call mail_system_$open_mailbox (mailbox_dirname,
               mailbox_ename, open_options_ptr, mailbox_version,
               mailbox_ptr, code);

ARGUMENTS

mailbox_dirname     (Input)
          is  the absolute  pathname of  the directory containing
          the mailbox.

mailbox_ename       (Input)
          is the  entryname of the  mailbox; the suffix  mbx need
          not be supplied by the caller.

open_options_ptr    (Input)
          is  a  pointer  to   an  open_options  structure.   The
          open_options  structure  and, unless  stated otherwise,
          all named  constants mentioned here are  defined in the
          include file mlsys_open_options.incl.pl1.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

               dcl 1 open_options  aligned
                                   based (open_options_ptr),
                     2 version     character (8),
                     2 message_selection_mode
                                   fixed binary,
                     2 sender_selection_mode
                                   fixed binary,
                     2 message_reading_level
                                   fixed binary;

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    This version of the structure is given by the
                    value      of     the      named     constant
                    OPEN_OPTIONS_VERSION_2.

          message_section_mode
                              (Input)
                    specifies  the   types  of  messages   to  be
                    returned in the  mailbox structure subject to
                    the  setting of  sender_selection_mode below.
                    The possible values for  this field are given
                    by the following named constants:

                    ALL_MESSAGES
                              includes all types of messages.

                    ORDINARY_MESSAGE
                    INTERATIVE_MESSAGE
                              includes    only     ordinary    or
                              interactive messages, respectively.

          sender_selection_mode
                              (Input)
                    specifies the messages to  be returned in the
                    mailbox structure  subject to the  setting of
                    message_selection_mode  above  based  on  the
                    sender of  the message.  The  possible values
                    of  this  field  are given  by  the following
                    named constants:

                    ACCESSIBLE_MESSAGES
                              includes all messages  which can be
                              accessed by the  user.  If the user
                              has   r  extended   access  to  the


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

                              mailbox, all messages  of the types
                              requested by message_selection_mode
                              are  included;  otherwise,  if  the
                              user has  o extended access  to the
                              mailbox,   only  messages   of  the
                              requested  types  sent by  the user
                              are included.

                    ALL_MESSAGES
                              includes   all   messages   of  the
                              requested  types.   The  user  must
                              have  r  extended   access  to  the
                              mailbox.

                    OWN_MESSAGES
                              includes   only  messages   of  the
                              requested  types sent  by the user.
                              The  user  must   have  o  extended
                              access to the mailbox.

                    NOT_OWN_MESSAGES
                              includes   only  messages   of  the
                              requested  types  not  sent  by the
                              user.    The   user  must   have  r
                              extended access to the mailbox.

          message_reading_level
                              (Input)
                    specifies  whether all  or only  part of each
                    message is to be  read from the mailbox.  The
                    possible values  for this field  are given by
                    the following named constants:

                    READ_KEYS reads only the  unique key for each
                              message from the mailbox.  This key
                              must be used in subsequent calls to
                              mail_system_$read_message        to
                              retrieve  the  actual  message from
                              the mailbox.

                    READ_MESSAGES
                              reads  the  entire content  of each
                              message from the mailbox.

mailbox_version     (Input)
          is the  version of the mailbox  structure to be created
          by this entrypoint.  The only version supported at this


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

          time  is  given  by  the value  of  the  named constant
          MAILBOX_VERSION_2      in     the      include     file
          mlsys_mailbox.incl.pl1.

mailbox_ptr         (Output)
          is set to locate the  mailbox structure created by this
          entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    The  caller  requested   the  creation  of  a
                    version of the mailbox  structure that is not
                    supported by the mail system.

          error_table_$moderr
                    The user has neither  r nor o extended access
                    to   the    mailbox   and   the    value   of
                    sender_selection_mode        option        is
                    ACCESSIBLE_MESSAGES.

          mlsys_et_$no_r_permission
                    The user  does not have r  extended access to
                    the     mailbox    and     the    value    of
                    sender_selection_mode   option    is   either
                    ALL_MESSAGES or NOT_OWN_MESSAGES.

          mlsys_et_$no_o_permission
                    The user  does not have o  extended access to
                    the     mailbox    and     the    value    of
                    sender_selection_mode option is OWN_MESSAGES.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$read_message

     This entrypoint  reads the content of  the requested message
from a  mailbox by using  the unique key in  the supplied mailbox
structure  is to  locate the message.   A pointer  to the message
structure  which describes  the message  is then  placed into the
mailbox structure.

USAGE

     dcl  mail_system_$read_message entry (pointer, fixed binary,
               fixed binary (35));

     call mail_system_$read_message (mailbox_ptr, message_index,
               code);

ARGUMENTS

mailbox_ptr         (Input)
          is  a pointer  to the mailbox  structure describing the
          mailbox in which the message is to be found.

message_index       (Input)
          is  the index  into the  messages array  in the mailbox
          structure of  the message that  is to be  read from the
          mailbox.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_mailbox
                    The   storage  identified   by  the  supplied
                    mailbox_ptr is not a mailbox structure.

          error_table_$bad_index
                    The  specified  message_index is  either less
                    than  one  or  greater  than  the  number  of
                    messages in the supplied mailbox structure.

          mlsys_et_$message_already_read
                    The  content  of  the  specified  message was
                    previously obtained  from the mailbox  by the
                    initial call  to mail_system_$open_mailbox or


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

                    by     a     prior     call     to     either
                    mail_system_$read_message                  or
                    mail_system_$read_new_messages.

             ________________________________________

Entry:  mail_system_$read_new_messages

     Given  a  mailbox  structure,   this  entrypoint  reads  any
messages  from  the mailbox  which  have arrived  after  the last
message  in  the  mailbox  structure.  Only  those  newly arrived
messages  which satisfy  the message  and sender  selection modes
specified  in the  call to mail_system_$open_mailbox  are read by
this  entrypoint.  A  new mailbox structure  containing these new
messages  and  the messages  in  the input  mailbox  structure is
created, replacing the supplied mailbox structure.

USAGE

     dcl  mail_system_$read_new_messages entry (pointer,
               fixed binary, fixed binary, fixed binary,
               fixed binary (35));

     call mail_system_$read_new_messages (mailbox_ptr,
               n_new_messages, n_new_ordinary_messages,
               n_new_interactive_messages, code);

ARGUMENTS

mailbox_ptr         (Input/Output)
          is  a pointer  to the mailbox  structure describing the
          mailbox  to  be  examined for  newly  arrived messages.
          This pointer will be set  to locate the revised mailbox
          structure and the old structure will be destroyed.

n_new_messages      (Output)
          is the total number of newly arrived messages read from
          the mailbox.

n_new_ordinary_messages
                    (Output)
          is the  number of newly arrived  ordinary messages read
          from the mailbox.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

n_new_interactive_messages
                    (Output)
          is  the  number of  newly arrived  interactive messages
          read from the mailbox.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          0         The  newly  arrived messages  in  the mailbox
                    were  read; the  input mailbox  structure was
                    replaced by a revised structure.

          mlsys_et_$no_more_messages
                    There were  no newly arrived  messages in the
                    mailbox; the input  mailbox structure was not
                    replaced.

          mlsys_et_$not_mailbox
                    The   storage  identified   by  the  supplied
                    mailbox_ptr is not a mailbox structure.

             ________________________________________

Entry:  mail_system_$redistribute_message

     This entrypoint  redistributes an in-mailbox  message to the
supplied  list  of reipcients.   A  comment may  be added  to the
message  as  part of  the  redistribution; however,  the original
message is left unchanged.

USAGE

     dcl  mail_system_$redistribute_message entry (pointer,
               character (*), pointer, pointer,
               fixed binary (35));

     call mail_system_$redistribute_message (message_ptr,
               redistribution_comment, recipients_info_ptr,
               deliver_options_ptr, code);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

ARGUMENTS

message_ptr         (Input)
          is   a  pointer   to  the  in-mailbox   message  to  be
          retransmitted.

redistribution_comment
                    (Input)
          is the  optional comment to be  added to the in-mailbox
          messages  as  it is  redistributed.   If this  value is
          zero-length or consists  only of whitespace characters,
          no comment will be added to the message.

recipients_info_ptr (Input)
          is  a  pointer  to  a  recipients_info  structure which
          defines the  recipients of the message  and the results
          of   transmission   for   each   recipient.    See  the
          description    of    the   mail_system_$deliver_message
          entrypoint   for   a  detailed   explanation   of  this
          structure.

deliver_options_ptr (Input)
          is  a  pointer  to  a  deliver_options  structure which
          defines the  options which control the  deliver of this
          message.      See     the     description     of    the
          mail_system_$deliver_message entrypoint  for a detailed
          explanation of this structure.

code                (Output)
          is  a  standard  system   status  code.   The  possible
          returned values for this  entrypoint are given above in
          the  description  of  the  mail_system_$deliver_message
          entrypoint.

NOTES

     See  the  description  of  the  mail_system_$deliver_message
entrypoint  above  for  an  explanation of  the  various possible
result codes for individual recipients  and for an explanation of
transient versus fatal errors.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$replace_address

     This entrypoint replaces an  address in the supplied address
list.

USAGE

     dcl  mail_system_$replace_address entry (pointer,
               fixed binary, pointer, fixed binary (35));

     call mail_system_$replace_address (address_list_ptr,
               address_position, new_address_ptr, code);

ARGUMENTS

address_list_ptr    (Input)
          is  a  pointer  to  the address  list  which  is  to be
          modified.

address_position    (Input)
          is  the index  within the  address list  of the address
          that is to be replaced.

new_address_ptr     (Input)
          is a pointer to the  address which will replace the old
          address in the list.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address_list
                    The   storage  identified   by  the  supplied
                    address_list_ptr is not an address list.

          mlsys_et_$not_address
                    The   storage  identified   by  the  supplied
                    new_address_ptr is not an address.

          error_table_$bad_index
                    The  specified address_position  is less than
                    one or  greater than the  number of addresses
                    in the address list.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$replace_body

     This entrypoint replaces the entire body of a new message by
the single message body section supplied by the caller.

USAGE

     dcl  mail_system_$replace_body entry (pointer, pointer,
               fixed binary (35));

     call mail_system_$replace_body (message_ptr,
               message_body_section_parameter_ptr, code);

ARGUMENTS

message_ptr         (Input/Output)
          is  a  pointer  to  the  new  message  which  is  to be
          modified.  This  pointer will be updated  to locate the
          revised message structure and the old structure will be
          destroyed.

message_body_section_parameter_ptr
                    (Input)
          is   a  pointer   to  a  message_body_section_parameter
          structure.  This structure, which describes the section
          that will replace the  current message body, is defined
          in the include file mlsys_message.incl.pl1 as follows:

               dcl 1 message_body_section_parameter
                                   aligned based
                                   (message_body_section_parameter_ptr),
                     2 version     character (8) unaligned,
                     2 section     like message_body_section;

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    MESSAGE_BODY_SECTION_PARAMETER_VERSION_2.

          section             (Input)
                    is the section which will replace the current
                    message  body.   See the  description  of the


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

                    message_body_section  structure  in Section 1
                    of this  document for a  detailed explanation
                    of the contents of this structure.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$not_new_message
                    The   storage  identified   by  the  supplied
                    message_ptr  is an  in-mailbox message rather
                    than a new message.

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    message_body_section_parameter structure that
                    is not supported by the mail system.

          mlsys_et_$unknown_body_section_type
                    The type of message body section specified is
                    not recognized by the mail system.

             ________________________________________

Entry:  mail_system_$replace_body_section

     This  entrypoint  replaces  a  section of  the  body  in the
supplied new message.

USAGE

     dcl  mail_system_$replace_body_section entry (pointer,
               fixed binary, pointer, fixed binary (35));

     call mail_system_$replace_body_section (message_ptr,
               section_position,
               message_body_section_parameter_ptr, code);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

ARGUMENTS

message_ptr         (Input/Output)
          is  a  pointer  to  the  new  message  which  is  to be
          modified.

section_position    (Input)
          is  the index  within the  message body  of the section
          that is to be replaced.

message_body_section_parameter_ptr
                    (Input)
          is   a  pointer   to  a  message_body_section_parameter
          structure.  This structure, which describes the section
          that will  replace the old  section, is defined  in the
          include file mlsys_message.incl.pl1 as follows:

               dcl 1 message_body_section_parameter
                                   aligned based
                                   (message_body_section_parameter_ptr),
                     2 version     character (8) unaligned,
                     2 section     like message_body_section;

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    MESSAGE_BODY_SECTION_PARAMETER_VERSION_2.

          section             (Input)
                    is  the  section which  will replace  the old
                    section  in   the  message  body.    See  the
                    description   of   the   message_body_section
                    structure in Section 1 of this document for a
                    detailed explanation of  the contents of this
                    structure.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

          mlsys_et_$not_new_message
                    The   storage  identified   by  the  supplied
                    message_ptr  is an  in-mailbox message rather
                    than a new message.

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    message_body_section_parameter structure that
                    is not supported by the mail system.

          error_table_$bad_index
                    The  specified section_position  is less than
                    one or greater than the number of sections in
                    the message body.

          mlsys_et_$unknown_body_section_type
                    The type of message body section specified is
                    not recognized by the mail system.

             ________________________________________

Entry:  mail_system_$replace_reply_reference

     This entrypoint  replaces one of the  references in the list
of messages for which the specified new message is a reply.

USAGE

     dcl  mail_system_$replace_reply_reference entry (pointer,
               fixed binary, pointer, fixed binary (35));

     call mail_system_$replace_reply_reference (message_ptr,
               reply_reference_position,
               new_referenced_message_ptr, code);

ARGUMENTS

message_ptr         (Input)
          is  a  pointer  to  the  new  message  which  is  to be
          modified.

reply_reference_position
                    (Input)


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

          is the  index within the  reply references list  of the
          reference that is to be replaced.

new_referenced_message_ptr
                    (Input)
          is  a  pointer to  the in-mailbox  message for  which a
          reply  reference  will be  created  to replace  the old
          reply reference in the list.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The storage identified  by either message_ptr
                    or   new_referenced_message_ptr   is   not  a
                    message.

          mlsys_et_$not_in_mailbox_message
                    The   storage  identitied   by  the  supplied
                    new_referenced_message_ptr  is a  new message
                    rather than an in-mailbox message.

          mlsys_et_$not_new_message
                    The   storage  identified   by  the  supplied
                    message_ptr  is an  in-mailbox message rather
                    than a new message.

          error_table_$bad_index
                    The  specified   reply_reference_position  is
                    less than  one or greater than  the number of
                    reply references in the message.

          mlsys_et_$duplicate_reply_reference
                    The  new  reply  reference  supplied  by  the
                    caller  is  already  present in  the  list of
                    references in the message header.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$replace_subject

     This entrypoint replaces the subject of a new message.

USAGE

     dcl  mail_system_$replace_subject entry (pointer,
               character (*), fixed binary (35));

     call mail_system_$replace_subject (message_ptr, new_subject,
               code);

ARGUMENTS

message_ptr         (Input)
          is  a  pointer  to  the  new  message  which  is  to be
          modified.

new_subject         (Input)
          is the value of the  new subject for the message.  This
          parameter  may  be  a  null string  in  which  case the
          message will not have a subject.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$not_new_message
                    The   storage  identified   by  the  supplied
                    message_ptr  is an  in-mailbox message rather
                    than a new message.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$replace_user_field

     This  entrypoint  replaces  a   user-defined  field  in  the
supplied new message.

USAGE

     dcl  mail_system_$replace_user_field entry (pointer,
               fixed binary, pointer, bit (1) aligned,
               fixed binary (35));

     call mail_system_$replace_user_field (message_ptr,
               user_field_position,
               message_user_field_parameter_ptr,
               allow_duplicates, code);

ARGUMENTS

message_ptr         (Input)
          is  a  pointer  to  the  new  message  which  is  to be
          modified.

user_field_position (Input)
          is the index within the  list of user-defined fields in
          the  message  header  of  the  field  which  is  to  be
          replaced.

message_user_field_parameter_ptr
                    (Input)
          is   a   pointer   to   a  message_user_field_parameter
          structure.    This   structure,  which   describes  the
          user-defined field that will  replace the old field, is
          declared in the  include file mlsys_message.incl.pl1 as
          follows:

               dcl 1 message_user_field_parameter
                                   aligned based
                                   (message_user_field_parameter_ptr),
                     2 version     character (8) unaligned,
                     2 user_field  like message_user_field;

          where:

          version             (Input)
                    is  the  current version  of  this structure.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    MESSAGE_USER_FIELD_PARAMETER_VERSION_2.

          section             (Input)
                    is the user-defined  field which will replace
                    the old field in the message header.  See the
                    description    of    the   message_user_field
                    structure in Section 1 of this document for a
                    detailed explanation of  the contents of this
                    structure.

allow_duplicates    (Input)
          if  "1"b,  this field  will  be placed  in  the message
          header  even if  there already is  a user-defined field
          with the same field ID present in the header.  If "0"b,
          this  field will  not be  placed into  the header under
          these circumstances.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$not_new_message
                    The   storage  identified   by  the  supplied
                    message_ptr  is an  in-mailbox message rather
                    than a new message.

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    message_user_field_parameter  structure  that
                    is not supported by the mail system.

          error_table_$bad_index
                    The value of user_field_position is less than
                    one   or   greater   than   the   number   of
                    user-defined fields in the message header.

          mlsys_et_$unknown_user_field_id
                    The   field   ID   specified   for   the  new
                    user-defined  field  has not  been registered


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

                    with  the  mail system  via  a prior  call to
                    mail_system_$get_user_field_id.

          mlsys_et_$unknown_user_field_type
                    The type  of user-defined field  specified is
                    not recognized by the mail system.

          mlsys_et_$duplicate_user_field
                    At least one user-defined field with the same
                    field  ID  as the  supplied field  is already
                    present in the message header.

             ________________________________________

Entry:  mail_system_$save_message

     This entrypoint copies a message into the specified savebox.
The  savebox may  optionally be  created if  it does  not already
exist.

USAGE

     dcl  mail_system_$save_message entry (pointer,
               character (*), character (*), bit (1) aligned,
               fixed binary (35));

     call mail_system_$save_message (message_ptr,
               savebox_dirname, savebox_ename,
               create_if_not_found, code);

ARGUMENTS

message_ptr         (Input)
          is a pointer to the message to be saved.

savebox_dirname     (Input)
          is  the absolute  pathname of  the directory containing
          the savebox.

savebox_ename       (Input)
          is the entryname of the savebox; the suffix sv.mbx need
          not be supplied by the caller.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

create_if_not_found (Input)
          if  "1"b, the  savebox will be  created if  it does not
          already exist; if "0"b, the savebox must exist prior to
          the execution of this entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$no_savebox
                    The specified savebox does  not exist and the
                    value of create_if_not_found is "0"b.

          mlsys_et_$no_a_permission
                    The user  does not have a  extended access to
                    the savebox.

          mlsys_et_$savebox_created
                    The  specified  savebox was  created  by this
                    entrypoint   and   the   message   was   then
                    successfully copied into the savebox.

NOTES

     See  the  writeup   of  mlsys_utils_$create_savebox  for  an
alternative  mechanism  to  create  the savebox  if  it  does not
already exist.

     See   the  mail_system_$deliver_message   entrypoint  for  a
description of  the default values  given to those  fields in the
message  which were  not set  by the  caller prior  to saving the
message if it is a new message.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$set_access_class

     This entrypoint sets the AIM access class of a new message.

USAGE

     dcl  mail_system_$set_access_class entry (pointer,
               bit (72) aligned, fixed binary (35));

     call mail_system_$set_access_class (message_ptr,
               access_class, code);

ARGUMENTS

message_ptr         (Input)
          is a pointer  to the new message whose  access class is
          to be changed.

access_class        (Input)
          is the new access class for the message.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$not_new_message
                    The   storage  identified   by  the  supplied
                    message_ptr  is an  in-mailbox message rather
                    than a new message.

          error_table_$ai_restricted
                    The  requested  access class  is  either less
                    than    or   isolated    from   the   process
                    authorization and the user  does not have the
                    ring-1 AIM privilege.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$unmark_message_for_deletion

     This  entrypoint  cancels  the  request for  deletion  of an
in-mailbox    message     made    by    a     prior    call    to
mail_system_$mark_message_for_deletion

USAGE

     dcl  mail_system_$unmark_message_for_deletion entry
               (pointer, fixed binary (35));

     call mail_system_$unmark_message_for_deletion (message_ptr,
               code);

ARGUMENTS

message_ptr         (pointer)
          is  a pointer  to the in-mailbox  message whose pending
          deletion is to be cancelled.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          mlsys_et_$not_in_mailbox_message
                    The   storage  identified   by  the  supplied
                    message_ptr is  a new message  rather than an
                    in-mailbox message.

          mlsys_et_$not_marked_for_deletion
                    The  specified  in-mailbox  message  was  not
                    previously marked for deletion.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mail_system_                                         mail_system_
____________                                         ____________

Entry:  mail_system_$validate_address

     This entrypoint  determines whether mail  can sucessfully by
transmitted to the supplied address.

USAGE

     dcl  mail_system_$validate_address entry (pointer,
               bit (1) aligned, fixed binary (35));

     call mail_system_$validate_address (address_ptr,
               validate_list_contents, code);

ARGUMENTS

address_ptr         (Input)
          is a pointer to the address to be validated.

validate_list_contents
                    (Input)
          controls  whether the  mail system  should validate the
          contents of the mailing  list when the supplied address
          is a  mailing list address.   If "1"b, the  mail system
          will consider the address to  be valid only if mail can
          be  transmitted to  all addresses in  the mailing list.
          If "0"b,  the mail system will  consider the address to
          be  valid  merely if  the  mailing list  exists  in the
          storage system.

code                (Output)
          is a  standard system status  code.  It will  be set to
          zero  if the  mail system  considers the  address to be
          valid    subject     to    the    setting     of    the
          validate_list_contents  parameter.  Otherwise,  it will
          be set to one of  the recipient return codes documented
          above in the writeup of mail_system_$deliver_message.


MTB-613         Mail System Programmer's Reference        MTB-613

___________                                           ___________

mlsys_info_                                           mlsys_info_
___________                                           ___________

Name:  mlsys_info_

     The mlsys_info_ subroutine provides access to several static
and/or  constant objects  maintained by the  Multics Mail System.
Such objects  include the address of  the user's default mailbox,
logbox, and mail table entry.

NOTES

     The mail_system_$compare_addresses entrypoint can be used to
determine  if the  user's mail table  address is the  same as the
user's default mailbox.  These addresses can be different if, for
example, the user does not  place links to a single Person_id.mbx
mailbox in  the default mailbox  directories for each  project on
which he is registered.  The default mailbox directory for a user
on a given project is --
          >udd>Project_id>Person_id

     Although none of the values  returned by this subroutine are
ever  null, the  addresses that  they represent  may not acutally
exist.  The mail_system_$validate_address  entrypoint can be used
to  determine  the validity  of these  addresses.  If  the user's
default  mailbox  does not  exist,  it can  be created  using the
mlsys_utils_$create_default_mailbox  entrypoint;  if  the  logbox
does    not   exist,    it   can   be    created   using   either
mail_system_$log_message or mlsys_utils_$create_logbox.

     If  either of  the value  variables Person_id.full_name._ or
full_name._ is  defined in the user's  default value segment, the
mail system will  use the value of whichever  variable is defined
as  the  address name  to  be given  to  both the  user's default
mailbox address  and mail table  address.  If both  variables are
defined,    the   mail    system   will   use    the   value   of
Person_id.full_name._.   See the  description of address names in
Section 1 of this document for more information.


MTB-613         Mail System Programmer's Reference        MTB-613

___________                                           ___________

mlsys_info_                                           mlsys_info_
___________                                           ___________

Entry:  mlsys_info_$user_default_mailbox_address

     This  entrypoint  returns  a  pointer to  the  address which
represents  the user's  default mailbox.  See  the description of
address types in Section 1 of this document for more information.

USAGE

     dcl  mlsys_info_$user_default_mailbox_address entry ()
               returns (pointer);

     user_mailbox_address_ptr =
               mlsys_info_$user_default_mailbox_address ();

ARGUMENTS

user_mailbox_address_ptr
                    (Output)
          is  set  to  locate  the address  which  represents the
          user's default  mailbox.  This address  is normally the
          same as the user's mail table address.

             ________________________________________

Entry:  mlsys_info_$user_logbox_address

     This  entrypoint  returns  a  pointer to  the  address which
represents  the user's  logbox.  See  the description  of address
types in Section 1 of this document for more information.

USAGE

     dcl  mlsys_info_$user_logbox_address entry ()
               returns (pointer);

     user_logbox_address_ptr =
               mlsys_info_$user_logbox_address ();


MTB-613         Mail System Programmer's Reference        MTB-613

___________                                           ___________

mlsys_info_                                           mlsys_info_
___________                                           ___________

ARGUMENTS

user_logbox_address_ptr
                    (Output)
          is  set  to  locate  the address  which  represents the
          user's logbox.

             ________________________________________

Entry:  mlsys_info_$user_mail_table_address

     This  entrypoint  returns  a  pointer to  the  address which
represents the user's entry in  the system's mail table.  See the
description of  address types in  Section 1 of this  document for
more information.

USAGE

     dcl  mlsys_info_$user_mail_table_address entry ()
               returns (pointer);

     user_mail_table_address_ptr =
               mlsys_info_$user_mail_table_address ();

ARGUMENTS

user_mail_table_address_ptr
                    (Output)
          is  set  to  locate  the address  which  represents the
          user's  mail table  address.  This  address is normally
          the same as the user's default mailbox.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Name:  mlsys_utils_

     The  mlsys_utils_   subroutine  provides  a   collection  of
frequently  used  Multics Mail  System utility  functions.  These
functions include the conversion of addresses, address lists, and
messages between  their internal and  printed representations and
the  creation,   deletion,  and  extended   ACL  manipulation  of
mailboxes.

             ________________________________________

Entry:  mlsys_utils_$add_mailbox_acl_entries

     This  entrypoint adds  the specified  terms to  the extended
access control list (ACL) of the specified mailbox.

USAGE

     dcl  mlsys_utils_$add_mailbox_acl_entries entry
               (character (*), character (*), pointer,
               fixed binary (35)' );

     call mlsys_utils_$add_mailbox_acl_entries
               (mailbox_dirname,);

ARGUMENTS

mailbox_dirname     (Input)
          is  the absolute  pathname of  the directory containing
          the mailbox.

mailbox_ename       (Input)
          is the  entryname of the  mailbox; the suffix  mbx need
          not be supplied by the caller.

mailbox_acl_ptr     (Input)
          is  a  pointer  to   the  mailbox_acl  structure  which
          contains the terms  to be added to the  extended ACL of
          this  mailbox.  The  mailbox_acl structure  and, unless
          stated  otherwise, all  named constants  mentioned here
          are      defined      in      the      include     file
          mlsys_mailbox_acl.incl.pl1:


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

               dcl 1 mailbox_acl   aligned based
                                   (mailbox_acl_ptr),
                     2 header,
                       3 version   character (8) unaligned,
                       3 n_acl_terms
                                   fixed binary,
                       3 pad       bit (36),
                     2 acl_terms   (mailbox_acl_n_acl_terms refer
                                   (mailbox_acl.n_acl_terms)),
                       3 access_name
                                   character (32) unaligned,
                       3 extended_mode
                                   bit (36),
                       3 code      fixed binary (35);

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    MAILBOX_ACL_VERSION_1.

          n_acl_terms         (Input)
                    is  the number  of terms  to be  added to the
                    extended ACL.

          acl_terms           (Input/Output)
                    are the  individual terms to be  added to the
                    extended ACL.

            access_name         (Input)
                      is         the          access         name
                      (Person_id.Project_id.tag) of  the ACL term
                      to be added.  If an ACL term already exists
                      in the extended ACL  with this access name,
                      the extended mode of  said term is replaced
                      by the value given in this structure.

            extended_mode       (Input)
                      is the  extended access mode  to be granted
                      to  processes  which match  this  ACL term.
                      The possible bits which  may be set in this
                      field are defined by named constants of the
                      form A_MBX_ACCESS which  are defined in the
                      include  file mlsys_mailbox_modes.incl.pl1.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

            code                (Output)
                      is a standard  system status code.  Amongst
                      the possible returned  codes, the following
                      codes  have  special  significance  to this
                      entry:

                      error_table_$invalid_ascii
                                The supplied access name contains
                                non-ASCII characters.

                      error_table_$bad_name
                                The  supplied   access  name  has
                                improper syntax.

                      error_table_$bad_acl_mode
                                The supplied extended access mode
                                has   bits  set   which  are  not
                                defined   in  the   include  file
                                mlsys_mailbox_modes.incl.pl1.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    mailbox_acl  structure that  is not supported
                    by this entrypoint.

          error_table_$argerr
                    One or more of  the per-ACL term return codes
                    is  non-zero.   In  this  case,  none  of the
                    supplied ACL terms are added to the mailbox's
                    extended ACL.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$create_default_mailbox

     This entrypoint creates the user's default mailbox.

USAGE

     dcl  mlsys_utils_$create_default_mailbox entry
               (fixed binary (35));

     call mlsys_utils_$create_default_mailbox (code);

ARGUMENTS

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$mailbox_exists
                    The user's default mailbox already exists.

NOTES

     The pathname of the user's default mailbox is --

          >udd>Project_id>Person_id>Person_id.mbx

     The extended ACL assigned to  the mailbox by this entrypoint
is --

          adrosw
               Person_id.*.*
          aow  *.SysDaemon.*
          aow  *.*.*


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$create_logbox

     This entrypoint creates the user's logbox.

USAGE

     dcl  mlsys_utils_$create_logbox entry (fixed binary (35));

     call mlsys_utils_$create_logbox (code);

ARGUMENTS

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$mailbox_exists
                    The user's logbox already exists.

NOTES

     The pathname of the user's logbox is --

          >udd>Project_id>Person_id>Person_id.sv.mbx

     The extended  ACL assigned to the  logbox by this entrypoint
is --

          adrosw
               Person_id.*.*

     The  logbox  can   also  be  created  via  a   call  to  the
mail_system_$log_message entrypoint.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$create_mailbox

     This entrypoint creates an arbitrary mailbox.

USAGE

     dcl  mlsys_utils_$create_mailbox entry (character (*),
               character (*), fixed binary (35));

     call mlsys_utils_$create_mailbox (mailbox_dirname,
               mailbox_ename, code);

ARGUMENTS

mailbox_dirname     (Input)
          is the absolute pathname of  the directory in which the
          mailbox will be created.

mailbox_ename       (Input)
          is the  entryname of the  mailbox; the suffix  mbx need
          not be supplied by the caller.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$mailbox_exists
                    The mailbox already exists.

NOTES

     The extended ACL assigned to  the mailbox by this entrypoint
is --

          adrosw
               Person_id.*.*
          aow  *.SysDaemon.*
          aow  *.*.*


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$create_reply_message

     This entrypoint creates a new message which is to be a reply
to an  in-mailbox message.  Options  are provided to  control the
initial set of recipients of the reply.

USAGE

     dcl  mlsys_utils_$create_reply_message entry (pointer,
               pointer, pointer, fixed binary (35));

     call mlsys_utils_$create_reply_message
               (original_message_ptr, reply_options_ptr,
               message_ptr, code);

ARGUMENTS

original_message_ptr
                    (Input)
          is  a  pointer to  the in-mailbox  message for  which a
          reply message is to be created.

reply_options_ptr   (Input)
          is  a  pointer to  a  reply_options structure  which is
          defined        in        the        include        file
          mlsys_reply_options.incl.pl1 as follows:

               dcl 1 reply_options aligned based
                                   (reply_options_ptr),
                     2 version     character (8) unaligned,
                     2 to          pointer,
                     2 cc          pointer,
                     2 bcc         pointer,
                     2 flags,
                       3 include_authors
                                   bit (1) unaligned,
                       3 include_recipients
                                   bit (1) unaligned,
                       3 include_self
                                   bit (1) unaligned,
                       3 mbz       bit (33) unaligned;

          where:


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    REPLY_OPTIONS_VERSION_2 which is also defined
                    in          the          include         file
                    mlsys_reply_options.incl.pl1.

          to                  (Input)
                    is  a  pointer to  an  address_list structure
                    containing additional  primary recipients for
                    the  reply  message.   If a  null  pointer is
                    given,  no additional  primary recipients are
                    included.

          cc                  (Input)
                    is  a  pointer to  an  address_list structure
                    containing  additional  secondary  recipients
                    for the reply message.   If a null pointer is
                    given, no additional secondary recipients are
                    included.

          bcc                 (Input)
                    is  a  pointer to  an  address_list structure
                    containing  additional  blind  recipients for
                    the  reply  message.   If a  null  pointer is
                    given,  no  additional  blind  recipients are
                    included.

          flags.include_authors
                              (Input)
                    if "1"b, the authors  of the original message
                    (or the  addresses in the  original message's
                    Reply-To field)  will be included  as primary
                    recipients  of the  reply in  addition to any
                    primary  recipients  given  above.   If "0"b,
                    only thos primary recipients given above will
                    be used.

          flags.include_recipients
                              (Input)
                    if "1"b, the primary and secondary recipients
                    of the  original message will  be included as
                    secondary recipients of the reply in addition
                    to any  secondary recipients given  above and
                    the blind recipients  of the original message
                    will be  included as blind  recipients of the


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    reply  in  addition to  any  blind recipients
                    given above.   If "0"b, only  those secondary
                    and  blind  recipients  given  above  will be
                    used.

          flags.include_self  (Input)
                    if  "1"b,  the  user  will be  included  as a
                    recipient of  the reply message if  he was an
                    author or  recipient of the  original message
                    and the appropriate option  above is set.  If
                    "0"b,  the user  will only  be included  as a
                    recipient of the reply if he is listed in one
                    of the above lists of additional recipients.

          flags.mbz           (Input)
                    is reserved for future  expansion and must be
                    ""b.

message_ptr         (Output)
          is  set  to  locate  the  new  message  create  by this
          entrypoint.  The  version of message  structure created
          by this entrypoint  will be the same as  the version of
          the original message.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    original_message_ptr is not a message.

          mlsys_et_$not_in_mailbox_message
                    The   storage  identified   by  the  supplied
                    original_message_ptr is a  new message rather
                    than an in-mailbox message.

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    reply_options structure that is not supported
                    by the mail system.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

NOTES

     The message created by this  entrypoint has the same subject
as  the original  message with  the string  "Re: "  added  to the
front of the subject if it  is not already present.  In addition,
the  message has  a single  reply reference  which identifies the
original message supplied by the caller.

     The  message created  by this entrypoint  has the recipients
requested by the supplied reply_options structure.  Any duplicate
addresses  in  the  lists  of  recipients  will  be automatically
eliminated by this entrypoint.

     The  message  created  by  this entrypoint  has  no authors,
user-defined  fields,  or  message   body.   The  application  or
subsystem  should  use   the  appropriate  entrypoints  described
elsewhere in this document to construct the reply.

     See   the  mail_system_$deliver_message   entrypoint  for  a
description of  the default values  given to those  fields in the
message which  were not set  by the caller  prior to transmitting
the message.

             ________________________________________

Entry:  mlsys_utils_$create_savebox

     This entrypoint creates an arbitrary savebox.

USAGE

     dcl  mlsys_utils_$create_savebox entry (character (*),
               character (*), fixed binary (35));

     call mlsys_utils_$create_savebox (mailbox_dirname,
               mailbox_ename, code);

ARGUMENTS

mailbox_dirname     (Input)
          is the absolute pathname of  the directory in which the
          savebox will be created.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

mailbox_ename       (Input)
          is the entryname of the savebox; the suffix sv.mbx need
          not be supplied by the caller.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$mailbox_exists
                    The savebox already exists.

NOTES

     The extended ACL assigned to  the savebox by this entrypoint
is --

          adrosw
               Person_id.*.*

                    A savebox  can also be created  via a call to
               the mail_system_$save_message entrypoint.

             ________________________________________

Entry:  mlsys_utils_$delete_mailbox

     This entrypoint deletes a mailbox.

USAGE

     dcl  mlsys_utils_$delete_mailbox entry (character (*),
               character (*), character (*), pointer,
               fixed binary (35));

     call mlsys_utils_$delete_mailbox (mailbox_dirname,
               mailbox_ename, command_name, delete_options_ptr,
               code);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

ARGUMENTS

mailbox_dirname     (Input)
          is  the absolute  pathname of  the directory containing
          the mailbox to be deleted.

mailbox_ename       (Input)
          is the  entryname of the  mailbox; the suffix  mbx need
          not be supplied by the caller.

command_name        (Input)
          is the name  of the command or request  on whose behalf
          the mailbox is to be deleted.  This name is used in any
          queries made by this entrypoint.

delete_options_ptr  (Input)
          is  a pointer  to a  delete_options structure  which is
          defined        in        the        include        file
          mlsys_delete_mailbox.incl.pl1 as follows:

               dcl 1 delete_options
                                   aligned based
                                   (delete_options_ptr),
                     2 version     character (8) unaligned,
                     2 flags,
                       3 force     bit (1) unaligned,
                       3 query     bit (1) unaligned,
                       3 chase     bit (1) unaligned,
                       3 mbz       bit (33) unaligned;

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version of the  structure defined here is
                    given  by  the  value of  the  named constant
                    DELETE_OPTIONS_VERSION_1   which    is   also
                    defined      in     the      include     file
                    mlsys_delete_mailbox.incl.pl1.

          flags.force         (Input)
                    if  "1"b,  this  entrypoint  will  attempt to
                    delete  the  mailbox even  though  its safety
                    switch  is  set  by  first  turning  off  the
                    switch.   If "0"b,  this entrypoint  will use
                    the value of the  query option to control its


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    actions when a mailbox whose safety switch is
                    set is encountered.

          flags.query         (Input)
                    if "1"b and the force option is not set, this
                    entrypoint will query the user for permission
                    to delete the mailbox if its safety switch is
                    set.   If "0"b  and the  force option  is not
                    set,  this entrypoint  will refuse  to delete
                    any mailbox whose safety switch is set.

          flags.chase         (Input)
                    if "1"b and  the supplied pathname identifies
                    a  link,  this  entrypoint  will  attempt  to
                    delete  the  mailbox which  is the  target of
                    that  link.  Otherwise,  this entrypoint will
                    reject attempts to delete through a link.

          flags.mbz           (Input)
                    is reserved for future  expansion and must be
                    set to ""b by the caller.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_mailbox
                    The  storage  system  entry  with  the  given
                    pathname is not a Multics mailbox.

          error_table_$safety_sw_on
                    The mailbox is protected by the safety switch
                    and can not be deleted.

          error_table_$action_not_performed
                    The mailbox is protected by the safety switch
                    and the caller specified the query option but
                    the user answered "no" to the query to delete
                    the mailbox.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$delete_mailbox_acl_entries

     This  entrypoint  deletes  the   specified  terms  from  the
extended access control list (ACL) of the given mailbox.

USAGE

     dcl  mlsys_utils_$delete_mailbox_acl_entries entry
               (character (*), character (*), pointer,
               fixed binary (35));

     call mlsys_utils_$delete_mailbox_acl_entries
               (mailbox_dirname, mailbox_ename, mailbox_acl_ptr,
               code);

ARGUMENTS

mailbox_dirname     (Input)
          is  the absolute  pathname of  the directory containing
          the mailbox.

mailbox_ename       (Input)
          is the  entryname of the  mailbox; the suffix  mbx need
          not be supplied by the caller.

mailbox_acl_ptr     (Input)
          is  a  pointer  to   the  mailbox_acl  structure  which
          identifies  the terms  to be deleted  from the extended
          ACL  of  the mailbox.   The mailbox_acl  structure and,
          unless stated otherwise,  all named constants mentioned
          here    are    defined     in    the    include    file
          mlsys_mailbox_acl.incl.pl1:

               dcl 1 mailbox_acl   aligned based
                                   (mailbox_acl_ptr),
                     2 header,
                       3 version   character (8) unaligned,
                       3 n_acl_terms
                                   fixed binary,
                       3 pad       bit (36),
                     2 acl_terms   (mailbox_acl_n_acl_terms refer
                                   (mailbox_acl.n_acl_terms)),
                       3 access_name
                                   character (32) unaligned,
                       3 extended_mode


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                                   bit (36),
                       3 code      fixed binary (35);

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    MAILBOX_ACL_VERSION_1.

          n_acl_terms         (Input)
                    is the number of terms to be deleted from the
                    extended ACL.

          acl_terms           (Input/Output)
                    are the terms to be deleted from the extended
                    ACL.

            access_name         (Input)
                      is         the          access         name
                      (Person_id.Project_id.tag) of  the ACL term
                      to be deleted.

            extended_mode       (Input)
                      is ignored by this entrypoint.

            code                (Output)
                      is a standard  system status code.  Amongst
                      the possible returned  codes, the following
                      codes  have  special  significance  to this
                      entry:

                      error_table_$invalid_ascii
                                The supplied access name contains
                                non-ASCII characters.

                      error_table_$bad_name
                                The  supplied   access  name  has
                                improper syntax.

                      error_table_$user_not_found
                                There is no term in the mailbox's
                                extended   ACL  with   the  given
                                access  name.  This  error is not
                                considered  to  be fatal  by this
                                entrypoint (see below).


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          0         All  of the  terms whose return  code is zero
                    have been deleted from the mailbox's extended
                    ACL.  In  addition, there may  be terms whose
                    return  code  is  error_table_$user_not_found
                    indicating that they were  not present in the
                    mailbox's  extended  ACL when  this  call was
                    made.

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    mailbox_acl  structure that  is not supported
                    by this entrypoint.

          error_table_$argerr
                    One or more of  the per-ACL term return codes
                    is      both       non-zero      and      not
                    error_table_$user_not_found.   In  this case,
                    none  of the  supplied ACL  terms are deleted
                    from the mailbox's extended ACL.

             ________________________________________

Entry:  mlsys_utils_$format_access_class_field

     This  entrypoint  converts  a message  envelope,  header, or
redistributions list  field containing an AIM  access class value
into  its  printed representation.   See  the description  of the
printed representation of messages  in Section 1 of this document
for more information.

USAGE

     dcl  mlsys_utils_$format_access_class_field entry
               (character (*) varying, bit (72) aligned,
               fixed binary, pointer, fixed binary (21),
               fixed binary (21), fixed binary (35));

     call mlsys_utils_$format_access_class_field (field_name,
               access_class, line_length, buffer_ptr,
               buffer_size, buffer_used, code);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

ARGUMENTS

field_name          (Input)
          is the  name of this  field.  The field's  name and its
          value will be separated by the string ":  ".  The names
          of the standard fields supported by the mail system are
          available as  the values of the  named constants in the
          include file mlsys_field_names.incl.pl1.

access_class        (Input)
          is the access class which is the value of this field.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of this field.  This parameter must have
          a value greater than 20 or  equal to -1.  A value of -1
          indicates that  there is no  limit on the  width of the
          output produced by this entrypoint.

buffer_ptr          (Input)
          is  a  pointer  to  the buffer  where  the  the printed
          representation of this field will be placed.

buffer_size         (Input)
          is the size of the buffer in characters.

buffer_used         (Input/Output)
          on input,  is the number of  characters already present
          in  the  buffer.   The printed  representation  of this
          field  will  be  placed  into  the  buffer  after these
          characters.   On output,  this parameter  is updated to
          reflect the number of  characters present in the buffer
          including  the  printed  representation  added  by this
          entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

          error_table_$smallarg
                    The  amount  of  unused space  in  the buffer


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    supplied by  the caller is too  small to hold
                    the printed representation of this field.

             ________________________________________

Entry:  mlsys_utils_$format_address_field

     This  entrypoint  converts  a message  envelope,  header, or
redistributions list  field containing a single  address into its
printed  representation.   See  the  description  of  the printed
representation  of addresses  and messages  in Section 1  of this
document for more information.

USAGE

     dcl  mlsys_utils_$format_address_field entry
               (character (*) varying, pointer, fixed binary,
               pointer, fixed binary (21), fixed binary (21),
               fixed binary (35));

     call mlsys_utils_$format_address_field (field_name,
               address_ptr, line_length, buffer_ptr, buffer_size,
               buffer_used, code);

ARGUMENTS

field_name          (Input)
          is the  name of this  field.  The field's  name and its
          value will be separated by the string ":  ".  The names
          of the standard fields supported by the mail system are
          available as  the values of the  named constants in the
          include file mlsys_field_names.incl.pl1.

address_ptr         (Input)
          is a pointer to the address  which is the value of this
          field.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of this field.  This parameter must have
          a value greater than 20 or  equal to -1.  A value of -1
          indicates that  there is no  limit on the  width of the
          output produced by this entrypoint.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

buffer_ptr          (Input)
          is  a  pointer  to  the buffer  where  the  the printed
          representation of this field will be placed.

buffer_size         (Input)
          is the size of the buffer in characters.

buffer_used         (Input/Output)
          on input,  is the number of  characters already present
          in  the  buffer.   The printed  representation  of this
          field  will  be  placed  into  the  buffer  after these
          characters.   On output,  this parameter  is updated to
          reflect the number of  characters present in the buffer
          including  the  printed  representation  added  by this
          entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address
                    The   storage  identified   by  the  supplied
                    address_ptr is not an address.

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

          error_table_$smallarg
                    The  amount  of  unused space  in  the buffer
                    supplied by  the caller is too  small to hold
                    the printed representation of this field.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$format_address_list_field

     This  entrypoint  converts  a message  envelope,  header, or
redistributions  list field  containing an address  list into its
printed  representation.   See  the  description  of  the printed
representation of address lists and messages in Section 1 of this
document for more information.

USAGE

     dcl  mlsys_utils_$format_address_list_field entry
               (character (*) varying, pointer, fixed binary,
               pointer, fixed binary (21), fixed binary (21),
               fixed binary (35));

     call mlsys_utils_$format_address_list_field (field_name,
               address_list_ptr, line_length, buffer_ptr,
               buffer_size, buffer_used, code);

ARGUMENTS

field_name          (Input)
          is the  name of this  field.  The field's  name and its
          value will be separated by the string ":  ".  The names
          of the standard fields supported by the mail system are
          available as  the values of the  named constants in the
          include file mlsys_field_names.incl.pl1.

address_list_ptr    (Input)
          is a pointer to the address_list structure which is the
          value of this field.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of this field.  This parameter must have
          a value greater than 20 or  equal to -1.  A value of -1
          indicates that  there is no  limit on the  width of the
          output produced by this entrypoint.

buffer_ptr          (Input)
          is  a  pointer  to  the buffer  where  the  the printed
          representation of this field will be placed.

buffer_size         (Input)
          is the size of the buffer in characters.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

buffer_used         (Input/Output)
          on input,  is the number of  characters already present
          in  the  buffer.   The printed  representation  of this
          field  will  be  placed  into  the  buffer  after these
          characters.   On output,  this parameter  is updated to
          reflect the number of  characters present in the buffer
          including  the  printed  representation  added  by this
          entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address_list
                    The   storage  identified   by  the  supplied
                    address_list_ptr is not an address list.

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

          error_table_$smallarg
                    The  amount  of  unused space  in  the buffer
                    supplied by  the caller is too  small to hold
                    the printed representation of this field.

             ________________________________________

Entry:  mlsys_utils_$format_body_section

     This entrypoint converts a section  of the body of a message
into  its  printed representation.   See  the description  of the
printed representation of messages  in Section 1 of this document
for more information.

USAGE

     dcl  mlsys_utils_$format_body_section entry (pointer,
               fixed binary, pointer, fixed binary (21),
               fixed binary (21), fixed binary (35));

     call mlsys_utils_$format_body_section


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

               (message_body_section_parameter_ptr, line_length,
               buffer_ptr, buffer_size, buffer_used, code);

ARGUMENTS

message_body_section_parameter_ptr
                    (Input)
          is   a  pointer   to  a  message_body_section_parameter
          structure.  This structure, which describes the section
          that will be formatted, is  defined in the include file
          mlsys_message.incl.pl1 as follows:

               dcl 1 message_body_section_parameter
                                   aligned based
                                   (message_body_section_parameter_ptr),
                     2 version     character (8) unaligned,
                     2 section     like message_body_section;

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    MESSAGE_BODY_SECTION_PARAMETER_VERSION_2.

          section             (Input/Output)
                    is   the  section   to  be   formatted.   The
                    section_n_lines field in  this structure will
                    be set to the number  of lines in the section
                    after formatting.  See the description of the
                    message_body_section  structure  in Section 1
                    of this  document for a  detailed explanation
                    of the contents of this structure.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation  of   this  section  if  it   is  not  a
          preformatted section.  This parameter must have a value
          greater  than  20  or  equal  to  -1.   A  value  of -1
          indicates that  there is no  limit on the  width of the
          output produced by this entrypoint.

buffer_ptr          (Input)
          is  a  pointer  to  the buffer  where  the  the printed
          representation of this section will be placed.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

buffer_size         (Input)
          is the size of the buffer in characters.

buffer_used         (Input/Output)
          on input,  is the number of  characters already present
          in  the  buffer.   The printed  representation  of this
          section  of  the body  will be  placed into  the buffer
          after these  characters.  On output,  this parameter is
          updated to reflect the  number of characters present in
          the buffer  including the printed  representation added
          by this entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    message_body_section_parameter structure that
                    is not supported by the mail system.

          error_table_$unknown_body_section
                    The type of message body section specified is
                    not recognized by the mail system.

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

          error_table_$smallarg
                    The  amount  of  unused space  in  the buffer
                    supplied by  the caller is too  small to hold
                    the printed representation of this section.

NOTES

     This  entrypoint  does  not   place  the  blank  line  which
separates sections of a message body into the output buffer.  The
caller  is  responsible  for  including  said  blank  lines where
appropriate.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$format_date_time_field

     This  entrypoint  converts  a message  envelope,  header, or
redistributions list  field whose value  is a date/time  into its
printed  representation.   See  the  description  of  the printed
representation of messages in Section 1 of this document for more
information.

USAGE

     dcl  mlsys_utils_$format_date_time_field entry
               (character (*) varying, fixed binary (71),
               bit (1) aligned, fixed binary, pointer,
               fixed binary (21), fixed binary (21),
               fixed binary (35));

     call mlsys_utils_$format_date_time_field (field_name,
               date_time, include_dow, line_length, buffer_ptr,
               buffer_size, buffer_used, code);

ARGUMENTS

field_name          (Input)
          is the  name of this  field.  The field's  name and its
          value will be separated by the string ":  ".  The names
          of the standard fields supported by the mail system are
          available as  the values of the  named constants in the
          include file mlsys_field_names.incl.pl1.

date_time           (Input)
          is  a  standard  Multics clock  value  representing the
          date/time which is the value of this field.

include_dow         (Input)
          if "1"b, the name of  the day of the week corresponding
          to  the  supplied  date/time  will be  included  in the
          printed representation.   If "0"b, the day  of the week
          will not be included in the printed representation.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of this field.  This parameter must have
          a value greater than 20 or  equal to -1.  A value of -1
          indicates that  there is no  limit on the  width of the
          output produced by this entrypoint.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

buffer_ptr          (Input)
          is  a  pointer  to  the buffer  where  the  the printed
          representation of this field will be placed.

buffer_size         (Input)
          is the size of the buffer in characters.

buffer_used         (Input/Output)
          on input,  is the number of  characters already present
          in  the  buffer.   The printed  representation  of this
          field  will  be  placed  into  the  buffer  after these
          characters.   On output,  this parameter  is updated to
          reflect the number of  characters present in the buffer
          including  the  printed  representation  added  by this
          entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

          error_table_$smallarg
                    The  amount  of  unused space  in  the buffer
                    supplied by  the caller is too  small to hold
                    the printed representation of this field.

             ________________________________________

Entry:  mlsys_utils_$format_message

     This  entrypoint   converts  a  message   into  its  printed
representation.    See    the   description   of    the   printed
representation of messages in Section 1 of this document for more
information.

USAGE

     dcl  mlsys_utils_$format_message entry (pointer, pointer,
               pointer, fixed binary (21), fixed binary (21),
               fixed binary (35));


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

     call mlsys_utils_$format_message (message_ptr,
               format_message_options_ptr, buffer_ptr,
               buffer_size, buffer_used, code);

ARGUMENTS

message_ptr         (Input)
          is a  pointer to the  message to be  converted into its
          printed representation.

format_message_options_ptr
                    (Input)
          is  a  pointer to  a  format_message_options structure.
          This structure and, unless  stated otherwise, all named
          constants  mentioned  here are  defined in  the include
          file mlsys_format_options.incl.pl1:

               dcl 1 format_message_options
                                   aligned based
                                   (format_message_options_ptr),
                     2 version     character (8) unaligned,
                     2 line_length fixed binary,
                     2 envelope_formatting_mode
                                   fixed binary,
                     2 header_formatting_mode
                                   fixed binary,
                     2 redistributions_list_formatting_mode
                                   fixed binary,
                     2 include_body
                                   bit (1) aligned;

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    FORMAT_MESSAGE_OPTIONS_VERSION_1.

          line_length         (Input)
                    is  the  maximum width  for  any line  in the
                    printed   representation  of   the  envelope,
                    header,  and  redistributions  list  of  this
                    message.   This parameter  must have  a value
                    greater than  20 or equal to  -1.  A value of


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    -1  indicates that  there is no  limit on the
                    width   of  the   output  produced   by  this
                    entrypoint.

          envelope_formatting_mode
                              (Input)
          header_formatting_mode
                              (Input)
          redistributions_list_formatting_mode
                              (Input)
                    specify  the  level   of  information  to  be
                    included in the printed representation of the
                    message envelope, header, and redistributions
                    list, respectively.  The  possible values for
                    these fields are given by the following named
                    constants:

                    LONG_FORMATTING_MODE
                              specifies  that  the  long  form of
                              this part  of the message  is to be
                              included     in     the     printed
                              representation of the message.

                    DEFAULT_FORMATTING_MODE
                              specifies that the  default form of
                              this part  of the message  is to be
                              included     in     the     printed
                              representation of the message.

                    BRIEF_FORMATTING_MODE
                              specifies  that  the brief  form of
                              this part  of the message  is to be
                              included     in     the     printed
                              representation   of   the  message.
                              This  value is  not a  valid choice
                              for   the  envelope_formatting_mode
                              parameter.

                    NONE_FORMATTING_MODE
                              specifies  that  this  part  of the
                              message is to  be excluded from the
                              printed   representation   of   the
                              message.

          include_body        (Input)
                    if   "1"b,   specifies   that   the   printed
                    representation of  the message body  is to be


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    included in the printed representation of the
                    message.   If  "0"b,   the  message  body  is
                    excluded from the printed representation.

buffer_ptr          (Input)
          is  a  pointer  to  the buffer  where  the  the printed
          representation of this message will be placed.

buffer_size         (Input)
          is the size of the buffer in characters.

buffer_used         (Input/Output)
          on input,  is the number of  characters already present
          in  the  buffer.   The printed  representation  of this
          message  will  be placed  into  the buffer  after these
          characters.   On output,  this parameter  is updated to
          reflect the number of  characters present in the buffer
          including  the  printed  representation  added  by this
          entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    format_message_options structure  that is not
                    supported by the mail system.

          error_table_$bad_subr_arg
                    Either  the caller  supplied a  value for the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1 or the caller
                    supplied  a value  for one  of the formatting
                    modes  that  is  not  supported  by  the mail
                    system.

          error_table_$smallarg
                    The  amount  of  unused space  in  the buffer
                    supplied by  the caller is too  small to hold
                    the printed representation of this message.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$format_message_body

     This entrypoint converts the body  of the given message into
its printed  representation.  See the description  of the printed
representation of messages in Section 1 of this document for more
information.

USAGE

     dcl  mlsys_utils_$format_message_body entry (pointer,
               fixed binary, pointer, fixed binary (21),
               fixed binary (21), fixed binary (35));

     call mlsys_utils_$format_message_body (message_ptr,
               line_length, buffer_ptr, buffer_size, buffer_used,
               code);

ARGUMENTS

message_ptr         (Input)
          is  a  pointer  to  the message  whose  body  is  to be
          converted into its printed representation.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of  the message body  for those sections
          of the body which  are not preformatted sections.  This
          parameter must have a value greater than 20 or equal to
          -1.  A value of -1 indicates  that there is no limit on
          the width of the output produced by this entrypoint.

buffer_ptr          (Input)
          is  a  pointer  to  the buffer  where  the  the printed
          representation  of  the body  of  this message  will be
          placed.

buffer_size         (Input)
          is the size of the buffer in characters.

buffer_used         (Input/Output)
          on input,  is the number of  characters already present
          in the buffer.  The  printed representation of the body
          of this  message will be  placed into the  buffer after
          these characters.  On output, this parameter is updated
          to  reflect  the number  of  characters present  in the


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          buffer  including the  printed representation  added by
          this entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

          error_table_$smallarg
                    The  amount  of  unused space  in  the buffer
                    supplied by  the caller is too  small to hold
                    the  printed  representation of  the  body of
                    this message.

             ________________________________________

Entry:  mlsys_utils_$format_message_envelope

     This  entrypoint  converts  the  envelope  of  the  supplied
message into its printed  representation.  See the description of
the  printed  representation  of  messages in  Section 1  of this
document for more information.

USAGE

     dcl  mlsys_utils_$format_message_envelope entry (pointer,
               fixed binary, fixed binary, pointer,
               fixed binary (21), fixed binary (21),
               fixed binary (35));

     call mlsys_utils_$format_message_envelope (message_ptr,
               line_length, formatting_mode, buffer_ptr,
               buffer_size, buffer_used, code);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

ARGUMENTS

message_ptr         (Input)
          is  a pointer  to the message  whose envelope  is to be
          converted into its printed representation.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of  the envelope of  this message.  This
          parameter must have a value greater than 20 or equal to
          -1.  A value of -1 indicates  that there is no limit on
          the width of the output produced by this entrypoint.

formatting_mode     (Input)
          specifies  the level  of information to  be included in
          the  printed  representation  of the  envelope  of this
          message.   The possible  values for  this parameter are
          given  by  the  following  named  constants  which  are
          defined        in        the        include        file
          mlsys_format_options.incl.pl1:

          LONG_FORMATTING_MODE
                    specifies that  the long form  of the printed
                    representation  of  the  envelope  is  to  be
                    returned.

          DEFAULT_FORMATTING_MODE
                    specifies  that  the   default  form  of  the
                    printed representation of  the envelope is to
                    be returned.

buffer_ptr          (Input)
          is  a  pointer  to  the buffer  where  the  the printed
          representation of the envelope  of this message will be
          placed.

buffer_size         (Input)
          is the size of the buffer in characters.

buffer_used         (Input/Output)
          on input,  is the number of  characters already present
          in  the  buffer.   The  printed  representation  of the
          envelope of this message will be placed into the buffer
          after these  characters.  On output,  this parameter is
          updated to reflect the  number of characters present in
          the buffer  including the printed  representation added
          by this entrypoint.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          error_table_$bad_subr_arg
                    Either  the caller  supplied a  value for the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1 or the caller
                    supplied  a  value  for  the  formatting_mode
                    parameter that  is not supported  by the mail
                    system.

          error_table_$smallarg
                    The  amount  of  unused space  in  the buffer
                    supplied by  the caller is too  small to hold
                    the printed representation of the envelope of
                    this message.

             ________________________________________

Entry:  mlsys_utils_$format_message_header

     This entrypoint converts the  header of the supplied message
into  its  printed representation.   See  the description  of the
printed representation of messages  in Section 1 of this document
for more information.

USAGE

     dcl  mlsys_utils_$format_message_header entry (pointer,
               fixed binary, fixed binary, pointer,
               fixed binary (21), fixed binary (21),
               fixed binary (35));

     call mlsys_utils_$format_message_header (message_ptr,
               line_length, formatting_mode, buffer_ptr,
               buffer_size, buffer_used, code);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

ARGUMENTS

message_ptr         (Input)
          is  a  pointer to  the  message whose  header is  to be
          converted into its printed representation.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation  of  the header  of this  message.  This
          parameter must have a value greater than 20 or equal to
          -1.  A value of -1 indicates  that there is no limit on
          the width of the output produced by this entrypoint.

formatting_mode     (Input)
          specifies  the level  of information to  be included in
          the  printed  representation  of  the  header  of  this
          message.   The possible  values for  this parameter are
          given  by  the  following  named  constants  which  are
          defined        in        the        include        file
          mlsys_format_options.incl.pl1:

          LONG_FORMATTING_MODE
                    specifies that  the long form  of the printed
                    representation  of   the  header  is   to  be
                    returned.

          DEFAULT_FORMATTING_MODE
                    specifies  that  the   default  form  of  the
                    printed representation of the header is to be
                    returned.

          DEFAULT_FORMATTING_MODE
                    specifies that the brief  form of the printed
                    representation  of   the  header  is   to  be
                    returned.

buffer_ptr          (Input)
          is  a  pointer  to  the buffer  where  the  the printed
          representation  of the  header of this  message will be
          placed.

buffer_size         (Input)
          is the size of the buffer in characters.

buffer_used         (Input/Output)
          on input,  is the number of  characters already present
          in  the  buffer.   The  printed  representation  of the


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          header of  this message will be  placed into the buffer
          after these  characters.  On output,  this parameter is
          updated to reflect the  number of characters present in
          the buffer  including the printed  representation added
          by this entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          error_table_$bad_subr_arg
                    Either  the caller  supplied a  value for the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1 or the caller
                    supplied  a  value  for  the  formatting_mode
                    parameter that  is not supported  by the mail
                    system.

          error_table_$smallarg
                    The  amount  of  unused space  in  the buffer
                    supplied by  the caller is too  small to hold
                    the printed  representation of the  header of
                    this message.

             ________________________________________

Entry:  mlsys_utils_$format_message_id_field

     This  entrypoint  converts  a message  envelope,  header, or
redistributions  list field  whose value  is a  unique identifier
into  its  printed representation.   See  the description  of the
printed representation of messages  in Section 1 of this document
for more information.

USAGE

     dcl  mlsys_utils_$format_message_id_field entry
               (character (*) varying, bit (72) aligned,
               fixed binary, pointer, fixed binary (21),
               fixed binary (21), fixed binary (35));


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

     call mlsys_utils_$format_message_id_field (field_name,
               unique_id, line_length, buffer_ptr, buffer_size,
               buffer_used, code);

ARGUMENTS

field_name          (Input)
          is the  name of this  field.  The field's  name and its
          value will be separated by the string ":  ".  The names
          of the standard fields supported by the mail system are
          available as  the values of the  named constants in the
          include file mlsys_field_names.incl.pl1.

unique_id           (Input)
          is  the unique  identifier which  is the  value of this
          field.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of this field.  This parameter must have
          a value greater than 20 or  equal to -1.  A value of -1
          indicates that  there is no  limit on the  width of the
          output produced by this entrypoint.

buffer_ptr          (Input)
          is  a  pointer  to  the buffer  where  the  the printed
          representation of this field will be placed.

buffer_size         (Input)
          is the size of the buffer in characters.

buffer_used         (Input/Output)
          on input,  is the number of  characters already present
          in  the  buffer.   The printed  representation  of this
          field  will  be  placed  into  the  buffer  after these
          characters.   On output,  this parameter  is updated to
          reflect the number of  characters present in the buffer
          including  the  printed  representation  added  by this
          entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

          error_table_$smallarg
                    The  amount  of  unused space  in  the buffer
                    supplied by  the caller is too  small to hold
                    the printed representation of this field.

             ________________________________________

Entry:  mlsys_utils_$format_message_redistributions_list

     This  entrypoint  converts the  redistributions list  of the
supplied  message  into  its  printed  representation.   See  the
description  of   the  printed  representation   of  messages  in
Section 1 of this document for more information.

USAGE

     dcl  mlsys_utils_$format_message_redistributions_list entry
               (pointer, fixed binary, fixed binary, pointer,
               fixed binary (21), fixed binary (21),
               fixed binary (35));

     call mlsys_utils_$format_message_redistributions_list
               (message_ptr, line_length, formatting_mode,
               buffer_ptr, buffer_size, buffer_used, code);

ARGUMENTS

message_ptr         (Input)
          is a pointer to  the message whose redistributions list
          is to be converted into its printed representation.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation  of  the  redistributions  list  of this
          message.  This parameter must have a value greater than
          20 or equal to -1.  A  value of -1 indicates that there
          is no limit on the width of the output produced by this
          entrypoint.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

formatting_mode     (Input)
          specifies  the level  of information to  be included in
          the printed representation  of the redistributions list
          of  this   message.   The  possible   values  for  this
          parameter  are given  by the  following named constants
          which    are    defined    in    the    include    file
          mlsys_format_options.incl.pl1:

          LONG_FORMATTING_MODE
                    specifies that  the long form  of the printed
                    representation of the redistributions list is
                    to be returned.

          DEFAULT_FORMATTING_MODE
                    specifies  that  the   default  form  of  the
                    printed representation of the redistributions
                    list is to be returned.

          DEFAULT_FORMATTING_MODE
                    specifies that the brief  form of the printed
                    representation of the redistributions list is
                    to be returned.

buffer_ptr          (Input)
          is  a  pointer  to  the buffer  where  the  the printed
          representation  of  the  redistributions  list  of this
          message will be placed.

buffer_size         (Input)
          is the size of the buffer in characters.

buffer_used         (Input/Output)
          on input,  is the number of  characters already present
          in  the  buffer.   The  printed  representation  of the
          redistributions  list  of this  message will  be placed
          into  the  buffer after  these characters.   On output,
          this  parameter  is updated  to  reflect the  number of
          characters present in the  buffer including the printed
          representation added by this entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          error_table_$bad_subr_arg
                    Either  the caller  supplied a  value for the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1 or the caller
                    supplied  a  value  for  the  formatting_mode
                    parameter that  is not supported  by the mail
                    system.

          error_table_$smallarg
                    The  amount  of  unused space  in  the buffer
                    supplied by  the caller is too  small to hold
                    the    printed    representation    of    the
                    redistributions list of this message.

             ________________________________________

Entry:  mlsys_utils_$format_message_references_list_field

     This  entrypoint  converts  a message  envelope,  header, or
redistributions list field whose value is a list of references to
other  messages   into  its  printed   representation.   See  the
description  of   the  printed  representation   of  messages  in
Section 1 of this document for more information.

USAGE

     dcl  mlsys_utils_$format_message_references_list_field entry
               (character (*) varying, pointer, fixed binary,
               pointer, fixed binary (21), fixed binary (21),
               fixed binary (35));

     call mlsys_utils_$format_message_references_list_field
               (field_name, message_references_list_ptr,
               line_length, buffer_ptr, buffer_size, buffer_used,
               code);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

ARGUMENTS

field_name          (Input)
          is the  name of this  field.  The field's  name and its
          value will be separated by the string ":  ".  The names
          of the standard fields supported by the mail system are
          available as  the values of the  named constants in the
          include file mlsys_field_names.incl.pl1.

message_references_list_ptr
                    (Input)
          is a  pointer to the  message_references_list structure
          which  is the  value of  this field.   See Section 1 of
          this document for a description of the contents of this
          structure.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of this field.  This parameter must have
          a value greater than 20 or  equal to -1.  A value of -1
          indicates that  there is no  limit on the  width of the
          output produced by this entrypoint.

buffer_ptr          (Input)
          is  a  pointer  to  the buffer  where  the  the printed
          representation of this field will be placed.

buffer_size         (Input)
          is the size of the buffer in characters.

buffer_used         (Input/Output)
          on input,  is the number of  characters already present
          in  the  buffer.   The printed  representation  of this
          field  will  be  placed  into  the  buffer  after these
          characters.   On output,  this parameter  is updated to
          reflect the number of  characters present in the buffer
          including  the  printed  representation  added  by this
          entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    message_references_list structure that is not
                    supported by the mail system.

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

          error_table_$smallarg
                    The  amount  of  unused space  in  the buffer
                    supplied by  the caller is too  small to hold
                    the printed representation of this field.

             ________________________________________

Entry:  mlsys_utils_$format_message_trace

     This  entrypoint converts  a message trace  into its printed
representation.    See    the   description   of    the   printed
representation of messages in Section 1 of this document for more
information.

USAGE

     dcl  mlsys_utils_$format_message_trace entry (pointer,
               bit (1) aligned, fixed binary, pointer,
               fixed binary (21), fixed binary (21),
               fixed binary (35));

     call mlsys_utils_$format_message_trace (message_trace_ptr,
               format_redistribution_trace, line_length,
               buffer_ptr, buffer_size, buffer_used, code);

ARGUMENTS

message_trace_ptr   (Input)
          is  a  pointer  to  the  message_trace  structure which
          defines  the  message trace  to  be converted  into its
          printed representation.   This structure is  defined in
          the   include   file   mlsys_message.incl.pl1   and  is
          described in detail in Section 1 of this document.

format_redistribution_trace
                    (Input)


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          specifies  whether  this  message  trace is  part  of a
          message  envelope  or  a  redistribution  envelope.  If
          "1"b,  the trace  is part of  a redistribution envelope
          and   this   entrypoint  will   use  the   field  names
          Redistributed-Route  and  Redistributed-Relayed  in the
          printed representation.  If "0"b,  the trace is part of
          a  message envelope  and this  entrypoint will  use the
          field   names   Route  and   Relayed  in   the  printed
          representation.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of  this message trace.   This parameter
          must have  a value greater  than 20 or equal  to -1.  A
          value  of -1  indicates that there  is no  limit on the
          width of the output produced by this entrypoint.

buffer_ptr          (Input)
          is  a  pointer  to  the buffer  where  the  the printed
          representation of this message trace will be placed.

buffer_size         (Input)
          is the size of the buffer in characters.

buffer_used         (Input/Output)
          on input,  is the number of  characters already present
          in  the  buffer.   The printed  representation  of this
          message  trace  will be  placed  into the  buffer after
          these characters.  On output, this parameter is updated
          to  reflect  the number  of  characters present  in the
          buffer  including the  printed representation  added by
          this entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message_trace
                    The   storage  identified   by  the  supplied
                    message_trace_ptr is not a message trace.

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          error_table_$smallarg
                    The  amount  of  unused space  in  the buffer
                    supplied by  the caller is too  small to hold
                    the  printed  representation of  this message
                    trace.

             ________________________________________

Entry:  mlsys_utils_$format_text_field

     This  entrypoint  converts  a message  envelope,  header, or
redistributions list field whose value  is a text string into its
printed  representation.   See  the  description  of  the printed
representation of messages in Section 1 of this document for more
information.

USAGE

     dcl  mlsys_utils_$format_text_field entry
               (character (*) varying, character (*),
               fixed binary, pointer, fixed binary (21),
               fixed binary (21), fixed binary (35));

     call mlsys_utils_$format_text_field (field_name, field_text,
               line_length, buffer_ptr, buffer_size, buffer_used,
               code);

ARGUMENTS

field_name          (Input)
          is the  name of this  field.  The field's  name and its
          value will be separated by the string ":  ".  The names
          of the standard fields supported by the mail system are
          available as  the values of the  named constants in the
          include file mlsys_field_names.incl.pl1.

field_text          (Input)
          is the text string which is the value of this field.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of this field.  This parameter must have
          a value greater than 20 or  equal to -1.  A value of -1


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          indicates that  there is no  limit on the  width of the
          output produced by this entrypoint.

buffer_ptr          (Input)
          is  a  pointer  to  the buffer  where  the  the printed
          representation of this field will be placed.

buffer_size         (Input)
          is the size of the buffer in characters.

buffer_used         (Input/Output)
          on input,  is the number of  characters already present
          in  the  buffer.   The printed  representation  of this
          field  will  be  placed  into  the  buffer  after these
          characters.   On output,  this parameter  is updated to
          reflect the number of  characters present in the buffer
          including  the  printed  representation  added  by this
          entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

          error_table_$smallarg
                    The  amount  of  unused space  in  the buffer
                    supplied by  the caller is too  small to hold
                    the printed representation of this field.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$list_mailbox_acl

     This   entrypoint  returns   the  extended   access  control
list (ACL) of the specified mailbox.

USAGE

     dcl  mlsys_utils_$list_mailbox_acl entry (character (*),
               character (*), pointer, character (8), pointer,
               fixed binary (35));

     call mlsys_utils_$list_mailbox_acl (mailbox_dirname,
               mailbox_ename, area_ptr, mailbox_acl_version,
               mailbox_acl_ptr, code);

ARGUMENTS

mailbox_dirname     (Input)
          is  the absolute  pathname of  the directory containing
          the mailbox.

mailbox_ename       (Input)
          is the  entryname of the  mailbox; the suffix  mbx need
          not be supplied by the caller.

area_ptr            (Input)
          is a pointer to the  area in which this entrypoint will
          allocate the mailbox_acl structure.   If a null pointer
          is  given as  the value  of this  parameter, the system
          free area will be used.

mailbox_acl_version (Input)
          is  the  version  of  the mailbox_acl  structure  to be
          created by this entrypoint.  The only version supported
          at  this  time  is  given by  the  value  of  the named
          constant  MAILBOX_ACL_VERSION_1  in  the  include  file
          mlsys_mailbox_acl.incl.pl1.

mailbox_acl_ptr     (Output)
          is set to locate the mailbox_acl structure allocated by
          this entrypoint.  The mailbox_acl structure and, unless
          stated  otherwise, all  named constants  mentioned here
          are      defined      in      the      include     file
          mlsys_mailbox_acl.incl.pl1:


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

               dcl 1 mailbox_acl   aligned based
                                   (mailbox_acl_ptr),
                     2 header,
                       3 version   character (8) unaligned,
                       3 n_acl_terms
                                   fixed binary,
                       3 pad       bit (36),
                     2 acl_terms   (mailbox_acl_n_acl_terms refer
                                   (mailbox_acl.n_acl_terms)),
                       3 access_name
                                   character (32) unaligned,
                       3 extended_mode
                                   bit (36),
                       3 code      fixed binary (35);

          where:

          version             (Output)
                    is  set  to  the   current  version  of  this
                    structure.   The  version  of  the  structure
                    described here  is given by the  value of the
                    named constant MAILBOX_ACL_VERSION_1.

          n_acl_terms         (Output)
                    is  set  to  the  number  of  entries  in the
                    extended ACL of the mailbox.

          acl_terms           (Output)
                    is set to the extened ACL.

            access_name
                      is     set     to    the     access    name
                      (Person_id.Project_id.tag)   of   this  ACL
                      term.   The  access   name  identifies  the
                      processes to  which this extended  ACL term
                      applies.

            extended_mode
                      is set to the extended access to be granted
                      to  processes  which match  this  ACL term.
                      The possible bits which  may be set in this
                      field are defined by named constants of the
                      form A_MBX_ACCESS which  are defined in the
                      include  file mlsys_mailbox_modes.incl.pl1.

            code      is set to zero.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    The  caller  requested   the  creation  of  a
                    version of the  mailbox_acl structure that is
                    not supported by the mail system.

             ________________________________________

Entry:  mlsys_utils_$parse_address_control_arguments

     This entrypoint converts the control argument representation
of a  single address into  its internal representation.   See the
discussion  of control  argument representations  in Section 1 of
this manual for more information.

USAGE

     dcl  mlsys_utils_$parse_address_control_arguments entry
               (pointer, fixed binary, pointer, pointer,
               fixed binary (35)));

     call mlsys_utils_$parse_address_control_arguments (sci_ptr,
               argument_index, parse_ca_options_ptr, address_ptr,
               code);

ARGUMENTS

sci_ptr             (Input)
          is a  pointer to the subsystem  control structure which
          describes  the  command/active  function  or  subsystem
          request  on  whose  behalf  this  entrypoint  has  been
          invoked.   This pointer  is used by  this entrypoint in
          calls   to   various  entrypoints   of   the  subsystem
          utilities (ssu_).   If the  caller is  a command/active
          function,   it  will   have  to   create  a  standalone
          invocation  in order  to use this  entrypoint.  See the
          description of  interactive subsystems in  Section 4 of
          the    Multics   Programmer's    Reference   for   more
          information.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

argument_index      (Input/Output)
          on  input, is  the index  of the  first command/request
          argument   which  is   believed  to  be   part  of  the
          representation   of  an   address.   On   output,  this
          parameter   is   set  to   the   index  of   the  first
          command/request  argument  after  the  address;  if all
          remaining arguments were used to form the address, this
          parameter will be set to one greater than the number of
          command/request arguments.

parse_ca_options_ptr
                    (Input)
          is  a  pointer  to a  parse_ca_options  structure.  The
          parse_ca_options    structure   and,    unless   stated
          otherwise,  all  named  constants  mentioned  here  are
          defined        in        the        include        file
          mlsys_parse_ca_options.incl.pl1:

               dcl 1 parse_ca_options
                                   aligned based
                                   (parse_ca_options_ptr),
                     2 version     character (8) unaligned,
                     2 logbox_creation_mode
                                   fixed binary,
                     2 savebox_creation_mode
                                   fixed binary,
                     2 flags,
                       3 abort_on_errors
                                   bit (1) unaligned,
                       3 validate_addresses
                                   bit (1) unaligned,
                       3 mbz       bit (34) unaligned;

          where:

          version             (Input)
                    is the current version of the structure.  The
                    version  of the  structure described  here is
                    given  by  the  value of  the  named constant
                    PARSE_CA_OPTIONS_VERSION_1.

          logbox_creation_mode
                              (Input)
                    specifies  the  action  to  be  taken  if the
                    address  identifies  the  user's  logbox, the
                    caller  has  requested  that  the  address be
                    validated,  and  the logbox  does  not exist.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    This   parameter   is   ignored   unless  the
                    validate_addresses  parameter (see  below) is
                    set.  The  possible values of  this parameter
                    are given by the following named constants:

                    DONT_CREATE_MAILBOX
                              specifies   that   this  entrypoint
                              should  not  create the  logbox but
                              should,  instead,  print  an  error
                              message  and consider  this address
                              to be invalid.

                    QUERY_TO_CREATE_MAILBOX
                              specifies   that   this  entrypoint
                              should  query   for  permission  to
                              create  the  logbox.   If  the user
                              does  not  given  permission,  this
                              entrypoint   will    consider   the
                              address to be invalid.

                    CREATE_AND_ANNOUNCE_MAILBOX
                              specifies   that   this  entrypoint
                              should attempt to create the logbox
                              and,   if   successfull,   print  a
                              message announcing this action.

                    SILENTLY_CREATE_MAILBOX
                              specifies   that   this  entrypoint
                              should   attempt   to   create  the
                              logbox.

          savebox_creation_mode
                              (Input)
                    specifies  the  action  to  be  taken  if the
                    address   identifies   one   of   the  user's
                    saveboxes, the caller  has requested that the
                    address  be validated,  and the  savebox does
                    not exist.  This  parameter is ignored unless
                    the validate_address parameter (see below) is
                    set.  The  possible values of  this parameter
                    are  the same  as those  given above  for the
                    logbox_creation_mode parameter.

          flags.abort_on_errors
                              (Input)
                    if  "1"b,  specifies   that  this  entrypoint
                    should     abort     processing     of    the


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    command/request via a call to ssu_$abort_line
                    if  it  detects  any  errors  processing  the
                    control arguments.  If  "0"b, this entrypoint
                    will use ssu_$print_message to report errors.

          flags.validate_addresses
                              (Input)
                    if  "1"b,  specifies   that  this  entrypoint
                    should vaildate the  existence of the address
                    in  addition to  verifying the  syntax of its
                    control argument  representation.  Validation
                    of  an address  is accomplished by  a call to
                    the mail_system_$validate_address entrypoint.
                    If "0"b, this entrypoint will only verify its
                    syntax.

          flags.mbz           (Input)
                    is reserved for future  expansion and must be
                    ""b.

address_ptr         (Output)
          is   set  to   locate  the  address   created  by  this
          entrypoint.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    parse_ca_options   structure   that   is  not
                    supported by the mail system.

          mlsys_et_$ca_parse_failed
                    The   syntax   of    the   control   argument
                    representation  supplied  by the  user  is in
                    error  or the  address constructed  from said
                    representation  is invalid.   In either case,
                    this entrypoint will have already printed the
                    appropriate    error    messages    and   the
                    argument_index parameter  will be set  to the
                    index  of the  first command/request argument
                    of the erroneous representation.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$parse_address_list_control_arguments

     This entrypoint converts the control argument representation
of one  or more addresses into  their internal representation and
adds  these  addresses  to  a  supplied  address  list.   See the
discussion  of control  argument representations  in Section 1 of
this manual for more information.

USAGE

     dcl  mlsys_utils_$parse_address_list_control_arguments entry
               (pointer, fixed binary, pointer, character (8),
               pointer, fixed binary (35)));

     call mlsys_utils_$parse_address_list_control_arguments
               (sci_ptr, argument_index, parse_ca_options_ptr,
               address_list_version, address_list_ptr, code);

ARGUMENTS

sci_ptr             (Input)
          is a  pointer to the subsystem  control structure which
          describes  the  command/active  function  or  subsystem
          request  on  whose  behalf  this  entrypoint  has  been
          invoked.   This pointer  is used by  this entrypoint in
          calls   to   various  entrypoints   of   the  subsystem
          utilities (ssu_).   If the  caller is  a command/active
          function,   it  will   have  to   create  a  standalone
          invocation  in order  to use this  entrypoint.  See the
          description of  interactive subsystems in  Section 4 of
          the    Multics   Programmer's    Reference   for   more
          information.

argument_index      (Input/Output)
          on  input, is  the index  of the  first command/request
          argument  to  be  processed  by  this  entrypoint.   On
          output, this parameter is set to the index of the first
          subsequent command/request  argument which is  not part
          of the  control argument representation  on an address;
          if all remaining arguments were used to form addresses,
          this  parameter  will be  set to  one greater  than the
          number of command/request arguments.

parse_ca_options_ptr
                    (Input)


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          is  a  pointer  to a  parse_ca_options  structure.  The
          parse_ca_options    structure   and,    unless   stated
          otherwise,  all  named  constants  mentioned  here  are
          defined        in        the        include        file
          mlsys_parse_ca_options.incl.pl1:

               dcl 1 parse_ca_options
                                   aligned based
                                   (parse_ca_options_ptr),
                     2 version     character (8) unaligned,
                     2 logbox_creation_mode
                                   fixed binary,
                     2 savebox_creation_mode
                                   fixed binary,
                     2 flags,
                       3 abort_on_errors
                                   bit (1) unaligned,
                       3 validate_addresses
                                   bit (1) unaligned,
                       3 mbz       bit (34) unaligned;

          where:

          version             (Input)
                    is the current version of the structure.  The
                    version  of the  structure described  here is
                    given  by  the  value of  the  named constant
                    PARSE_CA_OPTIONS_VERSION_1.

          logbox_creation_mode
                              (Input)
                    specifies  the  action  to  be  taken  if  an
                    address  identifies  the  user's  logbox, the
                    caller   has  requested   that  addresses  be
                    validated,  and  the logbox  does  not exist.
                    This   parameter   is   ignored   unless  the
                    validate_addresses  parameter (see  below) is
                    set.  The  possible values of  this parameter
                    are given by the following named constants:

                    DONT_CREATE_MAILBOX
                              specifies   that   this  entrypoint
                              should  not  create the  logbox but
                              should,  instead,  print  an  error
                              message  and consider  this address
                              to be invalid.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    QUERY_TO_CREATE_MAILBOX
                              specifies   that   this  entrypoint
                              should  query   for  permission  to
                              create  the  logbox.   If  the user
                              does  not  given  permission,  this
                              entrypoint   will    consider   the
                              address to be invalid.

                    CREATE_AND_ANNOUNCE_MAILBOX
                              specifies   that   this  entrypoint
                              should attempt to create the logbox
                              and,   if   successfull,   print  a
                              message announcing this action.

                    SILENTLY_CREATE_MAILBOX
                              specifies   that   this  entrypoint
                              should   attempt   to   create  the
                              logbox.

          savebox_creation_mode
                              (Input)
                    specifies  the  action  to  be  taken  if  an
                    address   identifies   one   of   the  user's
                    saveboxes,  the  caller  has  requested  that
                    addresses be validated,  and the savebox does
                    not exist.  This  parameter is ignored unless
                    the validate_addresses  parameter (see below)
                    is   set.   The   possible  values   of  this
                    parameter are  the same as  those given above
                    for the logbox_creation_mode parameter.

          flags.abort_on_errors
                              (Input)
                    if  "1"b,  specifies   that  this  entrypoint
                    should     abort     processing     of    the
                    command/request via a call to ssu_$abort_line
                    if  it  detects  any  errors  processing  the
                    control arguments.  If  "0"b, this entrypoint
                    will use ssu_$print_message to report errors.

          flags.validate_addresses
                              (Input)
                    if  "1"b,  specifies   that  this  entrypoint
                    should vaildate the existence of each address
                    in  addition to  verifying the  syntax of its
                    control argument  representation.  Validation
                    of  an address  is accomplished by  a call to


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    the mail_system_$validate_address entrypoint.
                    If "0"b, this entrypoint will only verify the
                    syntax of each address.

          flags.mbz           (Input)
                    is reserved for future  expansion and must be
                    ""b.

address_list_version
                    (Input)
          is  the  version of  the  address_list structure  to be
          created  by  this  entrypoint  if  the address_list_ptr
          parameter  below is  null on  input.  The  only version
          supported  at this  time is given  by the  value of the
          named  constant  ADDRESS_LIST_VERSION_2 in  the include
          file mlsys_address_list.incl.pl1.

address_list_ptr    (Input/Output)
          is a  pointer to an address_list  structure or is null.
          If non-null,  the addresses created  by this entrypoint
          will be added  to the end of this list;  if null, a new
          address_list  will  be created  and the  addresses will
          then be added  to this new list.  In  either case, this
          pointer   will  be   updated  to   locate  the  revised
          address_list structure  and the old  structure, if any,
          will be destroyed.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    Either the  caller supplied a  version of the
                    parse_ca_options   structure   that   is  not
                    supported   by   the  mail   system   or  the
                    address_list_ptr parameter was  null on input
                    and  the caller  requested the  creation of a
                    version of the address_list structure that is
                    not supported by the mail system.

          mlsys_et_$ca_parse_failed
                    Either  a  syntax error  was detected  in the
                    control  argument  representation  of  one or
                    more  addresses or  one or  more addresses is
                    invalid.   In  either  case,  this entrypoint
                    will  have  already  printed  the appropriate


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    error   messages   and   the   argument_index
                    parameter  will be  set to  the index  of the
                    first command/request control argument of the
                    erroneous representation.

NOTES

     This  entrypoint  should  be  used as  a  co-routine  of the
argument  processing   loop  of  a   command/active  function  or
subsystem request  which accepts a list  of addresses in addition
to its own control arguments.

EXAMPLES

     For example,  the following code  sequence may be  used in a
command/active function:

dcl  1 local_pcao aligned like parse_ca_options;

sci_ptr = null ();                      /* for cleanup handler */
on condition (cleanup)
     begin;
          call cleanup_command ("1"b);  /* abnormal termination */
          if sci_ptr ^= null () then call ssu_$destroy_invocation (sci_ptr);
     end;

call ssu_$standalone_invocation (sci_ptr, "sample_command", "1.0",
          cu_$arg_list_ptr (), abort_command, code);

local_pcao.version = PARSE_CA_OPTIONS_VERSION_1;
local_pcao.logbox_creation_mode = CREATE_AND_ANNOUNCE_MAILBOX;
local_pcao.savebox_creation_mode = QUERY_TO_CREATE_MAILBOX;
string (local_pcao.flags) = ""b;
local_pcao.abort_on_errors,             /* let subr stop us on errors */
     local_pcao.validate_addresses = "1"b;   /* insure they're real */

call ssu_$arg_count (sci_ptr, argument_count);
argument_index = 1;

address_list_ptr = null ();             /* let subr create initial list */

do while (argument_index <= argument_count);

     call mlsys_utils_$parse_address_list_control_arguments (sci_ptr,
               argument_index, addr (local_pcao), ARGUMENT_LIST_VERSION_2,


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

               address_list_ptr, code);

     /*** only possible non-zero codes indicate that our local_pcao
          structure is invalid as the above subroutine will abort
          execution of the command/AF if the user made a mistake such as:
               -mailbox -log   (missing pathanme after -mailbox) */
     if code ^= 0 then call ssu_$abort_line (sci_ptr, code);

     if argument_index <= argument_count then do;
          /*** one of our control arguments? */
          call ssu_$arg_ptr (sci_ptr, argument_index, arg_ptr, arg_lth);
          if (argument = "-brief") | (argument = "-bf") then
               brief_sw = "1"b;

          /*** check here for other control arguments */
          else call ssu_$abort_line (sci_ptr, error_table_$badopt,
                         """^a""", argument);

          /*** skip over the argument that we have just processed */
          argument_index = argument_index + 1;
     end;
end;

call ssu_$destroy_invocation (sci_ptr); /* don't need it anymore */

/*** REST OF THE COMMAND/AF */

call cleanup_command ("0"b);            /* successfull execution */

RETURN_FROM_COMMAND:
return;

/*** this procedure is called by ssu_$abort_line after printing the error
     message to abort execution of the command/AF */

abort_command:
procedure ();

          call cleanup_command ("1"b);  /* abnormal termination */
          call ssu_$destroy_invocation (sci_ptr);

          go to RETURN_FROM_COMMAND;

end abort_command;


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$parse_address_list_text

     This entrypoint  converts the printed  representation of one
or more addresses into  their internal representation and creates
an address list containing  these addresses.  See the description
of the  printed representation of addresses  and address lists in
Section 1 of this document for more information.

USAGE

     dcl  mlsys_utils_$parse_address_list_text entry
               (character (*), pointer, character (8), pointer,
               pointer, fixed binary (35));

     call mlsys_utils_$parse_address_list_text
               (address_list_representation,
               parse_text_options_ptr, address_list_version,
               address_list_ptr, parse_text_error_list_ptr,
               code);

ARGUMENTS

address_list_representation
                    (Input)
          is  the character  string which is  the alleged printed
          representation of an address list.

parse_text_options_ptr
                    (Input)
          is a pointer to a parse_text_options structure which is
          defined        in        the        include        file
          mlsys_parse_txt_options.incl.pl1 as follows:

               dcl 1 parse_text_options
                                   aligned based
                                   (parse_text_options_ptr),
                     2 version     character (8) unaligned,
                     2 area_ptr    pointer,
                     2 flags,
                       3 list_errors
                                   bit (1) unaligned,
                       3 validate_addresses
                                   bit (1) unaligned,
                       3 include_invalid_addresses


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                                   bit (1) unaligned,
                       3 mbz       bit (33) unaligned;

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    PARSE_TEXT_OPTIONS_VERSION_1  which  is  also
                    defined      in     the      include     file
                    mlsys_parse_txt_options.incl.pl1.

          area_ptr            (Input)
                    is  a  pointer  to  the  area  in  which this
                    entrypoint       will        allocate       a
                    parse_text_error_list structure  if requested
                    by  the caller.   If this  parameter is null,
                    the  system  free  area will  be  used.  This
                    value  is  ignored   unless  the  list_errors
                    parameter is set.

          flags.list_errors   (Input)
                    if  "1"b,  this   entrypoint  will  create  a
                    parse_text_error_list  structure  which  will
                    provide  detailed information  for all errors
                    detected  while  parsing  or  validating  the
                    address  in  the address  list.  If  "0"b, no
                    parse_text_error_list   structure   will   be
                    created.

          flags.validate_addresses
                              (Input)
                    if  "1"b,  specifies   that  this  entrypoint
                    should vaildate the existence of each address
                    in  addition to  verifying the  syntax of its
                    printed  representation.   Validation  of  an
                    address  is  accomplished  by a  call  to the
                    mail_system_$validate_address entrypoint.  If
                    "0"b,  this entrypoint  will only  verify the
                    syntax of each address.

          flags.include_invalid_addresses
                              (Input)
                    if  "1"b,  this  entrypoint  will  create  an
                    invalid address for each piece of text in the
                    supplied  printed representation  which could


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    not  be  converted   into  an  address.   The
                    invalid address  will be created  in addition
                    to  detailing  the  errors  in  said  text if
                    requested   by   the   list_errors  parameter
                    described  above.   If "0"b,  this entrypoint
                    will not create  invalid addresses unless the
                    supplied  text actually  contains the printed
                    representation   of    an   invalid   address
                    ({invalid STR}).

          flags.mbz           (Input)
                    is reserved for future  expansion and must be
                    ""b.

address_list_version
                    (Input)
          is  the  version of  the  address_list structure  to be
          created by this entrypoint.  The only version supported
          at  this  time  is  given by  the  value  of  the named
          constant  ADDRESS_LIST_VERSION_2  which is  declared in
          the include file mlsys_address_list.incl.pl1.

address_list_ptr    (Output)
          is  set  to locate  the  address list  created  by this
          entrypoint.

parse_text_error_list_ptr
                    (Output)
          is  set to  locate the  parse_text_error_list structure
          created  by this  entrypoint if errors  are detected in
          the  supplied  text  and  the  caller  has  requested a
          detailed  error  list  via  the  list_errors  parameter
          described  above.  The  parse_text_error_list structure
          is      defined      in      the      include      file
          mlsys_parse_txt_options.incl.pl1 as follows:

               dcl 1 parse_text_error_list
                                   aligned based
                                   (parse_text_error_list),
                     2 n_errors    fixed binary,
                     2 errors      (parse_text_error_list_n_errors
                                   refer
                                   (parse_text_error_list.n_errors)),
                       3 text_start
                                   fixed binary (21),
                       3 text_lth  fixed binary (21),
                       3 code      fixed binary (35);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          where:

          n_errors            (Output)
                    is  set to  the number of  errors detected in
                    the supplied printed representation.

          errors              (Output)
                    is  set  to  a detailed  description  of each
                    error.  Each entry in  this array describes a
                    single error in the printed representation.

            text_start
                      is  set  to the  index within  the supplied
                      printed   representation   of   the   first
                      character of a substring which could not be
                      parsed by this entrypoint.

            text_lth  is set to the  number of characters in this
                      substring.

            code      is  set  to a  standard system  status code
                      which  describes  what is  wrong  with this
                      particular   substring   of   the   printed
                      representation.   It  may have  any  of the
                      values        returned        by        the
                      mail_system_$parse_address_text          or
                      mail_system_$validate_address entrypoints.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    Either the  caller supplied a  version of the
                    parse_text_options  structure   that  is  not
                    supported  by the  mail system  or the caller
                    requested  the creation  of a  version of the
                    address_list structure that  is not supported
                    by the mail system.

          mlsys_et_$text_parse_failed
                    One  or  more   errors  were  detected  while
                    parsing the  supplied printed representation.
                    If    requested    by     the    caller,    a
                    parse_text_error_list   structure   will   be


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    created  to  describe  these  errors  in more
                    detail.

             ________________________________________

Entry:  mlsys_utils_$parse_address_text

     This  entrypoint  converts the  printed representation  of a
single  address  into  its   internal  representation.   See  the
description  of  the  printed   representation  of  addresses  in
Section 1 of this document for more information.

USAGE

     dcl  mlsys_utils_$parse_address_text entry (character (*),
               pointer, fixed binary (35));

     call mlsys_utils_$parse_address_text
               (address_representation, address_ptr, code);

ARGUMENTS

address_representation
                    (Input)
          if  the character  string which is  the alleged printed
          representation of an address.

address_ptr         (Output)
          is   set  to   locate  the  address   created  by  this
          entrypoint.

code                (Output)
          is a standard  system status code.  It may  have any of
          the values returned  by the expand_pathname_$add_suffix
          entrypoint as documented in Multics Subroutines and I/O
          Modules.     In  addition,  it  may  have  any  of  the
          following values:

          mlsys_et_$invalid_user_id_syntax
                    The  supplied  text  appears  to  be  a  user
                    mailbox  address however  the User_id  in the
                    text is not properly formatted.  Said User_id
                    contains  whitespace or  angle brackets (<>),
                    does  not  contain  exactly  one  period (.),


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    contains  a Person_id  over 28  characters in
                    length,  or  contains  a  Project_id  over 32
                    characters in length.

          mlsys_et_$invalid_mte_syntax
                    The supplied text appears  to be a mail table
                    address however  the name for  the mail table
                    entry in the text  is not properly formatted.
                    Said  name  is either  over 32  characters in
                    length    or    contains    commas,   colons,
                    semi-colons,   backslashes (),  parentheses,
                    angle brackets (<>), braces ({}), quotes ("),
                    commerical at-signs (@),  or whitespace other
                    than spaces.

          mlsys_et_$unbalanced_parentheses

          mlsys_et_$unbalanced_braces
                              (nospace)

          mlsys_et_$unbalanced_quotes
                              (nospace)
                    The    supplied   text    contains   unpaired
                    parentheses,   braces ({}),   or  quotes ("),
                    respectively.

NOTES

     This  entrypoint create  the address  without verifying that
the  specified  address  actually  exists or  that  the  user has
sufficient     access     to     use     the     address.     The
mail_system_$validate_address entrypoint may be used to determine
whether mail  can indeed be  delivered to the  address created by
this entrypoint.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$parse_mailbox_control_arguments

     This entrypoint converts the control argument representation
of a single mailbox into the pathname of said mailbox.  See below
for   a   description   of   the   acceptable   control  argument
representations of a mailbox.

USAGE

     dcl  mlsys_utils_$parse_mailbox_control_arguments entry
               (pointer, fixed binary, pointer, character (),
               fixed binary (35)));

     call mlsys_utils_$parse_mailbox_control_arguments (sci_ptr,
               argument_index, parse_ca_options_ptr,
               mailbox_pathname, code);

ARGUMENTS

sci_ptr             (Input)
          is a  pointer to the subsystem  control structure which
          describes  the  command/active  function  or  subsystem
          request  on  whose  behalf  this  entrypoint  has  been
          invoked.   This pointer  is used by  this entrypoint in
          calls   to   various  entrypoints   of   the  subsystem
          utilities (ssu_).   If the  caller is  a command/active
          function,   it  will   have  to   create  a  standalone
          invocation  in order  to use this  entrypoint.  See the
          description of  interactive subsystems in  Section 4 of
          the    Multics   Programmer's    Reference   for   more
          information.

argument_index      (Input/Output)
          on  input, is  the index  of the  first command/request
          argument   which  is   believed  to  be   part  of  the
          representation of a mailbox.  On output, this parameter
          is  set  to  the  index  of  the  first command/request
          argument after the mailbox;  if all remaining arguments
          were  used   to  form  the   mailbox's  pathname,  this
          parameter will be set to one greater than the number of
          command/request arguments.

parse_ca_options_ptr
                    (Input)
          is  a  pointer  to a  parse_ca_options  structure.  The


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          parse_ca_options    structure   and,    unless   stated
          otherwise,  all  named  constants  mentioned  here  are
          defined        in        the        include        file
          mlsys_parse_ca_options.incl.pl1:

               dcl 1 parse_ca_options
                                   aligned based
                                   (parse_ca_options_ptr),
                     2 version     character (8) unaligned,
                     2 logbox_creation_mode
                                   fixed binary,
                     2 savebox_creation_mode
                                   fixed binary,
                     2 flags,
                       3 abort_on_errors
                                   bit (1) unaligned,
                       3 validate_addresses
                                   bit (1) unaligned,
                       3 mbz       bit (34) unaligned;

          where:

          version             (Input)
                    is the current version of the structure.  The
                    version  of the  structure described  here is
                    given  by  the  value of  the  named constant
                    PARSE_CA_OPTIONS_VERSION_1.

          logbox_creation_mode
                              (Input)
                    specifies  the  action  to  be  taken  if the
                    mailbox is the user's  logbox, the caller has
                    requested that the  mailbox be validated, and
                    the logbox does not exist.  This parameter is
                    ignored    unless    the   validate_addresses
                    parameter (see  below) is set.   The possible
                    values  of  this parameter  are given  by the
                    following named constants:

                    DONT_CREATE_MAILBOX
                              specifies   that   this  entrypoint
                              should  not  create the  logbox but
                              should,  instead,  print  an  error
                              message  and consider  this mailbox
                              specification to be invalid.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    QUERY_TO_CREATE_MAILBOX
                              specifies   that   this  entrypoint
                              should  query   for  permission  to
                              create  the  logbox.   If  the user
                              does  not  given  permission,  this
                              entrypoint   will    consider   the
                              mailbox    specification    to   be
                              invalid.

                    CREATE_AND_ANNOUNCE_MAILBOX
                              specifies   that   this  entrypoint
                              should attempt to create the logbox
                              and,   if   successfull,   print  a
                              message announcing this action.

                    SILENTLY_CREATE_MAILBOX
                              specifies   that   this  entrypoint
                              should   attempt   to   create  the
                              logbox.

          savebox_creation_mode
                              (Input)
                    specifies  the  action  to  be  taken  if the
                    mailbox is  one of the  user's saveboxes, the
                    caller  has  requested  that  the  mailbox be
                    validated,  and the  savebox does  not exist.
                    This   parameter   is   ignored   unless  the
                    validate_address  parameter  (see  below)  is
                    set.  The  possible values of  this parameter
                    are  the same  as those  given above  for the
                    logbox_creation_mode parameter.

          flags.abort_on_errors
                              (Input)
                    if  "1"b,  specifies   that  this  entrypoint
                    should     abort     processing     of    the
                    command/request via a call to ssu_$abort_line
                    if  it  detects  any  errors  processing  the
                    control arguments.  If  "0"b, this entrypoint
                    will use ssu_$print_message to report errors.

          flags.validate_addresses
                              (Input)
                    if  "1"b,  specifies   that  this  entrypoint
                    should vaildate the  existence of the mailbox
                    in  addition to  verifying the  syntax of its
                    control  argument  representation.   If "0"b,


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    this   entrypoint   will   only   verify  the
                    representation's syntax.

          flags.mbz           (Input)
                    is reserved for future  expansion and must be
                    ""b.

mailbox_pathname    (Output)
          is set to  the pathname of the mailbox  located by this
          entrypoint.  This pathname will include the mbx suffix.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    parse_ca_options   structure   that   is  not
                    supported by the mail system.

          mlsys_et_$ca_parse_failed
                    The   syntax   of    the   control   argument
                    representation  supplied  by the  user  is in
                    error  or  the  mailbox  identified  by  said
                    representation  does  not  exist.   In either
                    case,  this  entrypoint   will  have  already
                    printed  the  appropriate error  messages and
                    the argument_index  parameter will be  set to
                    the   index  of   the  first  command/request
                    argument of the erroneous representation.

CONTROL ARGUMENT REPRESENTATIONS OF A MAILBOX

     The  control  argument representation  of  a mailbox  is the
sequence of command/request line  arguments and control arguments
recognized by the mail system in order to allow a user to specify
the pathname of one or more mailboxes on a command/request line:

     The control argument sequences recognized by the mail system
are:

-user STR specifies either  a user's default mailbox  or an entry
          in the system mail table.   If STR contains exactly one
          period  and  no  whitespace,  it  is  interpreted  as a
          User_id  which  specifies  a  user's  default  mailbox;


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          otherwise, it is interpreted as the name of an entry in
          the mail table.  When interpreted as a User_id, STR may
          not contain  any angle brackets (<>) and  must have the
          form  Person_id.Project_id  where   Person_id  may  not
          exceed 28  characters in length and  Project_id may not
          exceed  32 characters  in length.   In this  case, this
          control argument is equivalent to:
               -mailbox >udd>Project_id>Person_id>Person_id.mbx
          When interpreted as the name of a mail table entry, STR
          may  not  contain   any  commas,  colons,  semi-colons,
          backslashes (),   parentheses,   angle  brackets (<>),
          braces ({}),  quotes ("),  commerical  at-signs (@), or
          whitespace  other than  spaces.  The query  of the mail
          table is  performed in a case  insensitive manner.  The
          display_mailing_address   command   may   be   used  to
          determine the actual address  corresponding to the STR.
           The address in the mail table must identify a mailbox.

-log      specifies the user's logbox and is equivalent to:
               -mailbox >udd>Project_id>Person_id>Person_id.sv.mbx

-save path, -sv path
          specifies the pathname of a savebox.  The suffix sv.mbx
          is added if necessary.

-mailbox path, -mbx path
          specifies the pathname of a mailbox.  The suffix mbx is
          added if necessary.

STR       is  any   non-control  argument  interpreted   by  this
          entrypoint.  This argument is first interpreted as
               -mailbox STR
          If  no   mailbox  is  found,  this   argument  is  then
          interpreted as
               -save STR If no savebox is found, this argument is
          then interpreted as
               -user STR


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$parse_message_text

     This entrypoint converts the printed representation of a new
message into its internal representation.  See the description of
the  printed  representation  of  messages in  Section 1  of this
document for more information.

USAGE

     dcl  mlsys_utils_$parse_message_text entry (character (*),
               pointer, character (8), pointer, pointer,
               fixed binary (35));

     call mlsys_utils_$parse_message_text
               (message_representation, parse_text_options_ptr,
               message_version, message_ptr,
               parse_text_error_list_ptr, code);

ARGUMENTS

message_representation
                    (Input)
          is  the character  string which is  the alleged printed
          representation of a new message.

parse_text_options_ptr
                    (Input)
          is a pointer to a parse_text_options structure which is
          defined        in        the        include        file
          mlsys_parse_txt_options.incl.pl1 as follows:

               dcl 1 parse_text_options
                                   aligned based
                                   (parse_text_options_ptr),
                     2 version     character (8) unaligned,
                     2 area_ptr    pointer,
                     2 flags,
                       3 list_errors
                                   bit (1) unaligned,
                       3 validate_addresses
                                   bit (1) unaligned,
                       3 include_invalid_addresses
                                   bit (1) unaligned,
                       3 mbz       bit (33) unaligned;


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    PARSE_TEXT_OPTIONS_VERSION_1  which  is  also
                    defined      in     the      include     file
                    mlsys_parse_txt_options.incl.pl1.

          area_ptr            (Input)
                    is  a  pointer  to  the  area  in  which this
                    entrypoint       will        allocate       a
                    parse_text_error_list structure  if requested
                    by  the caller.   If this  parameter is null,
                    the  system  free  area will  be  used.  This
                    value  is  ignored   unless  the  list_errors
                    parameter is set.

          flags.list_errors   (Input)
                    if  "1"b,  this   entrypoint  will  create  a
                    parse_text_error_list  structure  which  will
                    provide  detailed information  for all errors
                    detected while parsing  the representation of
                    the  message or  validating the  addresses in
                    the    message    header.    If    "0"b,   no
                    parse_text_error_list   structure   will   be
                    created.

          flags.validate_addresses
                              (Input)
                    if  "1"b,  specifies   that  this  entrypoint
                    should vaildate the existence of each address
                    in   the  message   header  in   addition  to
                    verifying   the   syntax   of   its   printed
                    representation.  Validation of  an address is
                    accomplished    by    a     call    to    the
                    mail_system_$validate_address entrypoint.  If
                    "0"b,  this entrypoint  will only  verify the
                    syntax of the addresses in the header.

          flags.include_invalid_addresses
                              (Input)
                    if  "1"b,  this  entrypoint  will  create  an
                    invalid address for each piece of text in the
                    supplied  printed representation  which could
                    not  be  converted   into  an  address.   The


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    invalid address  will be created  in addition
                    to  detailing  the  errors  in  said  text if
                    requested   by   the   list_errors  parameter
                    described  above.   If "0"b,  this entrypoint
                    will not create  invalid addresses unless the
                    supplied  text actually  contains the printed
                    representation   of    an   invalid   address
                    ({invalid STR}).

          flags.mbz           (Input)
                    is reserved for future  expansion and must be
                    ""b.

message_version     (Input)
          is the  version of the message  structure to be created
          by this entrypoint.  The only version supported at this
          time  is  given  by  the value  of  the  named constant
          MESSAGE_VERSION_2 which is declared in the include file
          mlsys_message.incl.pl1.

message_ptr         (Output)
          is   set  to   locate  the  message   created  by  this
          entrypoint.

parse_text_error_list_ptr
                    (Output)
          is  set to  locate the  parse_text_error_list structure
          created  by this  entrypoint if errors  are detected in
          the  supplied  text  and  the  caller  has  requested a
          detailed  error  list  via  the  list_errors  parameter
          described  above.  The  parse_text_error_list structure
          is      defined      in      the      include      file
          mlsys_parse_txt_options.incl.pl1 as follows:

               dcl 1 parse_text_error_list
                                   aligned based
                                   (parse_text_error_list),
                     2 n_errors    fixed binary,
                     2 errors      (parse_text_error_list_n_errors
                                   refer
                                   (parse_text_error_list.n_errors)),
                       3 text_start
                                   fixed binary (21),
                       3 text_lth  fixed binary (21),
                       3 code      fixed binary (35);

          where:


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          n_errors            (Output)
                    is  set to  the number of  errors detected in
                    the supplied printed representation.

          errors              (Output)
                    is  set  to  a detailed  description  of each
                    error.  Each entry in  this array describes a
                    single error in the printed representation.

            text_start
                      is  set  to the  index within  the supplied
                      printed   representation   of   the   first
                      character of a substring which could not be
                      parsed by this entrypoint.

            text_lth  is set to the  number of characters in this
                      substring.

            code      is  set  to a  standard system  status code
                      which  describes  what is  wrong  with this
                      particular   substring   of   the   printed
                      representation.   It  may have  any  of the
                      values        returned        by        the
                      mail_system_$parse_address_text          or
                      mail_system_$validate_address  entrypoints.
                      In  addition,  it  may   have  one  of  the
                      following values:

                      mlsys_et_$in_mailbox_only_field
                                This  substring  is  the  printed
                                representation   of   a   message
                                header   field  which   may  only
                                appear  in an  in-mailbox message
                                (eg:   Message-ID, Access-Class).
                                This status code is also returned
                                for  any  substring which  is the
                                printed   representation   of   a
                                message        envelope        or
                                redistributions list field.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    Either the  caller supplied a  version of the


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                    parse_text_options  structure   that  is  not
                    supported  by the  mail system  or the caller
                    requested  the creation  of a  version of the
                    message  structure that  is not  supported by
                    the mail system.

          mlsys_et_$text_parse_failed
                    One  or  more   errors  were  detected  while
                    parsing the  supplied printed representation.
                    If    requested    by     the    caller,    a
                    parse_text_error_list   structure   will   be
                    created  to  describe  these  errors  in more
                    detail.

NOTES

     Any fields present in  this printed representation which are
only valid for in-mailbox messages  are flagged as errors by this
entrypoint.  These  fields are the  Message-ID, Access-Class, and
Date fields of  the message header and any  fields in the message
envelope or redistributions list.

     The  message body  created by  this entrypoint  will contain
exactly  one preformatted  section.  The content  of this section
will be  all of the  text in the  supplied printed representation
which is part of the message  body.  (Ie:  all text which appears
after the  first blank line  in the supplied  text.)  The message
body  will  not  be  broken  into  individual  sections  by  this
entrypoint.

             ________________________________________

Entry:  mlsys_utils_$print_access_class_field

     This  entrypoint  displays the  printed representation  of a
message   envelope,   header,  or   redistributions   list  field
containing an AIM access class value on the specified I/O switch.
See the description of the  printed representation of messages in
Section 1 of this document for more information.

USAGE

     dcl  mlsys_utils_$print_access_class_field entry
               (character (*) varying, bit (72) aligned,


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

               fixed binary, pointer, fixed binary (35));

     call mlsys_utils_$print_access_class_field (field_name,
               access_class, line_length, output_switch, code);

ARGUMENTS

field_name          (Input)
          is the  name of this  field.  The field's  name and its
          value will be separated by the string ":  ".  The names
          of the standard fields supported by the mail system are
          available as  the values of the  named constants in the
          include file mlsys_field_names.incl.pl1.

access_class        (Input)
          is the access class which is the value of this field.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of this field.  This parameter must have
          a value greater than 20 or  equal to -1.  A value of -1
          specifies that this entryoint is to use the line length
          of  the  output switch  as  the maximum  width  for its
          output.

output_switch       (Input)
          is  a pointer  to the IOCB  defining the  I/O switch on
          which  the printed  representation is  to be displayed.
          If this  parameter is null,  the printed representation
          will be displayed on the user_output I/O switch.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$print_address_field

     This  entrypoint  displays the  printed representation  of a
message   envelope,   header,  or   redistributions   list  field
containing a single address on the specified I/O switch.  See the
description  of  the  printed  representation  of  addresses  and
messages in Section 1 of this document for more information.

USAGE

     dcl  mlsys_utils_$print_address_field entry
               (character (*) varying, pointer, fixed binary,
               pointer, fixed binary (35));

     call mlsys_utils_$print_address_field (field_name,
               address_ptr, line_length, output_switch, code);

ARGUMENTS

field_name          (Input)
          is the  name of this  field.  The field's  name and its
          value will be separated by the string ":  ".  The names
          of the standard fields supported by the mail system are
          available as  the values of the  named constants in the
          include file mlsys_field_names.incl.pl1.

address_ptr         (Input)
          is a pointer to the address  which is the value of this
          field.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of this field.  This parameter must have
          a value greater than 20 or  equal to -1.  A value of -1
          specifies that this entryoint is to use the line length
          of  the  output switch  as  the maximum  width  for its
          output.

output_switch       (Input)
          is  a pointer  to the IOCB  defining the  I/O switch on
          which  the printed  representation is  to be displayed.
          If this  parameter is null,  the printed representation
          will be displayed on the user_output I/O switch.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address
                    The   storage  identified   by  the  supplied
                    address_ptr is not an address.

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

             ________________________________________

Entry:  mlsys_utils_$print_address_list_field

     This  entrypoint  displays the  printed representation  of a
message   envelope,   header,  or   redistributions   list  field
containing an address list on  the specified I/O switch.  See the
description  of the  printed representation of  address lists and
messages in Section 1 of this document for more information.

USAGE

     dcl  mlsys_utils_$print_address_list_field entry
               (character (*) varying, pointer, fixed binary,
               pointer, fixed binary (35));

     call mlsys_utils_$print_address_list_field (field_name,
               address_list_ptr, line_length, output_switch,
               code);

ARGUMENTS

field_name          (Input)
          is the  name of this  field.  The field's  name and its
          value will be separated by the string ":  ".  The names
          of the standard fields supported by the mail system are
          available as  the values of the  named constants in the
          include file mlsys_field_names.incl.pl1.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

address_list_ptr    (Input)
          is a pointer to the address_list structure which is the
          value of this field.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of this field.  This parameter must have
          a value greater than 20 or  equal to -1.  A value of -1
          specifies that this entryoint is to use the line length
          of  the  output switch  as  the maximum  width  for its
          output.

output_switch       (Input)
          is  a pointer  to the IOCB  defining the  I/O switch on
          which  the printed  representation is  to be displayed.
          If this  parameter is null,  the printed representation
          will be displayed on the user_output I/O switch.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address_list
                    The   storage  identified   by  the  supplied
                    address_list_ptr is not an address list.

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

             ________________________________________

Entry:  mlsys_utils_$print_body_section

     This  entrypoint  displays the  printed representation  of a
section  of the  body of a  message on the  specified I/O switch.
See the description of the  printed representation of messages in
Section 1 of this document for more information.

USAGE

     dcl  mlsys_utils_$print_body_section entry (pointer,
               fixed binary, pointer, fixed binary (35));


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

     call mlsys_utils_$print_body_section
               (message_body_section_parameter_ptr, line_length,
               output_switch, code);

ARGUMENTS

message_body_section_parameter_ptr
                    (Input)
          is   a  pointer   to  a  message_body_section_parameter
          structure.  This structure, which describes the section
          that will  be printed, is  defined in the  include file
          mlsys_message.incl.pl1 as follows:

               dcl 1 message_body_section_parameter
                                   aligned based
                                   (message_body_section_parameter_ptr),
                     2 version     character (8) unaligned,
                     2 section     like message_body_section;

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    MESSAGE_BODY_SECTION_PARAMETER_VERSION_2.

          section             (Input/Output)
                    is   the   section   to   be   printed.   The
                    section_n_lines field in  this structure will
                    be set to the number  of lines in the section
                    after formatting.  See the description of the
                    message_body_section  structure  in Section 1
                    of this  document for a  detailed explanation
                    of the contents of this structure.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation  of   this  section  if  it   is  not  a
          preformatted section.  This parameter must have a value
          greater  than  20  or  equal  to  -1.   A  value  of -1
          specifies that this entryoint is to use the line length
          of  the  output switch  as  the maximum  width  for its
          output.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

output_switch       (Input)
          is  a pointer  to the IOCB  defining the  I/O switch on
          which  the printed  representation is  to be displayed.
          If this  parameter is null,  the printed representation
          will be displayed on the user_output I/O switch.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    message_body_section_parameter structure that
                    is not supported by the mail system.

          error_table_$unknown_body_section
                    The type of message body section specified is
                    not recognized by the mail system.

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

NOTES

     This  entrypoint  does  not   print  the  blank  line  which
separates  the  sections  of  a  message  body.   The  caller  is
responsible for printing said blank lines where appropriate.

             ________________________________________

Entry:  mlsys_utils_$print_date_time_field

     This  entrypoint  displays the  printed representation  of a
message  envelope,  header, or  redistributions list  field whose
value  is  a  date/time on  the  specified I/O  switch.   See the
description  of   the  printed  representation   of  messages  in
Section 1 of this document for more information.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

USAGE

     dcl  mlsys_utils_$print_date_time_field entry
               (character (*) varying, fixed binary (71),
               bit (1) aligned, fixed binary, pointer,
               fixed binary (35));

     call mlsys_utils_$print_date_time_field (field_name,
               date_time, include_dow, line_length,
               output_switch, code);

ARGUMENTS

field_name          (Input)
          is the  name of this  field.  The field's  name and its
          value will be separated by the string ":  ".  The names
          of the standard fields supported by the mail system are
          available as  the values of the  named constants in the
          include file mlsys_field_names.incl.pl1.

date_time           (Input)
          is  a  standard  Multics clock  value  representing the
          date/time which is the value of this field.

include_dow         (Input)
          if "1"b, the name of  the day of the week corresponding
          to  the supplied  date/time will be  printed.  If "0"b,
          the day of the week will not be printed.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of this field.  This parameter must have
          a value greater than 20 or  equal to -1.  A value of -1
          specifies that this entryoint is to use the line length
          of  the  output switch  as  the maximum  width  for its
          output.

output_switch       (Input)
          is  a pointer  to the IOCB  defining the  I/O switch on
          which  the printed  representation is  to be displayed.
          If this  parameter is null,  the printed representation
          will be displayed on the user_output I/O switch.

code                (Output)
          is a standard system status code.  Amongst the possible


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

             ________________________________________

Entry:  mlsys_utils_$print_delivery_results

     This   entrypoint  displays   the  results  of   a  call  to
mail_system_$deliver_message or mail_system_$redistribute_message
in a compact, easy-to-read format.

USAGE

     dcl  mlsys_utils_$print_delivery_results entry (pointer,
               bit (1) aligned, pointer, fixed binary (35));

     call mlsys_utils_$print_delivery_results (sci_ptr,
               errors_only, recipients_info_ptr, code);

ARGUMENTS

sci_ptr             (Input)
          is a  pointer to the subsystem  control structure which
          describes  the  command/active  function  or  subsystem
          request  on  whose  behalf  this  entrypoint  has  been
          invoked.   This pointer  is used by  this entrypoint in
          calls  to  ssu_$print_message.   If  the  caller  is  a
          command/active  function,  it  will  have  to  create a
          standalone invocation in order  to use this entrypoint.
          See  the  description   of  interactive  subsystems  in
          Section 4  of  the Multics  Programmer's  Reference for
          more information.

errors_only         (Input)
          if  "1"b,  this  entrypoint  will  only  print messages
          describing  fatal or  transient errors  detected by the
          call      to       mail_system_$deliver_message      or
          mail_system_$redistribute_message.    If   "0"b,   this
          entrypoint  will print  messages describing successfull


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          delivery  or  queuing in  addition to  those describing
          fatal or transient errors.

recipients_info_ptr (Input)
          is a pointer to  the recipients_info structure that was
          used in the prior call to mail_system_$delivery_message
          or    mail_system_$redistribute_message.     See    the
          description   of  mail_system_$deliver_message   for  a
          detailed explanation of this structure.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    recipients_info   structure   that   is   not
                    supported by the mail system.

NOTES

     The caller is responsible for interpreting the global status
code     returned      by     mail_system_$deliver_message     or
mail_system_$redistribute_message.     The    caller    is   also
responsible for aborting execution of the command/active function
or subsystem request if appropriate.

     Messages describing fatal or transient errors are printed by
calling  ssu_$print_message.    Messages  describing  successfull
delivery or queueing are printed on the user_output I/O switch by
calling ioa_.

EXAMPLES

     An example of the output from this subroutine is

     Mail delivered to Palter.Multics, your logbox, and GMP at MIT-MC.
     Mail not delivered to all addresses in the mailing list >udd>m>gmp>mail_project:
         You are not a participant of the forum >udd>m>gmp>meetings>Mail_System.
     Mail queued for MRC at SU-SCORE and Header-People at MIT-MC.
     Mail queued for Sibert.SiteSA because of record quota overflow.

     If  the  errors_only parameter  had been  set for  the above
example, this entrypoint would only print the messages related to


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

errors  in  the  >udd>m>gmp>mail_project  mailing  list  and  the
message   explaining  why   the  mail   had  to   be  queued  for
Sibert.SiteSA.

             ________________________________________

Entry:  mlsys_utils_$print_message

     This  entrypoint  displays the  printed representation  of a
message on the specified I/O  switch.  See the description of the
printed representation of messages  in Section 1 of this document
for more information.

USAGE

     dcl  mlsys_utils_$print_message entry (pointer, pointer,
               pointer, fixed binary (35));

     call mlsys_utils_$print_message (message_ptr,
               format_message_options_ptr, output_switch, code);

ARGUMENTS

message_ptr         (Input)
          is a pointer to the message to be displayed.

format_message_options_ptr
                    (Input)
          is  a  pointer to  a  format_message_options structure.
          This structure and, unless  stated otherwise, all named
          constants  mentioned  here are  defined in  the include
          file mlsys_format_options.incl.pl1:

               dcl 1 format_message_options
                                   aligned based
                                   (format_message_options_ptr),
                     2 version     character (8) unaligned,
                     2 line_length fixed binary,
                     2 envelope_formatting_mode
                                   fixed binary,
                     2 header_formatting_mode
                                   fixed binary,
                     2 redistributions_list_formatting_mode
                                   fixed binary,


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                     2 include_body
                                   bit (1) aligned;

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    FORMAT_MESSAGE_OPTIONS_VERSION_1.

          line_length         (Input)
                    is  the  maximum width  for  any line  in the
                    printed   representation  of   the  envelope,
                    header,  and  redistributions  list  of  this
                    message.   This parameter  must have  a value
                    greater than  20 or equal to  -1.  A value of
                    -1  specifies that  this entryoint  is to use
                    the line  length of the output  switch as the
                    maximum width for its output.

          envelope_formatting_mode
                              (Input)
          header_formatting_mode
                              (Input)
          redistributions_list_formatting_mode
                              (Input)
                    specify  the  level   of  information  to  be
                    displayed  for the  message envelope, header,
                    and redistributions  list, respectively.  The
                    possible values for these fields are given by
                    the following named constants:

                    LONG_FORMATTING_MODE
                              specifies  that  the  long  form of
                              this part  of the message  is to be
                              displayed.

                    DEFAULT_FORMATTING_MODE
                              specifies that the  default form of
                              this part  of the message  is to be
                              displayed.

                    BRIEF_FORMATTING_MODE
                              specifies  that  the brief  form of
                              this part  of the message  is to be
                              displayed.   This  value  is  not a


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                              valid      choice      for      the
                              envelope_formatting_mode parameter.

                    NONE_FORMATTING_MODE
                              specifies  that  this  part  of the
                              message is not to be displayed.

          include_body        (Input)
                    if   "1"b,   specifies   that   the   printed
                    representation of  the message body  is to be
                    displayed.  If "0"b, the  message body is not
                    displayed.

output_switch       (Input)
          is  a pointer  to the IOCB  defining the  I/O switch on
          which  the printed  representation is  to be displayed.
          If this  parameter is null,  the printed representation
          will be displayed on the user_output I/O switch.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    format_message_options structure  that is not
                    supported by the mail system.

          error_table_$bad_subr_arg
                    Either  the caller  supplied a  value for the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1 or the caller
                    supplied  a value  for one  of the formatting
                    modes  that  is  not  supported  by  the mail
                    system.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$print_message_body

     This entrypoint  displays the printed  representation of the
body of the  given message on the specified  I/O switch.  See the
description  of   the  printed  representation   of  messages  in
Section 1 of this document for more information.

USAGE

     dcl  mlsys_utils_$print_message_body entry (pointer,
               fixed binary, pointer, fixed binary (35));

     call mlsys_utils_$print_message_body (message_ptr,
               line_length, output_switch, code);

ARGUMENTS

message_ptr         (Input)
          is  a  pointer  to  the message  whose  body  is  to be
          displayed.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of  the message body  for those sections
          of the body which  are not preformatted sections.  This
          parameter must have a value greater than 20 or equal to
          -1.  A value of -1  specifies that this entryoint is to
          use the line length of the output switch as the maximum
          width for its output.

output_switch       (Input)
          is  a pointer  to the IOCB  defining the  I/O switch on
          which  the printed  representation is  to be displayed.
          If this  parameter is null,  the printed representation
          will be displayed on the user_output I/O switch.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

             ________________________________________

Entry:  mlsys_utils_$print_message_envelope

     This entrypoint  displays the printed  representation of the
envelope  of the  supplied message  on the  specified I/O switch.
See the description of the  printed representation of messages in
Section 1 of this document for more information.

USAGE

     dcl  mlsys_utils_$print_message_envelope entry (pointer,
               fixed binary, fixed binary, pointer,
               fixed binary (35));

     call mlsys_utils_$print_message_envelope (message_ptr,
               line_length, formatting_mode, output_switch,
               code);

ARGUMENTS

message_ptr         (Input)
          is  a pointer  to the message  whose envelope  is to be
          displayed.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of  the envelope of  this message.  This
          parameter must have a value greater than 20 or equal to
          -1.  A value of -1  specifies that this entryoint is to
          use the line length of the output switch as the maximum
          width for its output.

formatting_mode     (Input)
          specifies the level of  information to be displayed for
          the envelope of this  message.  The possible values for
          this  parameter  are  given   by  the  following  named
          constants  which  are  defined   in  the  include  file
          mlsys_format_options.incl.pl1:


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          LONG_FORMATTING_MODE
                    specifies that the long  form of the envelope
                    is to be displayed.

          DEFAULT_FORMATTING_MODE
                    specifies  that  the   default  form  of  the
                    envelope is to be displayed.

output_switch       (Input)
          is  a pointer  to the IOCB  defining the  I/O switch on
          which  the printed  representation is  to be displayed.
          If this  parameter is null,  the printed representation
          will be displayed on the user_output I/O switch.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          error_table_$bad_subr_arg
                    Either  the caller  supplied a  value for the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1 or the caller
                    supplied  a  value  for  the  formatting_mode
                    parameter that  is not supported  by the mail
                    system.

             ________________________________________

Entry:  mlsys_utils_$print_message_header

     This entrypoint  displays the printed  representation of the
header of the supplied message  on the specified I/O switch.  See
the  description  of the  printed  representation of  messages in
Section 1 of this document for more information.

USAGE

     dcl  mlsys_utils_$print_message_header entry (pointer,
               fixed binary, fixed binary, pointer,
               fixed binary (35));


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

     call mlsys_utils_$print_message_header (message_ptr,
               line_length, formatting_mode, output_switch,
               code);

ARGUMENTS

message_ptr         (Input)
          is  a  pointer to  the  message whose  header is  to be
          displayed.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation  of  the header  of this  message.  This
          parameter must have a value greater than 20 or equal to
          -1.  A value of -1  specifies that this entryoint is to
          use the line length of the output switch as the maximum
          width for its output.

formatting_mode     (Input)
          specifies the level of  information to be displayed for
          the  header of  this message.  The  possible values for
          this  parameter  are  given   by  the  following  named
          constants  which  are  defined   in  the  include  file
          mlsys_format_options.incl.pl1:

          LONG_FORMATTING_MODE
                    specifies that the long form of the header is
                    to be displayed.

          DEFAULT_FORMATTING_MODE
                    specifies that the default form of the header
                    is to be displayed.

          DEFAULT_FORMATTING_MODE
                    specifies that  the brief form  of the header
                    is to be displayed.

output_switch       (Input)
          is  a pointer  to the IOCB  defining the  I/O switch on
          which  the printed  representation is  to be displayed.
          If this  parameter is null,  the printed representation
          will be displayed on the user_output I/O switch.

code                (Output)
          is a standard system status code.  Amongst the possible


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          error_table_$bad_subr_arg
                    Either  the caller  supplied a  value for the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1 or the caller
                    supplied  a  value  for  the  formatting_mode
                    parameter that  is not supported  by the mail
                    system.

             ________________________________________

Entry:  mlsys_utils_$print_message_id_field

     This  entrypoint  displays the  printed representation  of a
message  envelope,  header, or  redistributions list  field whose
value is  a unique identifier  on the specified  I/O switch.  See
the  description  of the  printed  representation of  messages in
Section 1 of this document for more information.

USAGE

     dcl  mlsys_utils_$print_message_id_field entry
               (character (*) varying, bit (72) aligned,
               fixed binary, pointer, fixed binary (35));

     call mlsys_utils_$print_message_id_field (field_name,
               unique_id, line_length, output_switch, code);

ARGUMENTS

field_name          (Input)
          is the  name of this  field.  The field's  name and its
          value will be separated by the string ":  ".  The names
          of the standard fields supported by the mail system are
          available as  the values of the  named constants in the
          include file mlsys_field_names.incl.pl1.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

unique_id           (Input)
          is  the unique  identifier which  is the  value of this
          field.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of this field.  This parameter must have
          a value greater than 20 or  equal to -1.  A value of -1
          specifies that this entryoint is to use the line length
          of  the  output switch  as  the maximum  width  for its
          output.

output_switch       (Input)
          is  a pointer  to the IOCB  defining the  I/O switch on
          which  the printed  representation is  to be displayed.
          If this  parameter is null,  the printed representation
          will be displayed on the user_output I/O switch.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

             ________________________________________

Entry:  mlsys_utils_$print_message_redistributions_list

     This entrypoint  displays the printed  representation of the
redistributions list of the supplied message on the specified I/O
switch.   See the  description of  the printed  representation of
messages in Section 1 of this document for more information.

USAGE

     dcl  mlsys_utils_$print_message_redistributions_list entry
               (pointer, fixed binary, fixed binary, pointer,
               fixed binary (35));

     call mlsys_utils_$print_message_redistributions_list


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

               (message_ptr, line_length, formatting_mode,
               output_switch, code);

ARGUMENTS

message_ptr         (Input)
          is a pointer to  the message whose redistributions list
          is to be displayed.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation  of  the  redistributions  list  of this
          message.  This parameter must have a value greater than
          20 or equal  to -1.  A value of  -1 specifies that this
          entryoint  is  to use  the  line length  of  the output
          switch as the maximum width for its output.

formatting_mode     (Input)
          specifies the level of  information to be displayed for
          the redistributions list of this message.  The possible
          values  for this  parameter are given  by the following
          named constants  which are defined in  the include file
          mlsys_format_options.incl.pl1:

          LONG_FORMATTING_MODE
                    specifies   that   the  long   form   of  the
                    redistributions list is to be displayed.

          DEFAULT_FORMATTING_MODE
                    specifies  that  the   default  form  of  the
                    redistributions list is to be displayed.

          DEFAULT_FORMATTING_MODE
                    specifies   that  the   brief  form   of  the
                    redistributions list is to be displayed.

output_switch       (Input)
          is  a pointer  to the IOCB  defining the  I/O switch on
          which  the printed  representation is  to be displayed.
          If this  parameter is null,  the printed representation
          will be displayed on the user_output I/O switch.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          error_table_$bad_subr_arg
                    Either  the caller  supplied a  value for the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1 or the caller
                    supplied  a  value  for  the  formatting_mode
                    parameter that  is not supported  by the mail
                    system.

             ________________________________________

Entry:  mlsys_utils_$print_message_references_list

     This  entrypoint  displays the  printed representation  of a
message  envelope,  header, or  redistributions list  field whose
value is a list of references  to other messages on the specified
I/O switch.  See the description of the printed representation of
messages in Section 1 of this document for more information.

USAGE

     dcl  mlsys_utils_$print_message_references_list entry
               (character (*) varying, pointer, fixed binary,
               pointer, fixed binary (35));

     call mlsys_utils_$print_message_references_list (field_name,
               message_references_list_ptr, line_length,
               output_switch, code);

ARGUMENTS

field_name          (Input)
          is the  name of this  field.  The field's  name and its
          value will be separated by the string ":  ".  The names
          of the standard fields supported by the mail system are
          available as  the values of the  named constants in the
          include file mlsys_field_names.incl.pl1.

message_references_list_ptr
                    (Input)
          is a  pointer to the  message_references_list structure


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          which  is the  value of  this field.   See Section 1 of
          this document for a description of the contents of this
          structure.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of this field.  This parameter must have
          a value greater than 20 or  equal to -1.  A value of -1
          specifies that this entryoint is to use the line length
          of  the  output switch  as  the maximum  width  for its
          output.

output_switch       (Input)
          is  a pointer  to the IOCB  defining the  I/O switch on
          which  the printed  representation is  to be displayed.
          If this  parameter is null,  the printed representation
          will be displayed on the user_output I/O switch.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    message_references_list structure that is not
                    supported by the mail system.

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

             ________________________________________

Entry:  mlsys_utils_$print_message_trace

     This  entrypoint  displays the  printed representation  of a
message trace onto the specified I/O switch.  See the description
of the  printed representation of  messages in Section 1  of this
document for more information.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

USAGE

     dcl  mlsys_utils_$print_message_trace entry (pointer,
               bit (1) aligned, fixed binary, pointer,
               fixed binary (35));

     call mlsys_utils_$print_message_trace (message_trace_ptr,
               print_redistribution_trace, line_length,
               output_switch, code);

ARGUMENTS

message_trace_ptr   (Input)
          is  a  pointer  to  the  message_trace  structure which
          defines  the  message  trace  to  be  displayed.   This
          structure    is   defined    in   the    include   file
          mlsys_message.incl.pl1  and is  described in  detail in
          Section 1 of this document.

print_redistribution_trace
                    (Input)
          specifies  whether  this  message  trace is  part  of a
          message  envelope  or  a  redistribution  envelope.  If
          "1"b,  the trace  is part of  a redistribution envelope
          and  this entrypoint  will display the  trace using the
          field        names        Redistributed-Route       and
          Redistributed-Relayed.   If "0"b,  the trace is part of
          a message envelope and this entrypoint will display the
          trace using the field names Route and Relayed.

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of  this message trace.   This parameter
          must have  a value greater  than 20 or equal  to -1.  A
          value of  -1 specifies that  this entrypoint is  to use
          the  line length  of the  output switch  as the maximum
          width for its output.

output_switch       (Input)
          is  a pointer  to the IOCB  defining the  I/O switch on
          which  the printed  representation is  to be displayed.
          If this  parameter is null,  the printed representation
          will be displayed on the user_output I/O switch.

code                (Output)
          is a standard system status code.  Amongst the possible


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message_trace
                    The   storage  identified   by  the  supplied
                    message_trace_ptr is not a message trace.

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

             ________________________________________

Entry:  mlsys_utils_$print_text_field

     This  entrypoint  displays the  printed representation  of a
message  envelope,  header, or  redistributions list  field whose
value  is a  text string  on the  specified I/O  switch.  See the
description  of   the  printed  representation   of  messages  in
Section 1 of this document for more information.

USAGE

     dcl  mlsys_utils_$print_text_field entry
               (character (*) varying, character (*),
               fixed binary, pointer, fixed binary (35));

     call mlsys_utils_$print_text_field (field_name, field_text,
               line_length, output_switch, code);

ARGUMENTS

field_name          (Input)
          is the  name of this  field.  The field's  name and its
          value will be separated by the string ":  ".  The names
          of the standard fields supported by the mail system are
          available as  the values of the  named constants in the
          include file mlsys_field_names.incl.pl1.

field_text          (Input)
          is the text string which is the value of this field.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

line_length         (Input)
          is  the  maximum  width  for any  line  in  the printed
          representation of this field.  This parameter must have
          a value greater than 20 or  equal to -1.  A value of -1
          specifies that this entryoint is to use the line length
          of  the  output switch  as  the maximum  width  for its
          output.

output_switch       (Input)
          is  a pointer  to the IOCB  defining the  I/O switch on
          which  the printed  representation is  to be displayed.
          If this  parameter is null,  the printed representation
          will be displayed on the user_output I/O switch.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$bad_subr_arg
                    The   caller   supplied  a   value   for  the
                    line_length   parameter   which   is  neither
                    greater than 20 nor equal to -1.

             ________________________________________

Entry:  mlsys_utils_$replace_mailbox_acl_entries

     This  entrypoint   replaces  the  extended   access  control
list (ACL) of a specified mailbox  with a newly supplied extended
ACL.

USAGE

     dcl  mlsys_utils_$replace_mailbox_acl_entries entry
               (character (*), character (*), pointer,
               fixed binary (35));

     call mlsys_utils_$replace_mailbox_acl_entries
               (mailbox_dirname, mailbox_ename, mailbox_acl_ptr,
               code);


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

ARGUMENTS

mailbox_dirname     (Input)
          is  the absolute  pathname of  the directory containing
          the mailbox.

mailbox_ename       (Input)
          is the  entryname of the  mailbox; the suffix  mbx need
          not be supplied by the caller.

mailbox_acl_ptr     (Input)
          is  a pointer  to the  mailbox_acl structure containing
          the new extended  ACL for this mailbox.  If  it is null
          or it locates a mailbox_acl structure which contains no
          ACL terms, this entrypoint will delete the extended ACL
          of  the  mailbox and  no one  will be  able to  use the
          mailbox.  The mailbox_acl  structure and, unless stated
          otherwise,  all  named  constants  mentioned  here  are
          defined in the include file mlsys_mailbox_acl.incl.pl1:

               dcl 1 mailbox_acl   aligned based
                                   (mailbox_acl_ptr),
                     2 header,
                       3 version   character (8) unaligned,
                       3 n_acl_terms
                                   fixed binary,
                       3 pad       bit (36),
                     2 acl_terms   (mailbox_acl_n_acl_terms refer
                                   (mailbox_acl.n_acl_terms)),
                       3 access_name
                                   character (32) unaligned,
                       3 extended_mode
                                   bit (36),
                       3 code      fixed binary (35);

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    MAILBOX_ACL_VERSION_1.

          n_acl_terms         (Input)
                    is  the number  of terms in  the new extended
                    ACL.  This value may be zero.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          acl_terms           (Input/Output)
                    is the new extended ACL.

            access_name         (Input)
                      is         the          access         name
                      (Person_id.Project_id.tag)  for   this  ACL
                      term.

            extended_mode       (Input)
                      is  the  extended access  to be  granted to
                      processes which  match this ACL  term.  The
                      possible  bits  which  may be  set  in this
                      field are defined by named constants of the
                      form A_MBX_ACCESS which  are defined in the
                      include  file mlsys_mailbox_modes.incl.pl1.

            status_code

            error_table_$invalid_ascii
                      The supplied access name contains non-ASCII
                      characters.

            error_table_$bad_name
                      The  supplied  access   name  has  improper
                      syntax.

            error_table_$bad_acl_mode
                      The supplied extended  access mode has bits
                      set  which are  not defined  in the include
                      file mlsys_mailbox_modes.incl.pl1.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          error_table_$unimplemented_version
                    The   caller  supplied   a  version   of  the
                    mailbox_acl  structure that  is not supported
                    by this entrypoint.

          error_table_$argerr
                    One or more of  the per-ACL term return codes
                    is  non-zero.   In this  case,  the mailbox's
                    extended ACL is not replaced.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$search_message

     This  entrypoint  scans  the  printed  representation  of  a
message for  the supplied text  string.  Either a  simple textual
search or a qedx regular  expression search may be used.  Options
are  provided to  control which  parts of  the message (envelope,
header, redistributions list, message body) are searched.

USAGE

     dcl  mlsys_utils_$search_message entry (pointer,
               character (*), pointer,fixed binary (35))
               returns (bit (1) aligned);

     string_found = mlsys_utils_$search_message (message_ptr,
               search_string, search_options_ptr, code);

ARGUMENTS

message_ptr         (Input)
          is a pointer to the message to be searched.

search_string       (Input)
          is the actual text of  the search string.  If a regular
          expression  search  is  requested, this  text  must not
          include  the  enclosing delimiters  which  are normally
          slashes (/).

search_options_ptr  (Input)
          is  a pointer  to a  search_options structure  which is
          defined        in        the        include        file
          mlsys_search_options.incl.pl1 as follows:

               dcl 1 search_options
                                   aligned based
                                   (search_options_ptr),
                     2 version     character (8) unaligned,
                     2 flags,
                       3 regexp_search
                                   bit (1) unaligned,
                       3 case_insensitive
                                   bit (1) unaligned,
                       3 search_envelope
                                   bit (1) unaligned,
                       3 search_header


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

                                   bit (1) unaligned,
                       3 search_redistributions_list
                                   bit (1) unaligned,
                       3 search_body
                                   bit (1) unaligned,
                       3 mbz       bit (30) unaligned;

          where:

          version             (Input)
                    is  the  current version  of  this structure.
                    The version  of the structure  described here
                    is given  by the value of  the named constant
                    SEARCH_OPTIONS_VERSION_2   which    is   also
                    defined      in     the      include     file
                    mlsys_search_options.incl.pl1.

          flags.regexp_search (Input)
                    if "1"b, a qedx  regular expression search is
                    used to  locate the search  string within the
                    message.   If  "0"b,  an exact  match  of the
                    search string must be found in the message.

          flags.case_insensitive
                              (Input)
                    if  "1"b,  both  the  search  string  and the
                    printed  representation  of  the  message are
                    effectively  translated to  upper-case before
                    performing   the   search.    If   "0"b,  the
                    difference between  upper-case and lower-case
                    will be signigicant.

          flags.search_envelope
                              (Input)
          flags.search_header (Input)
          flags.search_redistributions_list
                              (Input)
          flags.search_body   (Input)
                    if  "1"b, the  printed representation  of the
                    message     envelope,     message     header,
                    redistributions   list,   or   message  body,
                    respectively,  is  scanned   for  the  search
                    string.   If   "0"b,  that  section   is  not
                    examined.  At  least one of  these four flags
                    must be set by the caller.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          flags.mbz           (Input)
                    is reserved for future  expansion and must be
                    ""b.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_message
                    The   storage  identified   by  the  supplied
                    message_ptr is not a message.

          error_table_$inconsistent
                    The caller did not set  any of the four flags
                    (flags.search_envelope,  etc.)   which define
                    what  sections  of  the  message  are  to  be
                    examined.

          mlsys_et_$null_search_string
                    The supplied  search string either  is a null
                    string   or   consists  only   of  whitespace
                    characters.

          error_table_$regexp_invalid_star
          error_table_$regexp_too_complex
          error_table_$regexp_too_long
                    A syntax  error was detected  in the supplied
                    regular expression.

string_found        (Output)
          is  set to  "1"b if the  search string is  found in the
          printed representation  of the message.   Otherwise, it
          is set to "0"b.

NOTES

     The  printed  representation  used  by  this  entrypoint  is
described  in Section 1  of this document.   This entrypoint uses
the  default form  of the  envelope, header,  and redistributions
list as described in that section.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

Entry:  mlsys_utils_$send_message_to_recipient

     This  entrypoint  provides  a  simple  interface  to  send a
message to  a single recipient.   This interface is  intended for
use by subsystems, such as the Volume Retriever, which send short
messages to a single user.  Such  subsystems do not need the full
capabilities of the mail system (eg:  adding secondary recipients
to the message).

USAGE

     dcl  mlsys_utils_$send_message_to_recipient entry
               (character (*), character (*), fixed binary,
               character (*), character (*), bit (72) aligned,
               character (*) varying, fixed binary (35));

     call mlsys_utils_$send_message_to_recipient (author_name,
               recipient, delivery_mode, message_subject,
               message_body, message_access_class, reason_queued,
               code);

ARGUMENTS

author_name         (Input)
          specifies the  name of the  author of the  message.  If
          this string is non-null,  the user's mail table address
          with this  string as its  address name will  be used as
          the author of the message.  If this string is null, the
          user's    mail   table    address   as    returned   by
          mlsys_info_$user_mail_table_address will be used as the
          author of the message.

recipient           (Input)
          is  the  printed  representation of  the  address which
          identifies   the  recipient   of  the   message.   This
          entrypoint will  convert this text into  an actual mail
          system        address        by        using        the
          mlsys_utils_$parse_address_text   entrypoint  described
          above.

delivery_mode       (Input)
          specifies  how the  message should be  delivered to the
          recipient (ie:  as an ordinary, interactive, or express
          interactive   message).    See   the   description   of
          mail_system_$deliver_message for a detailed explanation


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

          of  the possible  values for this  option.  The include
          file    mlsys_deliver_info.incl.pl1    contains   named
          constants which should be used  to specify the value of
          this mode.

message_subject     (Input)
          is the  subject of the  message to be sent.   If a null
          string  is given,  the message  will be  sent without a
          subject.

message_body        (Input)
          is the  body of the  message to be sent.   This text is
          placed  in the  message as  a single  preformatted body
          section.   See  the  description of  message  bodies in
          Section 1 of this document for more information.

message_access_class
                    (Input)
          is the AIM access class of the message to be sent.

reason_queued       (Output)
          is  set to  the reason why  the message  was queued for
          later  delivery  if it  was queued  due to  a transient
          error.  This  reason is formatted in  a manner suitable
          for  use as  the object  of the  preposition because as
          seen        in         the        description        of
          mlsys_utils_$print_delivery_results, above.

code                (Output)
          is a standard  system status code.  It may  have any of
          the        values         returned        by        the
          mlsys_utils_$parse_address_text                      or
          mail_system_$set_access_class entrypoints.  It may also
          have  any of  the per-recipient values  returned by the
          mail_system_$deliver_message entrypoint.   In addition,
          it may have one of the following values:

          mlsys_et_$unknown_delivery_mode
                    The delivery mode requested  by the caller is
                    not one of the supported values documented in
                    the               description              of
                    mail_system_$deliver_message.

          mlsys_et_$empty_message
                    The supplied message body is empty.  In other
                    words,  it  is  either  a null  string  or is
                    composed only of whitespace characters.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

NOTES

     This   entrypoint  specifies   ALWAYS_QUEUE_FOREIGN  as  the
queueing mode and NOTIFY_ON_ERROR as the queued notification mode
in its  call to the  mail_system_$deliver_message entrypoint.  In
addition,  this  entrypoint requests  recipient  notification for
ordinary  messages.   Finally, this  entrypoint does  not request
that the recipient send an  acknowledgement message when he reads
the     message.      See      the     description     of     the
mail_system_$deliver_message    entrypoint    for    a   detailed
explanation  of  these  modes  and  the  settings  used  by  this
entrypoint.

             ________________________________________

Entry:  mlsys_utils_$summarize_address

     This entrypoint returns a character string representation of
an  address  which  is  suitable  for  use  in  English  messages
describing  some  action  or  error for  that  address.   See the
examples below for further information.

USAGE

     dcl  mlsys_utils_$summarize_address entry (pointer,
               bit (1) aligned, character (*) varying,
               fixed binary (35));

     call mlsys_utils_$summarize_address (address_ptr,
               beginning_of_sentence, address_summary, code);

ARGUMENTS

address_ptr         (Input)
          is a pointer to the address which is to be examined.

beginning_of_sentence
                    (Input)
          if "1"b,  specifies that the output  of this subroutine
          will  be used  as the first  phrase in  a sentence and,
          therefore,  the  first  word  in the  phrase  should be
          capitalized if appropriate.  If "0"b, the first word of
          the phrase is not capitalized.


MTB-613         Mail System Programmer's Reference        MTB-613

____________                                         ____________

mlsys_utils_                                         mlsys_utils_
____________                                         ____________

address_summary     (Output)
          is set to the summarized form of the address.

code                (Output)
          is a standard system status code.  Amongst the possible
          returned  codes,  the   following  codes  have  special
          significance to this entry:

          mlsys_et_$not_address
                    The   storage  identified   by  the  supplied
                    address_ptr is not an address.

          error_table_$smallarg
                    The address_summary parameter provided by the
                    caller is too small to  hold the value of the
                    summarized address.

EXAMPLES

     Examples of the text returned by this entrypoint include:

          Palter.Multics
          your logbox
          the mailing list >udd>m>gmp>mail_project
          the named group Mail System Maintainers