.NONUMBER
.C
 
.S 5
.C
ARC MAIL
.S 3
.C
INTER-USER MESSAGE TRANSFER FACILITY
.S 3
.C
ATMOSPHERIC SCIENCES DIVISION
.S
.C
ALBERTA RESEARCH
.S 10
.C
This manual describes ARC MAIL
.C
Version V4.0 for RSX11M V4.0
.c
November 25, 1981
.PG
.C
ARC MAIL
.S
.C
Inter-user Message Transfer Facility
.S 3
.fill
.number 1
.pg
.c
.s 2
.c
ARC MAIL
.s
.c
Inter-user Message Transfer Facility
.s 3
.ap
.hl 2 Introduction

ARC MAIL is an RSX-11M utility program which
supports inter-user message transfer. An RSX user may
send a message to other users, check to see if any mail has
been sent to him, and save messages permanently.
Readers are assumed to be knowledgable users of the RSX-11M
operating system, and familiar with operation of an RSX-11M terminal.

ARC MAIL was developed and written by William Korendyk
and Mark Johnson of the Computing Group of the Atmospheric
Sciences Division of the Alberta Reseach Council, under work
funded by the Alberta Weather Modification Board.  Later it was modified
by James Downward of KMS Fusion Inc., Ann Arbor, Michigan to fix bugs
and support new (but optional) multi users featurs.
This manual describes ARC MAIL  version V4.0 for RSX11M V4.0.
.s
.i 50
V4.0
.i 50
WK, MJ, JGD
.number Chapter 1
.chapter User's Guide

The aim of this chapter is to supply a comprehensive
guide to the use and understanding of the ARC MAIL  Inter-user
Message Transfer Facility.

Within each section of this chapter, basic concepts are described
first, followed by more advanced concepts in subsections. Only the first
part of each section is required to obtain a brief overview of ARC MAIL .

.hl 1 General Description

The ARC MAIL  Inter-user Message Transfer Facility
supports for the transfer of mail (messages, letters, notices, etc.) to
any person entered in the RSX user account file of an RSX
multi-user system. This account file is maintained by the system manager.

The ARC MAIL  facility maintains a "mailbox" for each user,
and each letter sent to a user is inserted into his own
personal mailbox. Once deposited into the user mailbox, only that user has
access to that mail. The sender can not retrieve the letter, nor can
any other user access the contents of the mailbox.

Each user is able to open his own mailbox and read its contents.
He may then leave mail in his mailbox, or empty his mailbox
by discarding it or saving it into a "mailbag".

ARC MAIL  was designed to supply a high degree of
usability with a concise, easy to use command syntax. To achieve this
conciseness, the command syntax differs from standard RSX-11
utilities. However, the utility
allows for quick, single command execution, as well as  allowing for
a certain amount of user interaction. The general command syntax is:
.s
.c
>MAIL [LETTER] [TO NAME]
.s
.lm +10
.i -7
.tp14
where##the square brackets enclose an optional portion of the command line.
.s
.i -7
LETTER#(if specified) must be a valid RSX file specification
which indicates the file containing the letter that is to be mailed. If
not specified, the letter will be read from the terminal,
terminated by typing a CTRL/Z.
.i -7
TO#####is required if a name is specified.
.i -7
NAME###is the name (or list
of names) of the person(s) to whom the mail is to be sent. If not
specified, ARC MAIL  will request names from the terminal until
a CTRL/Z is typed.
.lm0
.ap
.tp 10
.hl 1 Sending Mail

Sending mail is the proccess of appending a letter to one or more
user mailboxes. The letter may be already a file, or created by ARC MAIL 
before the mail is sent.
.lm +5
.hl 2 Preparing A Letter

A letter may be contained in a file prepared earlier
using a text editor, or built by ARC MAIL  by reading lines from
the terminal. The contents of the letter, whether in a file
or typed at the terminal, can be virtually any text, as long as the length of
each line is less than the maximum allowable size specified
by the system manager. (The
maximum allowable line size is generally set at 132. characters per line.)

