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