Multics Technical Bulletin
To: Distribution
From: Barry Margolin, Gary Palter
Date: June 29, 1983
Subject: The Mail Table, Revision 1
1. ABSTRACT
The MR10.2 Extended Mail Facility is required to allow mail
by Person_id without Project_id. Earlier plans were to implement
this capability using the User Inquiry System, but the current
implementation of inquire_ in EXL does not have the performance
that is necessary. For MR10.2 we will therefore implement a Mail
Table which will provide a simple mapping from Person_id to mail
address. This MTB describes the implementation of this table.
This revision contains changes to the set_mailing_address |
and display_mailing_address commands, and the addition of the |
administrative commands add_mail_table_entry, |
update_mail_table_entry, and delete_mail_table_entry. It also |
extends the mail table to allow multiple aliases for a mail table |
entry. In addition, the relationship between the Mail Table and |
the PNT has changed. Change bars are included. |
Comments on this MTB may be entered in the System M Forum
meeting:
>udd>Multics>Palter>meetings>Mail_System (mail)
or sent by Multics mail on System M or MIT to:
Palter.Multics
and
Margolin.Multics
or by U.S.Mail to:
Gary Palter, Barry Margolin
CISL, HIS
575 Technology Square
Cambridghe, MA 02139
(617) 492-7300
HVN 261-9300
_________________________________________________________________
Multics Project internal working Documentation. Not to be
reproduced outside the Multics Project.
Multics Technical Bulletin
2. CURRENT STATE
Currently (MR10.1) the Extended Mail Facility provides an
undocumented way for users to have mail system aliases. This is
implemented as a set of links in the directory
>udd>Daemon>mailboxes; an address without a Project_id or
"-at <hostname>" is looked up in that directory and the mail is
delivered to that mailbox (there is also a special case in the
network mail server software that treats links to Forum meetings,
user-ring segments with a ".mls" suffix (mailing lists), and
entries in the nonexistent directory >FORWARD, specially).
Changes to this directory are generally only made by system
administrators, as users with sma access would be able to divert
other users' mail.
3. GOALS
The MR10 PFS specifies that users should be able to address
mail by Person_id, without having to specify the Project_id of
the intended recipient. Thus, there has to be a concept of a
default mailing address for a user. Our primary goal is that a
user may specify to the system what his default mailing address
is, and that every user's default default mailing address be
determined by his default login project. This information will
| be kept in the Mail Table, which will be protected by the ring
mechanism. At one point we considered implementing this by
moving the above-described directory of links into a lower ring
(at least one customer has actually implemented this on its own);
however, the number of entries that we are dealing with far
exceeds the capacity of a directory, and any mechanism that
implements network addresses will be as kludgey as the current
one.
The link mechanism (described in the preceding section) had
the feature that a user could have many synonyms for his mailbox.
| It also allows for entries in the links directory that are are
| not associated with registered users. Since one requirement of
| this project is that every user should be registered in the mail
| table, the tools used by the system administrators when creating
| accounts must be taught to check the mail table before assigning
| a Person_id, to make sure that there is no conflict with
| already-assigned mail table entries or aliases.
| Mail table entries which do not correspond to registered
| users have several uses and present several other problems. They
| might be used for automatic forwarding of mail to other computers
| on a network, to allow mail to be sent to a mailing list or Forum
| meeting without requiring that the sender know that the recipient
| is not a real user, or to allow incoming mail from other
| computers to be addressed to such objects, even if their mail
| software makes it difficult to use Multics' syntax for such
Multics Technical Bulletin
addresses. A System Administrator will be able to add arbitrary |
entries to the Mail Table, and should be able to delegate |
maintenance of such entries to a specified user or users by means |
of ACS segments. |
One way in which we would like to remain compatible with the
current mechanism is in case-insensitivity. Currently, the mail
system searches the mailbox links directory first for an entry
whose name matches the given name exactly, and failing, searces
for the name in all uppercase. This is convenient for systems
that are on large networks, as many of the computers from which
they will receive mail are generally case-insensitive, so the
mail senders are very likely to specify the case incorrectly. A
similar scheme should be implemented in the mail table. In order
to keep the interface simple, it will be considered an error if
more than one entry matches a name case-insensitively and none
match it exactly.
A final goal is that the default mailing address be able to
specify network addresses, mailing lists, and anything else to
which the mail system allows mail to be delivered.
4. IMPLEMENTATION
The mail table will be implemented as an ms_table (MSF
managed by ms_table_mgr_), just as the PNT and URF currently are.
Its pathname will be
>site>mail_system>mail_table
It will reside in ring-2 so that it will be protected from
improper updates. Two types of entries will exist in the
database: regular entries and alias entries. The following
information will be recorded in each regular entry: the default |
project, a flag specifying whether the entry corresponds to a PNT |
entry, the ACS pathname, and the mailing address. In addition, |
the first and last aliases will be recorded in the regular entry; |
this is the head and tail of a doubly-linked list of alias |
entries. Alias entries will just contain the primary name, a |
flag specifying whether the alias corresponds to a PNT alias, and |
the previous and next aliases; any lookups by alias will just |
return the same information it would have if the primary name had |
been specified. In the mail_table_entry structure (described in |
the Documentation section) the flags.alias_entry component is
used to distinguish the two types of entries. In most cases the
interfaces deal only with regular entries; the exception is that |
all the aliases of an entry are deleted when the entry itself is |
deleted with mail_table_priv_$delete. Aliases may be added and |
removed by using mail_table_priv_$add_alias and |
mail_table_priv_$delete_alias. |
Users will be able to modify the mailing address information
in their own entry. Also, if there is a non-blank acs_path |
Multics Technical Bulletin
| component then any user with rw to the segment specified by the
| pathname may update the mailing address information in an entry.
Whenever a user's default project is changed (either by logging
in with the -change_default_project control argument or by a
system administrator using new_user$cg) the default_project in
the mail table will be updated. In addtion, new_user will create
an entry for a user when he is registered on the system, and
create an alias entry if the user is given an alias. The
remove_user command will delete the appropriate entries from the
| mail table. The add_mail_table_entry, update_mail_table_entry,
| and delete_mail_table_entry commands may also be used by adminis-
| trators to maintain entries that are not associated with regis-
| tered users or to manipulate entries in ways which normal users
| are prohibited.
Three gate procedures will be provided to access the mail
table. The mail_table_ gate will be the interface normal users
will use to retrieve and update the information in the mail
table. In general it will be called by address parsing routines
in mail_system_ and by the command provided for users to update
their mailing address. The mail_table_initializer_ gate will be
used by the Answering Service to update an entry when a user
changes his default project while logging in. The
mail_table_priv_ gate will be used by system administrators to
create and manage the mail table. In general it will be called
by existing system administrative commands (primarily new_user)
and by commands provided with the mail table software. See the
documentation section for complete information on these proce-
dures.
5. DOCUMENTATION
The following is MPM-style documentation for the commands
and subroutines associated with the mail table. Much of it is
not actually intended for user consumption, but is included in
this document as internal documentation for Multics System
Development. For instance, much of the documentation describes
installation procedures which should not be documented in manuals
(but probably should be in installation instructions), and the
documentation for privileged entrypoints need not be published.
___________________ ___________________
set_mailing_address set_mailing_address
___________________ ___________________
Names: set_mailing_address, smla
This command is used by a user to specify his preferred mailing
address, which will be used by the mail system when mail is
addressed to him by his Person_id alone (i.e. "sdm Opus", as
opposed to "sdm Opus.Bloom"). The user may also specify that his
mailing address be reset to the default, which means that mail
addressed to "Milo" will be sent to Milo.DProject, where DProject
is whatever Milo's default project is at the time the mail is
sent. This may also be used by users who are designated as |
maintainers of other Mail Table entries to update these entries. |
SYNTAX AS A COMMAND
smla {ADDRESS} {-CONTROL_ARGS}
ARGUMENTS
address
This may be any recipient address accepted by the
send_mail command. Type
"help >doc>subsystem>mail_system>addresses.gi" for more
information on allowable address forms. Only one
address may be specified, and this is incompatible with
the -default_project control argument.
CONTROL ARGUMENTS
-default_project
-dp
Specifies that the mailing address be reset to the
default project. This control argument is incompatible
with the specification of a mailing address.
|
-user NAME |
Specifies the entry whose mail address is to be |
updated. The name should be enclosed in quotes if it |
contains whitespace. If name is an alias then the |
associated normal entry is updated. If this control |
argument is used, the user must have rw access to the |
ACS segment associated with the entry. (Default: the |
user's own entry). |
___________________ ___________________
set_mailing_address set_mailing_address
___________________ ___________________
NOTES
Either an address or -default_project must be
| specified, but not both. The -default_project control
| argument should not be used if the entry is not
| associated with a registered user, because only users
| have default projects. If this is attempted, an error
| will be reported.
_______________________ _______________________
display_mailing_address display_mailing_address
_______________________ _______________________
Names: display_mailing_address, dsmla
Displays the specified mail table entries. The display will be |
in the format used in message headers displayed by read_mail. In |
addition, if the mail table entry specifies an ACS segment to |
allow other maintainers, this pathname is displayed. |
SYNTAX AS A COMMAND |
dsmla {NAMEs} |
ARGUMENTS
Name |
Specifies the name or alias of the user whose mailing |
address should be displayed, or the name or alias of a |
mail table entry for a non-user. If none are given, |
then this defaults to the current user. More than one
may be given, and this command will display the mailing
address for all of them (printing a warning message for
any invalid ones).
_________________ _________________
create_mail_table create_mail_table
_________________ _________________
Name: create_mail_table
This command is used by system administrators to create the
initial mail table. It is initially populated with information
taken from the Person Name Table (PNT).
SYNTAX AS A COMMAND
create_mail_table
ACCESS REQUIRED
The user must have access to the gate mail_table_priv_, r access
to the PNT, and sma access to >site>mail_system in ring-2. In
addition, the access class of the mail table will be the current
authorization of the creator, so this user should be logged in at
system_low (this may be ignored if the site does not use multiple
AIM levels); the command will attempt to set dir and seg
privileges, in which case the mail table will be created at
system low, regardless of the authorization of the creator.
NOTES
This command should generally only be needed once, the first time
the system is booted when it is delivered, or when the a site
| first upgrades to MR10.2. It must be used after the PNT has been
| created, but before the system is brought up for regular service;
| the safest way is to run it before the Answering Service is
| brought up.
__________________ __________________
compact_mail_table compact_mail_table
__________________ __________________
Names: compact_mail_table, salvage_mail_table
This command is used by a system administrator to fix the mail
table after it has been damaged or has become full. As the mail
table and the PNT contain a parallel set of entries, any time the
PNT needs to be compacted (using salvage_mstb) the mail table
should also be compacted. This works by copying the mail table;
the old mail table is renamed to mail_table.MM/DD.HHMM.
SYNTAX AS A COMMAND
compact_mail_table {SIZE}
ARGUMENTS
size
This specifies the size of the new mail table. If not
specified this defaults to the number of used entries
(both regular and alias entries) multiplied by three, |
which is close to optimum for the accessing algorithm.
In general, it is best to keep the mail table the same
size as the PNT. If the size specified is not large
enough to hold the existing entries an error will be
generated. *
NOTES
This command should be run before the Answering Service is |
brought up. |
____________________ ____________________
add_mail_table_entry add_mail_table_entry
____________________ ____________________
| Name: add_mail_table_entry
|
| Adds an entry to the Mail Table, and specifies its mail address.
| This command is used by system administrators to define names for
| mailing lists and other possible mail destinations, and added
| names for users, so that users may send mail to these objects as
| if they were other users, i.e. not requiring pathnames or
| Project_ids. The name must not already exist in the Mail Table
| or the PNT, disregarding case.
|
|
| SYNTAX AS A COMMAND
|
| add_mail_table_entry NAME ADDRESS {-CONTROL_ARGS}
|
|
| ARGUMENTS
|
| name
| is a string which specifies the name to be given to
| this mail table entry. It must be enclosed in quotes
| if it contains whitespace.
|
| address
| is a destination specifier, as used by
| set_mailing_address. This is the initial mail address
| associated with the specified name.
|
|
| CONTROL ARGUMENTS
|
| -alias NAME
| specifies an alternate name for the name being defined.
| If this control argument is specified multiple times,
| all the names are defined as aliases for the entry.
|
| -acs_path PATH
| specifies the ACS segment which controls who may update
| the entry's mail address. rw access to the ACS segment
| indicates that a user may update the entry. If this is
| not specified or is the null string, only users with
| access to mail_table_priv_ may update the entry.
|
|
| ACCESS REQUIRED
|
| e access to the gate mail_table_priv_.
_______________________ _______________________
update_mail_table_entry update_mail_table_entry
_______________________ _______________________
Name: update_mail_table_entry |
|
Modifies an entry in the Mail Table. |
|
|
SYNTAX AS A COMMAND |
|
update_mail_table_entry NAME {ADDRESS} {-CONTROL_ARGS} |
|
|
ARGUMENTS |
|
NAME |
Specifies the name of the mail table entry which is to |
be updated. The name must be enclosed in quotes if it |
contains whitespace. If the name is an alias, the |
associated normal entry is updated. |
|
ADDRESS |
is a destination specifier, as used by |
set_mailing_address. If this is given, it becomes the |
new mail address of the entry. |
|
|
CONTROL ARGUMENTS |
|
-alias NAME |
Specifies an alternate name for the entry. If this is |
specified multiple times, each alias is added. |
|
-acs_path PATH |
specifies the ACS segment which controls who may update |
the entry's mail address. rw access to the ACS segment |
indicates that a user may update the entry. If path is |
the null string there will be no ACS segment, and only |
system administrators (anyone with access to |
mail_table_priv_) may update the entry. |
|
-delete_alias NAME |
causes the specifiedalternate name to be removed from |
the entry. In order to maintain consistency with the |
PNT, this alias may not be the user's login alias. |
|
|
ACCESS REQUIRED |
|
e access to the gate mail_table_priv_. |
_______________________ _______________________
delete_mail_table_entry delete_mail_table_entry
_______________________ _______________________
| Name: delete_mail_table_entry
|
| Removes enties from the Mail Table which are not associated with
| a registered user.
|
|
| SYNTAX AS A COMMAND
|
| delete_mail_table_entry NAMES
|
|
| ARGUMENTS
|
| NAME
| is a string which specifies a mail table entry which is
| to be deleted. It must be enclosed in quotes if it
| contains whitespace.
|
|
| ACCESS REQUIRED
|
| e access to the gate mail_table_priv_.
|
|
| NOTES
|
| In order to maintain consistency with the PNT, this will not
| permit entries which are associated with registered users to be
| deleted. If the mail table entry has aliases then the alias
| entries are also deleted.
___________ ___________
mail_table_ mail_table_
___________ ___________
Name: mail_table_
These entrypoints are used by normal users to access the mail
table.
Entry: mail_table_$get
Function: This entrypoint retrieves a specified mailing |
address. This address is in a form suitable for use with |
mail_system_ entrypoints. The name given is matched against the |
names and aliases in the mail table. If it is not found, then a |
case-insensitive search is performed.
USAGE SYNTAX
declare mail_table_$get entry (char (*) varying, ptr, |
char (*), fixed bin (35); |
call mail_table_$get (name, address_ptr, acs_path, code); |
ARGUMENTS
name |
is either the name or alias of a Mail Table entry. |
This specifies the mailing adress which is to be |
returned. (Input) |
address_ptr
is a pointer to an address object which may be passed
to several mail_system_ entrypoints. The structure of
this object is internal to the mail system, and is not
documented here; only mail_system_ entrypoints should
be used to manipulate this object. (Output)
|
acs_path |
is the pathname of the segment whose access control |
list specifies who may update the specified entry. If |
this is the null string then only the owner of the |
entry (if it corresponds to a registered user) or a |
user with access to mail_table_priv_ may update the |
entry. |
code
is a standard system status code. If this is
mlsys_et_$ambiguous_address then the name did not match |
any name or alias exactly, but matched more than one |
without regard to case. (Output)
___________ ___________
mail_table_ mail_table_
___________ ___________
Entry: mail_table_$set
| Function: This entrypoint updates the a mailing address.
USAGE SYNTAX
|
| declare mail_table_$set entry (char (*) varying, ptr,
| fixed bin (35));
| call mail_table_$set (name, address_ptr, code);
|
ARGUMENTS
|
| name
| is the name or alias of the mail table entry whose
| mailing address should be changed. If this is the null
| string, then the caller's mail table entry is updated.
address_ptr
is a pointer to a mail_system_ address object, or is
| null. If it is non-null then it specifies the entry's
new mailing address. The structure of this object is
internal to the mail system and is not documented here;
appropriate mail_system_ subroutines should be used to
create and manipulate this object. If it is a null
pointer, then it specifies that the mailing address
should be removed, i.e. that mail addressed to him
should be delivered to his mailbox in his home directo-
ry for his default project,
>udd>Default_Proj>Person_id>Person_id.mbx (this is the
default if the user has never set a mailing address).
| This is only permitted for entries associated with a
| registered Person_id. (Input)
code
* is a standard system status code. (Output)
_______________________ _______________________
mail_table_initializer_ mail_table_initializer_
_______________________ _______________________
Name: mail_table_initializer_
This gate is used by the Answering Service to manage the mail
table on behalf of users. Only Initializer.SysDaemon.z need have
access to this gate.
Entry: mail_table_initializer_$set_dft_proj
Function: Sets the default project field in the mail table
entry for a specified user. This is used by the Answering
Service when a user logs in with the -change_default_project
control argument. This ensures that if the user is using the
default mailing address that his mail always goes to his current
default project.
USAGE SYNTAX
declare mail_table_initializer_$set_dft_proj entry |
(char (*) varying, char (*) varying, fixed bin (35)); |
call mail_table_initializer_$set_dft_proj (person_id, |
default_proj, code); |
ARGUMENTS
person_id
is the Person_id of the user whose default project is
being changed. (Input)
default_proj
is the new default project of the specified user.
(Input)
code
is a standard system status code. (Output) *
________________ ________________
mail_table_priv_ mail_table_priv_
________________ ________________
Name: mail_table_priv_
These entrypoints are used by system administrators to maintain
the mail table. Access to this gate should be given to
*.SysAdmin.*
Entry: mail_table_priv_$create
Function: This entrypoint creates the mail table.
USAGE SYNTAX
declare mail_table_priv_$create entry (fixed bin,
fixed bin (35));
call mail_table_priv_$create (size, code);
ARGUMENTS
size
is the number of entries to be allocated in the mail
table. For best operation this should be three times
the number of entries that will be used, which is the
| number of names and aliases that will be registered.
(Input)
code
is a standard system status code. (Output)
NOTES
The mail_table_priv_$create subroutine is called as part of the
operation of the create_mail_table command. If a site is
upgrading to MR10.2 from an earlier release, this
mail_table_priv_$fill_from_pnt subroutine should be called imme-
diately after this subroutine in order to initialize the data;
this will also be done by create_mail_table.
The process should have sma access to >site>mail_system. If the
mail table already exists it will be renamed to
mail_table.MM/DD.HHMM. The process should also be logged in with
an authorization of system_low if the site runs multiple AIM
levels; the access class of the the mail table will be set to the
process' authorization. If the process has dir and seg privi-
leges enabled then the mail table will be created with an access
class of system_low.
________________ ________________
mail_table_priv_ mail_table_priv_
________________ ________________
Entry: mail_table_priv_$fill_from_pnt
This entrypoint has been deleted, as its functionality can
be provided by the user-ring portion of the create_mail_table
command.
Entry: mail_table_priv_$add
Function: Adds a new entry to the mail table. This |
entrypoint will not add aliases for existing entries; use |
mail_table_priv_$add_alias for this purpose. |
USAGE SYNTAX
declare mail_table_priv_$add entry (ptr, fixed bin (35));
call mail_table_priv_$add (mte_ptr, code);
ARGUMENTS
mte_ptr
is a pointer to a mail_table_entry structure, as
declared in mail_table_entry.incl.pl1.
Mail_table_entry.name specifies the entry which is |
being added. |
code |
is a standard system status code. (Output) It can be |
one of the following: |
0 The entry (or entries) was added successfully. |
error_table_$unimplemented_version |
The version component of the mail_table_entry |
was not set properly by the caller. |
error_table_$id_already_exists |
The name component specified a name that |
already existed in the mail table. |
NOTES
This subroutine is normally only called by new_user when a new ID
is being registered on the system, and by add_mail_table_entry to |
create an entry for a non-user. |
________________ ________________
mail_table_priv_ mail_table_priv_
________________ ________________
Entry: mail_table_priv_$delete
Function: Deletes an entry from the mail table. This
should be done whenever a Person_id is deregistered.
USAGE SYNTAX
| declare mail_table_priv_$delete entry (char (*) varying,
| fixed bin (35));
| call mail_table_priv_$delete (name, code);
ARGUMENTS
| name
| is either a name or an alias. This specifies the entry
| which should be removed. If the entry has any aliases,
| then either the primary name or analias may be used,
| and all the entries will be deleted. (Input)
code
is a standard system status code. (Output) It can be
one of the following:
0 The entry (or entries) was deleted successful-
ly.
error_table_$id_not_found
| There is no entry with the specified name.
NOTES
This subroutine will normally be called by the delete_user
| command prior to deleting the user from the PNT and URF, or by
| the delete_mail_table_entry command when deleting a non-user
| entry.
Entry: mail_table_priv_$update
Function: Replaces a user's mail table entry. The replace-
ment mail_table_entry should generally be created by retrieving
| the entry, modifying it, and then calling this routine. Alter-
| nate names may not be manipulated with this entrypoint; use
| mail_table_priv_$add_alias, mail_table_priv_$delete_alias, and
| mail_table_priv_$get_aliases to manipulate aliases.
________________ ________________
mail_table_priv_ mail_table_priv_
________________ ________________
USAGE SYNTAX
declare mail_table_priv_$update entry (ptr, fixed bin (35));
call mail_table_priv_$update (mte_ptr, code);
ARGUMENTS
mte_ptr
is a pointer to a mail_table_entry structure as
declared in mail_table_entry.incl.pl1. The subroutine
will modify the entry identified by the |
mail_table_entry.name component; if this is an alias, |
then the regular entry will be modified. |
(Input)
code
is a standard system status code. (Output) It can be one
of the following:
0 The entry (or entries) was updated successfully.
error_table_$unimplemented_version
The version component of the mail_table_entry was
not set properly by the caller.
error_table_$id_not_found
There is no entry with the specified name. |
NOTES
This subroutine will normally be called by the new_user$cg and
new_user$cga commands if any of the information needed by the
mail table (currently only the default project) was changed, and |
by the update_mail_table_entry command when changing the mailing |
address. |
Entry: mail_table_priv_$get |
Function: Retrieves a mail table entry given either its |
name or alias. |
________________ ________________
mail_table_priv_ mail_table_priv_
________________ ________________
USAGE SYNTAX
| declare mail_table_priv_$get entry (char (*) varying, ptr,
| fixed bin (35));
| call mail_table_priv_$get (name, mte_ptr, code);
ARGUMENTS
| name
| is the name or alias of the entry which should be
| retrieved. (Input)
mte_ptr
is a pointer to a mail_table_entry structure as
declared in mail_table_entry.incl.pl1. This structure
| should already be allocated and have the version
| component set; if the pointer is null an error code
will be returned. (Input)
code
is a standard system status code. (Output) It can be
one of the following:
0 The entry was retrieved successfully.
error_table_$unimplemented_version
The version component of the mail_table_entry
was not set properly by the caller.
error_table_$id_not_found
| There is no entry with the specified name.
NOTES
| The new_user$cg, new_user$cga, and update_mail_table_entry com-
| mands use this subroutine to retrieve the old contents of the
| mail table entry in order to update it, and the
| display_mail_table_entry command uses this.
|
|
| Entry: mail_table_priv_$get_raw_by_name
|
| Function: Retrieve a real mail table entry given the its
| key, which is either a name or alias. If an alias is specified,
| then the actual alias entry will be returned. This is intended
| as a low-level interface, and no commands are provided which use
| this.
________________ ________________
mail_table_priv_ mail_table_priv_
________________ ________________
USAGE SYNTAX |
|
declare mail_table_priv_$get_raw_by_name (char (*) varying, |
ptr, fixed bin (35)); |
call mail_table_priv_$get_raw_by_name (name, mtre_ptr, |
code); |
|
|
ARGUMENTS |
|
name |
is the name of the entry to be retrieved. (Input) |
|
mtre_ptr |
is a pointer to a mail_table_raw_entry structure as |
declared in mail_table_entry.incl.pl1. It must already |
be allocated and the version component filled in. |
(Input) |
|
code |
is a standard error code. (Output) It may be one of |
the following: |
0 The entry was retrieved successfully. |
error_table_$unimplemented_version |
The version component of the |
mail_table_raw_entry was not set properly by |
the caller. |
error_table_$id_not_found |
No entry with the specified name was found in |
the mail table. |
Entry: mail_table_priv_$get_raw_by_index |
Function: Retrieve a real mail table entry given its index |
into the mail table (which is effectively a sparse array). This |
will return alias entries as well as regular entries. This |
subroutine is useful for listing the contents of the mail table. |
________________ ________________
mail_table_priv_ mail_table_priv_
________________ ________________
USAGE SYNTAX
declare mail_table_priv_$get_raw_by_index (fixed bin, ptr,
fixed bin(35));
call mail_table_priv_$get_raw_by_index (N, mte_ptr, code);
ARGUMENTS
N
is the index of the entry which should be retrieved.
It must be greater than 0. (Input)
mte_ptr
| is a pointer to a mail_table_raw_entry structure as
| declared in mail_table_entry.incl.pl1. This structure
should already be allocated and the version component
should be set; if the pointer is null an error code
will be returned. (Input)
code
is a standard system status code. (Output) It can be
one of the following:
0 The entry was retrieved successfully.
error_table_$unimplemented_version
The version component of the mail_table_entry
was not set properly by the caller.
error_table_$no_record
The specified index corresponds to an unused or
deleted record.
error_table_$bad_index
The specified index references beyond the end
of the mail table.
error_table_$bad_subr_arg
The index was not greater than 0.
NOTES
The standard use of this entry is by a routine which loops over
all the possible indices starting from 1 until
error_table_$bad_index is returned. If a call returns
error_table_$no_record then the procedure should just go to the
next iteration of the loop, as this is to be expected.
________________ ________________
mail_table_priv_ mail_table_priv_
________________ ________________
Entry: mail_table_priv_$add_alias |
|
Function: Adds an alternate name to an existing mail table |
entry. |
|
|
USAGE SYNTAX |
|
declare mail_table_priv_$add_alias (char (*) varying, |
char (*) varying, fixed bin (35)); |
call mail_table_priv_$add_alias (name, alias, code); |
|
|
ARGUMENTS |
|
name |
is the name of the existing entry which is being given |
an alternate name. This may be the primary name or one |
of its aliases. (Input) |
|
alias |
is the new alternate name being added. (Input) |
|
code |
is a standard system status code. (Output) It can be |
one of the following: |
0 The alias was added successfully. |
error_table_$id_already_exists |
The specified alias is already in use in the |
mail table as a name or alias. |
error_table_$id_not_found |
There is no entry in the mail table with the |
specified name. |
|
|
Entry: mail_table_priv_$delete_alias |
|
Function: Deletes an alias from the mail table. |
________________ ________________
mail_table_priv_ mail_table_priv_
________________ ________________
| USAGE SYNTAX
|
| declare mail_table_priv_$delete_alias (char (*) varying,
| fixed bin(35));
| call mail_table_priv_$delete_alias (alias, code);
|
|
| ARGUMENTS
|
| alias
| is the alias which should be deleted from the mail
| table. This may not be the primary name of an entry;
| use mail_table_priv_$delete to delete the regular entry
| itself. It also may not be the login alias of the
| user. (Input)
|
| code
| is a standard system status code. (Output) It can be
| one of the following:
| 0 The alias was removed successfully.
| error_table_$bad_subr_arg The alias specified was the primary
| name of the entry or was a user's login alias,
| so it could not be deleted.
| error_table_$id_not_found
| The specified alias did not exist in the mail
| table.
|
|
| Entry: mail_table_priv_$get_aliases
|
| Function: Returns a list of all the names of an entry.
|
|
| USAGE SYNTAX
|
| declare mail_table_priv_$get_aliases (char (*) varying,
| char (*), ptr, ptr, fixed bin (35));
| call mail_table_priv_$get_aliases (name, version, area_ptr,
| mta_ptr, code);
|
|
| ARGUMENTS
|
| name
| is the name or alias of the entry whose names should be
| listed. (Input)
________________ ________________
mail_table_priv_ mail_table_priv_
________________ ________________
version |
is the version of the mail_table_aliases structure that |
the caller wishes returned. Currently this should be |
set to MAIL_TABLE_ALIASES_VERSION_1, which is declared |
in mail_table_entry.incl.pl1. (Input) |
|
area_ptr |
is a pointer to an area in which the mail_table_aliases |
structure should be allocated. It may not be null. |
(Input) |
|
mta_ptr |
will be set to point to a mail_table_aliases structure, |
as declared in mail_table_entry.incl.pl1. This struc- |
ture will contain an array of all the names of the |
entry, including the primary name. (Output) |
|
code |
is a standard system status code. (Output) It can be |
one of the following: |
0 No errors were encountered. |
error_table_$unimplemented_version |
The version specified is not supported by the |
subroutine. |
error_table_$id_not_found |
No entry with the specified name was found in |
the mail table. |
Entry: mail_table_priv_$count_entries
Function: Returns the number of used entries in the mail
table. This is useful for determining the proper size of a
compacted mail table (the mail table works optimally when it is
one-third full).
USAGE SYNTAX
declare mail_table_priv_$count_entries entry (fixed bin,
fixed bin (35));
call mail_table_priv_$count_entries (N, code);
ARGUMENTS
N
is the number of used entries in the mail table.
(Output)
________________ ________________
mail_table_priv_ mail_table_priv_
________________ ________________
code
is a standard system status code. (Output)
_________________________ _________________________
mail_table_entry.incl.pl1 mail_table_entry.incl.pl1
_________________________ _________________________
Name: mail_table_entry.incl.pl1
declare 1 mail_table_entry aligned
based (mail_table_entry_ptr),
2 version char (8),
2 name char (32) varying, |
2 acs_path char (168), |
2 default_project char (12) varying,
2 mailing_address char (256) varying;
declare MAIL_TABLE_ENTRY_VERSION_1 char (8) int static
options (constant)
init ("mte_0001");
Where:
version is the version of the structure being used. Currently
this should always be set to the value of
MAIL_TABLE_ENTRY_VERSION_1.
name is the name of the entry. When this structure is used |
as input to a mail_table_priv_ entrypoint then this |
component may be the primary name or an alias of the |
entry. When this structure is used for output it will |
always be the primary name. |
acs_path |
is the pathname of a segment whose access control list |
controls who may modify the mailing_address of this |
entry. If this is the null string, then only a user |
with access to mail_table_priv_ or the owner of the |
entry may modify it (the owner is the user whose |
Person_id is the same as the name of the entry). |
default_project
is the user's default login project. If no
mailing_address is set for the user then this will be
used to determine the mailing address. This will be |
null for entries which do not correspond to registered |
users. |
mailing_address
is a character string form of a mail destination, as
might appear in a standard header. mail_table_$set,
mail_table_priv_$add, and mail_table_priv_$update will
verify that this is in correct format. Various
entrypoints in mail_system_ can be used to generate
this form of address. If the entry corresponds to a |
registered user then this may be blank, in which case |
_________________________ _________________________
mail_table_entry.incl.pl1 mail_table_entry.incl.pl1
_________________________ _________________________
| the default project component will be used to determine
| the user's default mailbox. cbf 1
|
|
| declare 1 mail_table_raw_entry aligned
| based (mail_table_raw_entry_ptr),
| 2 version char (8),
| 2 name char (32) varying,
| 2 primary_name char (32) varying,
| 2 flags,
| 3 alias_entry bit (1) unaligned,
| 3 registered_user bit (1) unaligned,
| 3 mbz bit (34) unaligned,
| 2 n_name fixed bin,
| 2 next_name char (32) varying,
| 2 prev_name char (32) varying,
| 2 acs_path char (168),
| 2 default_project char (12) varying,
| 2 mailing_address char (256) varying;
|
| declare MAIL_TABLE_RAW_ENTRY_VERSION_1 char (8) int static
| options (constant)
| init ("mtre_001");
|
|
| Where:
| version is the version of the structure being used. Currently
| this should always be set to the value of
| MAIL_TABLE_RAW_ENTRY_VERSION_1.
| name is the name or alias of this entry.
| primary_name
| is the name of the regular entry that corresponds to
| this entry. If this is a regular entry this will be
| the same as the name component. If it is an alias
| entry then this is the name of the regular entry which
| contains all the normal information.
| flags.alias_entry
| indicates that the entry is an alias entry. If this is
| on then the default_project, mailing_address, and
| acs_path information are not valid; the regular entry,
| identified by the primary_name component, contains the
| correct values for these components.
| flags.registered_user
| indicates that the entry or alias corresponds to a PNT
| entry. Such entries should only be deleted when the
| corresponding PNT entry is deleted, in order to main-
| tain consistency between the PNT and the mail table.
| If this flag is off in a regular entry then the
| mailing_address compontent may not be blank and the
_________________________ _________________________
mail_table_entry.incl.pl1 mail_table_entry.incl.pl1
_________________________ _________________________
default_project component must be blank. |
flags.mbz |
are reserved and should be set to "0"b. |
n_names is the number of names for this entry. This is only |
set in the regular entry, and the count includes the |
regular entry. |
next_name |
is the next name for this entry. This is used to make |
a linked list of the names for an entry. In the |
regular entry this contains the first alias, if any, or |
the null string. The last alias always contains the |
null string in this field. |
prev_name |
is the previous name for this entry. This is like the |
next_name component, except that it chains the entries |
together in the reverse direction. It is used as a |
redundancy check; someday the mail table salvager will |
use this. |
acs_path, default_project, mailing_address |
are the same as in the mail_table_entry structure. |
|
|
declare 1 mail_table_aliases aligned |
based (mail_table_aliases_p|tr),
2 version char (8), |
2 n_names fixed bin, |
2 names (mail_table_aliases_extent|refer
(mail_table_aliases.n_na|mes))
char (32) varying; |
|
declare mail_table_aliases_extent fixed bin; |
declare MAIL_TABLE_ALIASES_VERSION_1 char (8) int static |
options (constant) |
init ("mta_0001"); |
|
|
Where: |
version is the version number of the structure. Currently this |
should always be set to the value of the variable |
MAIL_TABLE_ALIASES_VERSION_1. |
n_names is the number of names for the entry, including the |
primary name. |
names is an array of the names for the entry. When this is |
used as output from mail_table_priv_$get_aliases the |
first element of this array is the primary name. |
mail_table_aliases_extent |
is an automatic variable which is used only by the |
procedure which allocates the structure. |