Certain defaults apply to portions of the file specification which
are not explicitly given:
.s
.lm +7
.ts 30
.nofill
device:	SY0:
UIC:            The current UIC
filename:       (no default)
file type:      TXT
version number: The highest version
.s
.fill
.lm -7
If the file type of the file specification is MAI, then the file
is considered to be a "temporary message" and will be deleted if
successfully deposited into the user's mailbox.

There are two different kinds of messages which may be sent. The
first, a "letter", is a message which requires an immediate reply.
The second kind, a "notice", is a message which does not require a reply.

When a file name is supplied in the command string, it is assumed
to be a letter, and replies will be requested from other users receiving it.
To send the contents of a file as a notice, the switch
"/NO" may be appended to the file specification:
.s
.c
MAIL NOTICE.TXT/NO TO MARY
.s
	When the interactive entry of a letter at the terminal
is completed (by typing CTRL/Z),
the user is asked whether he would like a reply. A positive response
("YES") will cause the message to be sent as a letter, with replies requested;
all other responses cause the message to be sent a notice.

.hl 2 Name Syntax

The "name" portion of the ARC MAIL  command line
can be of several forms.
.list
.le
The "LAST NAME" of the user as specified
in the RSX-11M user account file.
(See the system manager for a list of user names.)
.le
The UIC of the person to receive the mail:
.s
.c
MAIL to [n,m]
.le
A mailing list:
.s
.c
MAIL to _@filespec
.s
where "filespec" is a valid RSX file specification of a file
containing one of either of the above names per record (also see
section 1.2.3).
.le
A list of any or all of the above, separated by
commas, spaces, or tabs, for example:
.s
.c
MAIL To [12,10],SYSTEM ,_@LIST
.els
All of the above forms may be used following the "TO" in the 
single-line command, or after the "WHO to?" prompt.

.hl 2 Reusable Mailing Lists

As stated earlier, "NAME" can consist of a valid RSX
file specification preceded by an at-sign (_@). Files used in this
way are termed "mailing lists", supplying a means of sending mail
to a predefined list of users.

These mailing lists can contain qualifiers to provide
the ability to mail to only selected names in the
mailing list. This is accomplished by use of a switch specification
on the file specifier, with corresponding qualifiers in the records
of the mailing list. Each switch specifier must be two characters
long, and these characters are matched against the first two 
characters of the qualifiers in the file. Only those names with
quaifiers matching a switch value will be used. For example, if the file:
.s
.c
MAILING.MLS
.s
contains the following records:
.s
.i 10
BOB SYSTEM DOCUMENTS
.i 10
CAROL DOCUMENTS
.i 10
TED
.i 10
ALICE SYSTEM
.s
then if no switch is specified with the file name, all four persons
will receive the mail. However, if
.s
.c
_@MAILING.MLS/SY
.s
is specified, then only Bob and Alice will receive the mail. If
.s
.c
_@MAILING.MLS/DO
.s
is specified, then only Bob and Alice will receive the mail. And
finally, if
.s
.c
_@MAILING.MLS/SY/DO
.s
is specified, then only Bob, Carol, and Alice will receive the mail.

If an asterisk ("*") is used as a qualifier in a
record, then that person will receive the mail regardless of the switch
specification on the file name. Therefore, if the records of the mailing list
are:
.tp 6
.s
.i 10
BOB SYSTEM DOCUMENTS
.i 10
CAROL DOCUMENTS
.i 10
TED *
.i 10
ALICE SYSTEM
.s
then Ted would receive the mail in all of the above examples.

Certain defaults apply to unspecified portions of the mailing
list file specification, and are given below:
.s
.lm +7
.tp 10
.ts 30
.nofill
device:	SY0:
UIC:            The current UIC
file name:      (no default)
file type:      MLS
version number: The highest version number
.fill
.s
.lm -7

.lm -5
.ap
.hl 1 Receiving Mail

There are two methods by which a user can determine
if there is mail for him in his computerized mailbox. The 
first allows the user to find out precisely how much mail
is waiting for him in his mailbox:
.s
.c
>MAIL _?
.s
Note that the question mark ("_?") must be separated from the
word "MAIL" by a space or tab. This command
informs the user of the number of letters, notices, and replies
in his mailbox, and the total number of lines they occupy.
A "beep" is issued to the terminal if there is mail in the mailbox
to attract the user's attention if this command is used in a
"LOGIN.CMD" file (see section 1.5.1).

