Trailing-Edge - PDP-10 Archives - BB-P527A-BM - documentation/msinst.mem
There are 3 other files named msinst.mem in the archive. Click here to see a list.

                     DECmail/MS Installation Guide

           This document reflects DECmail/MS version 10(2124)

                             December, 1982


     This document describes how  to  install  DECmail/MS  on  either  a
TOPS-10 or a TOPS-20 system.  Where references to other software modules
are required, we refer the reader to the appropriate  documentation  for
the  module  in  question.   We  assume that the reader is familiar with
operating system commands and at least  one  editor,  and  can  compile,
link, and save programs based on instructions in a batch control file.

     The installation instructions are divided into two  sections.   The
first  section describes installation of DECmail/MS on a TOPS-10 system.
The second part  describes  installation  of  DECmail/MS  on  a  TOPS-20
system.   Each section ends with an Installation Certification Procedure
(ICP).  The ICP is a simple, manual procedure you can perform to  assure
yourself  that you've correctly installed all the required pieces of the
software and that the product is functioning properly.

     Please read this entire document through before beginning your  in-


               Before  installing  DECmail/MS,  be   sure
               you've read the Beware file for DECmail/MS
               completely.    It   contains    cautionary
               notices   and   monitor  patches  required
               before installing DECmail/MS.


     There are three forms of distribution tape for DECmail/MS:

     1.  DECmail/MS for TOPS-10 systems
DECmail/MS Installation Guide                                     Page 2

     2.  DECmail/MS for TOPS-20 systems, local mail only

     3.  DECmail/MS for TOPS-20 systems, with network mail

     Each tape contains three savesets.  The first saveset contains doc-
umentation  (such  as  this  file);   the  second  saveset  contains the
executable images you install on your system;   and  the  third  saveset
contains  REL  files  that are used to build the software.  You need not
keep the REL files online, or do  anything  with  them  at  installation
time.  They are supplied in order to provide a base on which patches may
be installed, should any patches be necessary.

     One of the files in the first saveset is called MS.DIR.  This is  a
checksummed  directory  of the tape.  Before proceeding with the instal-
lation, take a checksummed directory  of  your  tape,  and  compare  the
checksums  you  get  with  the  checksums  in MS.DIR.  Except for MS.DIR
itself, the checksums should match.  If they do  not,  you  may  have  a
damaged tape;  contact Digital for a replacement.


3.1  Installation Instructions

     There are five basic steps to the  installation  of  DECmail/MS  on