The second command actually reads the mail in the mailbox:
.s
.c
>MAIL me
.s
This command lists the mail on the user's terminal, and requests
replies if necessary.

.lm +5
.hl 2 Description of Received Mail

All mail, whether a letter, notice, or reply, is entered into the
user's mailbox precisely as entered by the sender except that:
.list
.le
each line is preceded with a space character, thereby formatting the contents
of the mailbox so that each piece of mail can be easily distinguished by the
header line.
.le
each mail entry (i.e. letter, notice, or reply) is preceded by a header line
indicating the day of the week, the month, the day of the month, and the
year that the mail was sent, the name of the person who sent the mail, and
an indication as to what type of mail it is. For example:
.s
WED#NOV#26/81#12:24#>REPLY<##[216,010]#ALEX
.s
shows that on Wednesday, November 26, 1981 at 12:24, the user Alex
(whose UIC is [216,10]) replied to a letter that was sent to him.
The contents of his reply would follow the header.
.els

It is possible that a user may send mail while his
terminal's default UIC is different from his login UIC. If the
default UIC does not correspond to an entry in the RSX user
account file, ARC MAIL  will indicate that UIC, and 
use the name:
.s
.c
MYSTERY mailer
.s
as in the following example:
.s
SUN#JAN#16/81#16:04#>NOTICE<#[363,210]#MYSTERY#MAILER
.s

.lm +3
.hl 3 Letters
Letters are distinguished from notices and replies by having the
words:
.s
.c
ARC MAIL 
.s
in the header line of the mail entry. A letter implies
an immediate reply is desired by the sender. The reply is requested
automatically. Once the entire letter has been listed, the user is prompted
for a reply, to be directly entered, just as if he were entering a letter.
No reply is requested if the sender is the same
as the receiver, or if the sender is a MYSTERY mailer.
.hl 3 Notices
Notices are distinguished from letters and replies by
having the word:
.s
.c
>NOTICE<
.s
in the header line of the mail entry. Notices are treated the same as
letters, but no reply is requested.
.hl 3 Replies
Replies are distinguished from letters and notices by 
having the word:
.s
.c
>REPLY<
.s
in the header line of the mail entry. The header is then followed
by a number of "recap" lines which are the first lines (including the
header) of the the letter that was originally sent. These recap lines
are preceded with a tab character and an asterisk ("*") to differentiate
them from the actual reply. The number of recap lines shown is determined
by the system manager.
(Generally, the number of recap lines is equal to two: the header, and the
first line of the letter.)
.lm -3
.hl 2 Saving Received Mail

After the contents of the user's mailbox have been listed,
ARC maill asks:
.s
Save this mail?
.s
If this is answered "YES" (or "Y") then ARC MAIL  asks:
.s
Where is your mailbag?
.s
to which the user should reply with a valid RSX file specification.
If not explicitly given, the following defaults apply:
.s
.lm +7
.ts 30
.nofill
device:	SY0:
UIC:            Current UIC
file name:      MAILBAG
file type:      TXT
version number: Most recent version
.fill
.s
.lm -7
If the file specified exists, then the contents of the mailbox
file are appended to the mailbag file; if it does not exist,
it is created and filled with the contents of the mailbox.
Confirmation of the name of the mailbag file
is given, and the mailbox is emptied.

If a user indicates that he does not wish to save his
mailbox, the mailbox is emptied. All mail is left in the mailbox
if a null response (i.e. a carriage return) is given. All other responses
are flagged as being in error, the alternatives are listed, and the question
is asked again.

.lm -5
.ap
.hl 1 Error Recovery

The errors that can result from normal use of ARC MAIL 
are listed below with a brief
description of what they represent, and what should be done to recover.
.s
.lm +10
.i -10
MAIL - Account entry for "xxxxxxxxxx" not found
.break
The name specified could not be found in the system's user account file.
Retry using  proper account name.
.s 2
.i -10
MAIL - Account file open failure
.break
Difficulties were encountered when trying to access the system's user account
file. Try again later, and if the problem persists, notify the system manager
immediately.
.s 2
.i -10
MAIL - Account name syntax error in "xxxxxxxxxx"
.break
The name specified is not a valid account name. Retry using the proper
account name.
.s 2
.i -10
MAIL - File name syntax error in: "xxxxxxxxxxx"
.break
The file name given is not a valid RSX file specification. If the
name represents a letter file, reenter the command with a valid file
specification. If the name of a mailing list is in error, the letter
will be retained.
.s 2
.i -10
MAIL - I/O error N at M
.break
This message indicates that a general I/O error was encountered
at location m. n is the standard RSX I/O error code, and if preceded
by a "DR" it indicates a standard directive error code. Execution
of the task is terminated.
.s 2
.i -10
MAIL - Standing in line to mail to "xxxxxxxxxx"
.break
The mailbox of the receiver is being referenced by another user.
ARC MAIL  will pause and try again a few times (see next message).
.s 2
.i -10
MAIL - Unable to mail to "xxxxxxxxxx"
.break
ARC MAIL  was not able to deliver the mail to the desired user
(see previous message).
Try again later; if possible, the letter is retained.
.s 2
.i -10
Proper command syntax is ->mail [from] [to person]
.break
The command as entered is not recognizable. Enter the command
in the proper syntax.
.s 2
.i -10
Sensing incoming mail - will wait till it is received
.break
When attempting to read your own mail, incoming mail was sensed.
ARC MAIL  will wait for the incoming mail.
.s 2
.i -10
Unrecoverable Mail file error
.break
ARC MAIL  was not able to access your mailbox at this time.
Wait a while and try again. If the problem persists, notify the
system manager.
.s 3
.lm -10
If the utility was not able to deliver mail to a user, an
attempt is made to retain the letter in a file. If the letter is
retained, a message of the form:
.s
.c
Letter retained in "xxxxxxxxx".
.s
is printed at the terminal confirming the file name of the letter.
.hl 1 Helpful Hints

The following are some useful pointers for the use of
ARC MAIL  which the authors
of this document feel would be helpful to most users.
.lm +5
.hl 2 Check Mail at LOGON

	The HELLO task for RSX-11M V4.0 has the ability  to
invoke an indirect command file (LOGIN.CMD) each time a user logs on
to the system. By inserting the command:
.s
.c
MAIL ?
.s
into that file, the user is automatically informed if any mail is in his
mailbox. Note that a "beep" will be issued at the terminal if there is
mail in the mailbox.  Alternately, a HELLO patch automatically notifies
the user of waiting mail at logon, or one can have LB:[1,2]SYSLOGIN.CMD
do a .TESTFILE on LB:[10,1] for the correct directory file existing prior
to issuing a MAIL ?.
.hl 2 Reminders or "CARBON COPIES"

ARC MAIL  allows a user to deposit new mail into his own mailbox
simply by sending to his own account name. In this way, a user can send
himself personal reminders or "carbon copies"
which he can read at later time.
.hl 2 Memo Distribution

Because of the versatility of the ARC MAIL  mailing list, it
is generally more efficient to have a single mailing list containing the
name of all users to whom mail is generally sent. Then a subset of this
list can be specified by use of a switch entry. In fact, several subsets
can be specified, some of which may overlap. In this way, memorandums of
general information, as well as those directed to a specific group of people
can be sent using a single mailing list. Contact the system manager to see
if such a file is available.
.lm -5
.hl 1 Sample Mailing Sessions

This section gives a series of examples in the
use of ARC MAIL .
.hl 2 Sending Mail
.list
.le Simple single-line command
.s
.nofill
>MAIL LETTER TO SYSTEM
.s
.fill
(mails the file "SY0:LETTER.TXT;" to the user whose last name
(as specified in the RSX user account file) is SYSTEM.)
.le Make up a letter at the terminal
.s
.nofill
>MAIL TO MARY
Letter>This is a short letter I am
Letter>mailing to Mary. When I get her
Letter>reply, I'll know she has read it.
Letter><CTRL/Z>
.s
Do you want a reply? YES
.fill
.s
.le Send a Prepared Letter
.s
.nofill
>MAIL LETTER/NO
WHO TO? SYSTEM
WHO TO? PETE
WHO TO? <CTRL/Z>
.fill
.s
(mails "SY:LETTER.TXT;" as a notice (no reply requested)
to SYSTEM and to PETE.)
.els
.HL 2 Checking Mailbox
.s
.nofill
>MAIL ?
You have 3 letters, 2 notices and 2 replies in 32 lines.
.s 1
>
.s
.fill
.HL 2 Receiving Mail
.nofill
.s
>MAIL ME
.NUMBER Chapter 2
.chapter Installation Procedures