TOPS-10 systems.  They are:

      o  Step 1 - Compile and link  LGNMS  to  LOGIN   (7.01  and  7.01A

      o  Step 2 - Enter MS in PRVTAB   (7.01 and 7.01A only)

      o  Step 3 - Define the MS monitor command   (7.01 and 7.01A only)

      o  Step 4 - Install files

      o  Step 5 - Create STD:USERS.TXT

3.1.1  Step 1 - Compile And Link LGNMS To LOGIN -

     LGNMS is a module which, when linked with LOGIN (the CUSP that logs
timesharing  users  in  to  the system), notifies users when they log in
that they have new mail.  The way you link it to LOGIN  depends  on  the
version of LOGIN you have.
DECmail/MS Installation Guide                                     Page 3  Rebuilding LOGIN -

     Before compiling and linking LGNMS, you  must  recompile  LOGIN  so
that  it  calls LGNMS.  You will find instructions for recompiling LOGIN
in the BUILD.CTL file distributed with the monitor.  Look  for  the  tag
LOGIN::,  which  precedes  the section of the control file that rebuilds

     The way to recompile LOGIN with the LGNMS  hook  depends  on  which
version of LOGIN you have.  LOGIN Version 61(751) -

     LOGIN version 61(751) has the LGNMS hook, but enclosed in a  REPEAT
0.   Look for the PUSHJ P,RNMAIL## in LOGIN.MAC, and remove the REPEAT 0
conditional around it.  Now recompile LOGIN.


        .COMPILE/COMPILE FACTOR.MAC  LOGIN Version 62(1005) -

     LOGIN version 62(1005) has a  conditional  assembly  switch  called
FTMAIL  instead  of  the  REPEAT 0.  Just set FTMAIL to -1 and recompile



     One of the output files produced when you recompile  LOGIN  is  the
LOGIN  universal file, LGNUNV.UNV.  Using this file (just make sure it's
in the directory you're working from), compile LGNMS.MAC from the  tape,
producing LGNMS.REL.


DECmail/MS Installation Guide                                     Page 4  Link LGNMS With LOGIN -

     Once you've compiled LOGIN and LGNMS successfully,  link  them  to-
gether.   Refer  to the batch control file (BUILD.CTL) shipped with your
monitor;  there is a tag called LOGIN::  that precedes the  LOGIN  build
procedure.   Follow  the  procedure  documented there for linking LOGIN,
except that you must add the module name LGNMS to the LINK command line.
Install the LOGIN.EXE thus created on SYS:.


        .R LINK

3.1.2  Step 2 - Enter MS In PRVTAB -

     Under TOPS-10, version 10 of DECmail/MS delivers mail by  appending
each  message directly to the end of each recipient's MAIL.TXT file.  In
order to have the privileges to do this (since the recipient's  MAIL.TXT
resides  in  a  different  PPN  than the sender's), MS must run with the
JACCT bit.  To accomplish this, MS must be entered in the monitor  table

     PRVTAB is a table which is defined in COMCON.MAC.  Edit  COMCON.MAC
and find the label PRVTAB.  The beginning of this table looks like this:


        SIXBIT  /LOGIN/
        SIXBIT  /SPRINT/

Add the following line anywhere in the table:

        SIXBIT /MS/

Ordering of the entries in the table is not significant,  so  this  line
may appear anywhere in PRVTAB.

3.1.3  Step 3 - Define The MS Monitor Command -

     To define the MS monitor command, edit the file COMMON.MAC and look
for the definition of the NAMES macro.  The beginning of this definition
looks like this:

DECmail/MS Installation Guide                                     Page 5


The following line must be added to the definition of the NAMES macro:

        C       MS,RUNAME,RUNFLG

Ordering of the entries in this macro is not significant, so  this  line
may be added wherever you like.  Just be sure it's not inserted inside a
conditional which is turned off in your monitor.

     Now that  you've  edited  COMCON.MAC  and  COMMON.MAC,  follow  the
instructions  in  the  TOPS-10 Monitor Installation Guide, and build and
install  your  new  monitor.    Briefly,   this   involves   recompiling
COMMON.MAC, recompiling your configuration-dependent files using the new
version of COMMON.MAC, recompiling COMCON.MAC, and  then  replacing  the
copy  of  COMCON  in  TOP?10.REL  with the one you just assembled (using
MAKLIB), and linking and saving the monitor in the usual way.

3.1.4  Step 4 - Installation Of Files -

     The following files should be copied as indicated:

        File on distribution medium     Where to copy it
        ---------------------------     -------------------
        MS.EXE                          SYS:
        MS.HLP                          HLP:
        MS.INI                          STD:
        MS.DOC                          DOC:

3.1.5  Step 5 - Create STD:USERS.TXT -

     With DECmail/MS, people are referred to  by  name.   Since  TOPS-10
refers  to  people  by  number (PPN), a method for associating names and
numbers is required.  This is the file STD:USERS.TXT.  It  is  a  simple
text  file,  which  you  can  create  with any editor, which defines the
correspondence between usernames and PPNs (Project-Programmer Numbers).

     A USERNAME is a continuous string of  characters;   only  the  fol-
lowing characters are valid in usernames:  letters, digits, hyphens, and

     STD:USERS.TXT is a text file which  contains  one  line  per  user.
Each  line  contains a file structure name, a colon, a PPN, a comma, and
then the username.  PPNs and usernames should be unique (that is,  don't
assign two names to the same PPN, or two PPNs to the same name).
DECmail/MS Installation Guide                                     Page 6


               USERS.TXT  can  contain   at   most   1400
               entries, which means that a TOPS-10 system
               can  support  at  most   1400   DECmail/MS

     Here is a sample USERS.TXT:


     UFDs must exist corresponding to each entry in  STD:USERS.TXT.   If
you  attempt  to send to a user who does not have a UFD corresponding to
the area defined for him in STD:USERS.TXT, then DECmail/MS will  produce
the following error message:

?Can't send message because:  Non-existant UFD


               In order  to  insure  that  a  UFD  always
               exists into which mail can be received, it
               is a good practice to create an empty file
               in  each  UFD  named in USERS.TXT (because
               LOGOUT  normally  deletes   empty   UFDs).
               Protect   this   file   <777>  to  prevent
               accidental deletion.  You may wish to call
               this  file  MAIL.NUL or MAIL.000, or some-
               thing like that, to indicate its purpose.

     Users  who  are  not  registered  in   STD:USERS.TXT   cannot   use
DECmail/MS;   they  can  neither  send nor receive mail.  Running MS for
them will  produce  the  fatal  message  "?You  are  not  registered  in

3.2  Installation Certification Procedure (ICP)

     Before running the ICP you must be sure that  you're  running  with
the  modified  monitor you built, containing the MS command.  This means
that after having built and installed the monitor, you must reload  your
DECmail/MS Installation Guide                                     Page 7

     Make sure that the user list, STD:USERS.TXT, contains an entry  for
PPN [1,2] called "Operator".  Make sure that this entry refers to a file
structure that is always online, and on which a [1,2] UFD exists and has
unused disk space.

     Next make sure that you, the person doing  the  procedure,  has  an
entry  in  STD:USERS.TXT  that also refers to a structure that is online
and on which you have a UFD.  This UFD must be for a PPN that is NOT  in
project 1;  that is, do not run the ICP from any PPN of the form [1,*].

     Log in to your (non-project-1) PPN.  In  response  to  the  monitor
prompt (.), type the MS command.  MS should start up and inform you that
you have no message file.

     If you get the following error message from the monitor in response
to the MS command:


then the MS command has not been correctly  installed.   Check  to  make
sure  that  you  correctly edited COMCON.MAC, and built and loaded a new
monitor containing the MS command.

     If MS complains that it cannot find  STD:USERS.TXT,  check  to  see
that this file is properly installed.

     If MS complains that "?You are not  registered  in  STD:USERS.TXT",
check  USERS.TXT  to  see  if  the  PPN  under which you're logged in is

     If MS complains about the format of USERS.TXT, check  to  see  that
you've followed the instructions for creating this file.

     Once you've successfully started MS up, try  sending  mail  to  the
operator.  The typescript should look something like this:

        To: Operator
        Message (ESC to enter Send Level, ctrl-Z to send, ctrl-K to redisplay,
                 ctrl-B to insert file, ctrl-E to enter editor):

        This is a test message.
        Sending to Operator - OK

     If,  instead  of  typing  "OK"  after  "Sending  to  Operator",  MS
complains  about  a protection violation, then it is running without the
JACCT bit.  Check to make sure that you've installed the MS  command  in
the monitor properly, and that MS appears in the monitor table PRVTAB.
DECmail/MS Installation Guide                                     Page 8

     Once you've successfully  sent  mail  to  the  operator,  have  the
operator  run  MS  and  send you mail back.  Now log out and log back in
again.  LOGIN should give you the following reminder:

        [LGNYHM You have 1 new message;  to receive it, type 'MS READ']

     If you do not get this message, check to insure  that  you've  cor-
rectly  installed  the module LGNMS in LOGIN and that the modified LOGIN
is the one you're running to log in.

     If the above steps  succeed  with  no  problems,  you've  correctly
installed MS and can announce it to your user community.
DECmail/MS Installation Guide                                     Page 9


4.1  Summary

     There are two kinds of DECmail/MS  installation  on  TOPS-20.   The
simplest  installation  is that for local mail only;  this means mail to
other users on the  same  host.   This  installation  is  required.   In
addition,  if  you have other DECSYSTEM-20s in a DECNET network and wish
to be able to exchange messages with users  on  other  hosts,  you  must
install the network mail software.

4.2  Local Mail Only

4.2.1  Installation Instructions -

     For local mail (mail to users on the same host) only, you  need  to
install the following files as indicated:

        File on distribution medium     Where to install it
        ---------------------------     -------------------
        MS.EXE                          SYS:
        MS.HLP                          HLP:
        MAILEX.EXE                      SYS:
        MS.INIT                         SYSTEM:

     You also need to edit SYSTEM:SYSJOB.RUN so  that  it  runs  MAILEX.
Place the following line in SYSTEM:SYSJOB.RUN:


     If you wish to use MS immediately, rather than  waiting  until  the
next  system  reload, you also must start MAILEX under SYSJOB, using the
^ESPEAK command (refer to the DECSYSTEM-20 Operator's Guide  for  infor-
mation on the ^ESPEAK command).


        $^ESPEAK (TO SYSJOB)
         [Please type SYSJOB commands - end with ^Z]
DECmail/MS Installation Guide                                    Page 10

4.2.2  Installation Certification Procedure (ICP) -

     Once you've installed MS, log in and try to send mail to some other
user.  Your typescript should look something like this:

        %No current mail file
        To: Other-user
        Subject: Test message
        Message (ESC to enter Send Level, ctrl-Z to send, ctrl-K to redisplay,
                 ctrl-B to insert file, ctrl-E to enter editor):

        This is a test message.
        Processing mail...
        Local mail delivered OK.

     If you get the following error message:

        ?Could not send to local mailer

then neither MAILER nor  MAILEX  is  running.   Check  the  installation
instructions  for  local  mail  above  and be sure that you've installed
either MAILER or MAILEX and that one of them is running.

     If you get the following message:

        ?MAILER is not running.  Messages not sent.

then MAILER or MAILEX has crashed.  Check to insure that  whichever  one
you are running is running under OPERATOR, so that it has the privileges
it needs.

     Once you've sent mail to some other user, have them log in and read
the  mail.  Then have them send mail back to you.  If this works, you've
successfully installed DECmail/MS for local mail on your  node  and  can
announce it to your user community.
DECmail/MS Installation Guide                                    Page 11

4.3  DECNET Mail Installation

4.3.1  Installation Instructions -

     For a network mail installation,  you  first  do  the  installation
described  above  for local mail.  In addition to MS, however, there are
some ancillary modules, known as  network  mail  (or  netmail)  daemons,
which  do  the work of moving messages around the network for you.  This
section describes the installation  of  the  netmail  daemons,  and  for
DECNET mail, the network database that the DECNET mail daemons require.  DECNET Mail -  Install Network Mail Daemons -

     Install the following files as indicated:

        File on distribution medium     Where to install it
        ---------------------------     -------------------
        DMAILR.EXE                      SYS:
        NMAIL.EXE                       SYS:  Edit SYSTEM:SYSJOB.RUN To Run The Daemons -

     Add the following lines to SYSTEM:SYSJOB.RUN:

        RUN SYS:NMAIL  Start Network Mail Daemons -

     If you wish to begin using network mail  immediately  (rather  than
waiting  for  the next system reload), you must start these two tasks by
hand (SYSJOB will start them automatically on every system reload).  Use
the  ^ESPEAK  command to do this.  Refer to the TOPS-20 Operator's Guide
for a description of the ^ESPEAK command.


        $^ESPEAK (TO SYSJOB)
         [Please type SYSJOB commands - end with ^Z]
DECmail/MS Installation Guide                                    Page 12

        $  Create SYSTEM:DECNET-HOSTS.TXT -

     This file contains command lines  which  define  the  DECNET  envi-
ronment.  It is read by both DMAILR and MS, so it must be protected such
that all users can read it without privileges.  It is a  text  file  and
can  be created with any editor.  Each line defines a host, or a synonym
or alternate path to a host.  Comments (started by exclamation point  or
semicolon) and blank lines, for readability, are allowed.  Defining A Directly Accessible Host -

     A host is directly accessible if it is in the same Phase  III  net-
work  as your host, or in a Phase II network if it is directly adjacent.
To define such a node, just enter its name on a separate line.  No punc-
tuation  is  required;   in  particular,  do NOT terminate the name with
double-colon.  Defining Off-network Hosts (route-through Hosts) -


               This section is applicable only  to  those
               networks  which run the "pass-through", or
               "poor-man's-router"  task,  as  a  gateway
               between  DECNETs.   If  you  have a simple
               network without  gateways,  you  may  skip
               this section.

     Hosts which are not adjacent to your host, in a Phase  II  network,
or  are  not  on  the Phase III network in which your host participates,
must be reached using  the  pass-through  protocol  implemented  by  the
"pass-through",  or  "poor-man's-router"  task (distributed with DECNET,
not with DECmail/MS).  To define such a host you must know  the  routing
path used to reach it.  The entry for such a host is:

<host-name>,<1st-gateway>::<2nd-gateway>:: ... <host-name>::

If your gateway configuration provides  multiple  paths  to  off-network
(Phase  III)  or  nonadjacent  (Phase  II) hosts, you may define all the
paths in the file.  The mail system will try to use them in the order in
which  they  appear  in  the file.  If the first path does not work, the
DECmail/MS Installation Guide                                    Page 13

second path is tried, and so forth, until the mail is delivered  or  all
paths  have  been  tried.   For  example, consider a Phase II network as

                  |               |
                  |               |

As you can see, HOSTA has two possible paths to HOSTF and HOSTE.  So  in
SYSTEM:DECNET-HOSTS.TXT for HOSTA, the following entries should be made:

HOSTE,HOSTB::HOSTC::HOSTF::HOSTE::      ! alternate path
HOSTF,HOSTB::HOSTC::HOSTF::             ! alternate path

Note that the local host must be defined as well.  Also, be careful  not
to forget the trailing double-colon.
DECmail/MS Installation Guide                                    Page 14

     Frequently you will find it useful to define mnemonic  or  humorous
synonyms  for  hosts in your network, especially if the network adminis-
trators have chosen to assign dry or unpopular names to the  hosts.   To
define  a  host synonym, enter the synonym name, an equals sign (=), and
the real name.  Be careful!  The real name must already  have  been  de-
fined earlier in the the file.  For example:

HOSTA                      ! Unimaginative name
ORANGE-PAINTED-PDP10=HOSTA ! More easily remembered name

4.3.2  Installation Certification Procedure (ICP) -

     In order to perform this procedure, you should  have  installed  MS
and the network mail software on two DECSYSTEM-20s connected via DECNET.
Before trying to verify your installation, be sure that the DECNET  link
between the two systems is up and working.

     Log into an account on one system and send mail to an invalid user-
name  on  the other system;  for example, "No-such-user".  Next give the
"net-mail" command to force  the  mail  unspooler  (DMAILR)  to  try  to
deliver  your mail.  You should get an error message from the other node
complaining about the invalid node name.

     For example, if you're on NODEA and the other node is  NODEB,  your
typescript would look something like this:

        %No current mail file
        To: No-such-user at NODEB
        Subject: Test message
        Message (ESC to enter Send Level, ctrl-Z to send, ctrl-K to redisplay,
                 ctrl-B to insert file, ctrl-E to enter editor):

        This is a test message.
        Netmail queued for transmission.
        Sending to NODEB, connect OK,
        ?NMAIL error:  Invalid username in "To:" list:  NO-SUCH-USER

     If you do not get the "connect OK" message, but  instead  get  some
DECNET error message, check to make sure that the connection to NODEB is
working.  If the DECNET error message is "destination process  does  not
exist", check to insure that NMAIL is installed and running on the other
DECmail/MS Installation Guide                                    Page 15

     Once  you've  successfully  executed  this  part  of  the   network
verification,  try  sending mail to a real user on the other node.  Your
typescript should look something like this:

        %No current mail file
        To: Smith at NODEB
        Subject: Test message
        Message (ESC to enter Send Level, ctrl-Z to send, ctrl-K to redisplay,
                 ctrl-B to insert file, ctrl-E to enter editor):

        This is a test message.
        Netmail queued for transmission.
        Sending to NODEB, connect OK, sent OK, deleted.

     Next check to see if the mail unspooler is running OK.  Proceed  as
in  the  previous  example,  except  do NOT give the "net-mail" command.
Wait for the unspooler to deliver the mail.  This should take no  longer
than  30  minutes.   You can check to see if the mail has been delivered
yet by getting a directory listing of your logged-in PS:  directory.  If
the mail has not yet been sent, you will see a file whose filespec is of
the form:


     When this file disappears, the mail has been delivered.   Have  the
user  on the other system to whom you sent the mail log in and run MS to
check to see that he's actually received the mail correctly.

     If  you  encounter  problems  with  this  test,  check   the   file
SYSTEM:DMAILR.LOG.  This file contains a complete log of the unspooler's
activity and should point you to the problem.

     Once you've successfully run these tests,  you  can  be  sure  that
you've  correctly  installed  DECmail/MS and can now announce it to your
user community.

4.4  ARPANET Mail Installation

     DECmail/MS can send and receive mail over the ARPANET as well.  For
information  on  installing the ARPANET software, refer to the TOPS-20AN
Installation Guide.  There is nothing special  that  need  be  done  for
DECmail/MS;  if you install the ARPANET software correctly, as described
in its documentation, DECmail/MS  will  work  with  no  further  actions
required on your part.
DECmail/MS Installation Guide                                    Page 16

4.5  XMAILR (Stanford/MIT Internet Mailer)

     DECmail/MS supports XMAILR, the Stanford/MIT  internetwork  mailer.
XMAILR  is  a  mail delivery daemon which can deliver mail to hosts on a
variety of networks, including DECNET, ARPANET, Chaosnet,  and  Dialnet.
XMAILR is neither supported nor distributed by Digital Equipment Corpor-
ation, and so we cannot claim that  DECmail/MS  will  always  work  with
XMAILR.  We do make an effort to keep DECmail/MS up-to-date with respect
to XMAILR, however.   For  more  information  on  XMAILR,  contact  Mark
Crispin  at  Stanford  University (Admin.MRC @ SU-SCORE.ARPANET).  As of
the writing of this document, DECmail/MS worked correctly  with  XMAILR,
but  did not recognize pseudo-mailbox-names defined by the XMAILBOX pro-
gram.  This capability will probably be  added  to  future  releases  of

     DECmail/MS decides to use XMAILR on a system if and only if:

      o  The file SYSTEM:HOSTS2.BIN exists and is readable.

      o  The file SYSTEM:XMAILR.FLAGS exists and is writeable.

     If these two conditions are not met,  DECmail/MS  attempts  to  use
supported methods of delivering the mail.