The procedures described in this chapter are for the
generation of the ARC MAIL  Inter-user Message Transfer
Facility uder an RSX-11M V4.0 multi-user system.
.HL 1 Task Building

ARC MAIL  is distributed as a completed object module
library (MAIL.OLB) and if no changes are required, the library
can be used as is for the building of the ARC MAIL  task.

Triial alterations can be made, however, if it appears necessary
to modify the function of certain portions of ARC MAIL .
.list
.le
REPLIN is a symbolic value defined within the module ME which
specifies the number of recap lines that are to be included in the user
replies. The distribution has the value:
.s
.c
REPLIN=2
.s
To alter that value, the module (located in the file: MAIME.MAC)
must be edited and reassembled with a different definition of REPLIN.
The module ME is the only module affected. (The indirect command
file MAIASM.CMD is supplied to assemble any module and replace
it in the ARC MAIL  object library.)
.le
MAXLIN is a symbolic value which defines the maximum length of a line
allowed in ARC MAIL .  In the distribution:
.s
.c
MAXLIN=132
.s
The value is defined in one of the macros contained in the ARC MAIL 
macro library. In order to modify the value of MAXLIN, the macro
"MAIGBL" must be extracted from the macro library, modified, and then
re-inserted into the library. Rather then specify all the modules that
must be reassembled, let's say that all source modules provided in
the distribution must be reassembled and replaced in the object library.
.le
NOTIFY is a symbolic value used in conjunction wth the ARC MAIL 
ancilliary task which notifies logged-on users of incoming mail. It is
used as a conditional assembly parameter for the generation of code
necessary to invoke the ancilliary task (see section 2.2). The object library
as distributed supports the initiation of the ancilliary task.
NOTIFY is defined in the macro "MAIGBL" in the ARC MAIL 
macro library. In order to remove the code for initiation of the
ancilliary task, that macro must be extracted from the library, modified
to remove the definition of the symbol, and re-inserted into the
macro library. Then the module MAIL (in the file "MAIMAIL.MAC")
must be assembled and replaced in the object library. Normally, only those
systems which do not support the RSX send (SDAT$) and receive
(RCVD$) data directives will require reassembly of this module.
.le;ACCNUM is set via a global patch in the task build command files for
MAIL and MAITSK.  If ACCNUM=1, then MAIL send out the user-unique account
number in the send packet to MAITSK (MAI...).  If MAI...#can not track down
the user via the logon UIC and ACCNUM=1, it checks the UCB extension
field U.ACN to see if account numbers match.  The UCB extension fields only
exist if KMS accounting has been SYSGENED into the system.
.els
	When the object module library is ready for the task build,
it is only necessary to modify the supplied build file (MAITKB.CMD) to
indicate the desired "POST OFFICE LOCATION". There is a global patch
specified in the command file which is used to indicate the location of
all the users' mailboxes. The command file distributed assumes that the
mailboxes are to reside on "DM0:[10,3]".
.hl 1 Installation of Ancilliary Tasks
.s 2
.c
.lm -5

MAITSK is installed as MAI...  It is an executive privilege task and must
be rebuilt each SYSGEN.  Furthermore, it has conditional code which is used
to determine the offset in the UCB for U.ACN depending on whether the system
has multiple/alternate CLI support or just vanilla flavor multi-user
protection.  If a user wishes to sysgen both types of systems, MAITSK must
be assembled for each version of the system with the correct RSXMC.MAC
The command file assumes that RSXMC.MAC resides on SYSUIC.  This 
probably is not the case but was chosen to force the user to find and place
a correct version of RSXMC.MAC in a place easy to remember.  It is never
a good idea to ever assemble an executive privileged task with the wrong
RSXMC.MAC file.