ARC MAIL INTER-USER MESSAGE TRANSFER FACILITY ATMOSPHERIC SCIENCES DIVISION ALBERTA RESEARCH This manual describes ARC MAIL Version 781123 ARC MAIL INTER-USER MESSAGE TRANSFER FACILITY Table of Contents 0.1 Introduction 1.0 User's Guide 1.1 General Command Syntax 1.2 Sending Mail 1.2.1 Preparing a letter 1.2.2 Name syntax 1.2.3 Reusable mailing lists 1.3 Receiving Mail 1.3.1 Description of received mail 1.3.2.1 Letters 1.3.2.2 Notices 1.3.2.3 Replies 1.3.2 Saving received mail 1.4 Error Recovery 1.5 Helpful Hints 1.5.1 Check mail at log-in and log-out 1.5.2 Reminders or "carbon copies" 1.5.3 Memo distribution 1.6 Sample Mailing Sessions 2.0 Installation Procedures 2.1 Task Building 2.2 Installation of Ancilliary Tasks Page 2 ARC MAIL INTER-USER MESSAGE TRANSFER FACILITY 0.1 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. This manual describes ARC MAIL version 781123. 781123 WK, MJ CHAPTER 1 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. 1.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: >MAIL [letter] [TO name] where the square brackets enclose an optional portion of the command line. user's guide Page 1-2 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. TO is required if a name is specified. 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. 1.2 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. 1.2.1 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 80. characters per line.) Certain defaults apply to portions of the file specification which are not explicitly given: device: SY0: UIC: the current UIC filename: (no default) file type: TXT version number: the highest version 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" user's guide Page 1-3 may be appended to the file specification: MAIL NOTICE.TXT/NO TO MARY 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 negative response ("NO") will force the message to be sent as a notice; all other responses cause the message to be sent as a letter, with replies requested. 1.2.2 NAME SYNTAX The "name" portion of the ARC MAIL command line can be of several forms. 1. 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.) 2. The UIC of the person to receive the mail: MAIL TO [n,m] 3. A mailing list: MAIL TO @filespec 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). 4. A list of any or all of the above, separated by commas, spaces, or tabs, for example: MAIL TO [12,10],SYSTEM ,@LIST All of the above forms may be used following the "TO" in the single-line command, or after the "WHO TO?" prompt. 1.2.3 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 user's guide Page 1-4 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: MAILING.MLS contains the following records: BOB SYSTEM DOCUMENTS CAROL DOCUMENTS TED ALICE SYSTEM then if no switch is specified with the file name, all four persons will receive the mail. However, if @MAILING.MLS/SY is specified, then only Bob and Alice will receive the mail. If @MAILING.MLS/DO is specified, then only Bob and Alice will receive the mail. And finally, if @MAILING.MLS/SY/DO 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: BOB SYSTEM DOCUMENTS CAROL DOCUMENTS TED * ALICE SYSTEM then Ted would receive the mail in all of the above examples. Certain defaults apply to unspecified portions of user's guide Page 1-5 the mailing list file specification, and are given below: device: SY0: UIC: the current UIC file name: (no default) file type: MLS version number: the highest version number 1.3 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: >MAIL ? 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: >MAIL ME This command lists the mail on the user's terminal, and requests replies if necessary. 1.3.1 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: 1. each line is preceded with a tab character, thereby formatting the contents of the mailbox so that each piece of mail can be easily distinguished by the header line. 2. 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 user's guide Page 1-6 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: WED NOV 26/78 12:24 >REPLY< [216,010] ALEX shows that on Wednesday, November 26, 1978 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. 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: MYSTERY MAILER as in the following example: SUN JAN 16/78 16:04 >NOTICE< [363,210] MYSTERY MAILER 1.3.1.1 Letters - Letters are distinguished from notices and replies by having the words: ARC MAIL 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. 1.3.1.2 Notices - Notices are distinguished from letters and replies by having the word: >NOTICE< in the header line of the mail entry. Notices are treated the same as letters, but no reply is user's guide Page 1-7 requested. 1.3.1.3 Replies - Replies are distinguished from letters and notices by having the word: >REPLY< 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.) 1.3.2 SAVING RECEIVED MAIL After the contents of the user's mailbox have been listed, ARC MAILL asks: SAVE THIS MAIL? If this is answered "YES" (or "Y") then ARC MAIL asks: WHERE IS YOUR MAILBAG? to which the user should reply with a valid RSX file specification. If not explicitly given, the following defaults apply: device: SY0: UIC: current UIC file name: MAILBAG file type: TXT version number: most recent version 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 user's guide Page 1-8 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. 1.4 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. MAIL - ACCOUNT ENTRY FOR "XXXXXXXXXX" NOT FOUND The name specified could not be found in the system's user account file. Retry using proper account name. MAIL - ACCOUNT FILE OPEN FAILURE 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. MAIL - ACCOUNT NAME SYNTAX ERROR IN "XXXXXXXXXX" The name specified is not a valid account name. Retry using the proper account name. MAIL - FILE NAME SYNTAX ERROR IN: "XXXXXXXXXXX" 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. MAIL - I/O ERROR n AT m 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. MAIL - STANDING IN LINE TO MAIL TO "XXXXXXXXXX" The mailbox of the receiver is being referenced by another user. ARC MAIL will pause and try again a few times (see next message). MAIL - UNABLE TO MAIL TO "XXXXXXXXXX" user's guide Page 1-9 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. PROPER COMMAND SYNTAX IS ->MAIL [FROM] [TO PERSON] The command as entered is not recognizable. Enter the command in the proper syntax. SENSING INCOMING MAIL - WILL WAIT TILL IT IS RECEIVED When attempting to read your own mail, incoming mail was sensed. ARC MAIL will wait for the incoming mail. UNRECOVERABLE MAIL FILE ERROR 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. 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: LETTER RETAINED IN "XXXXXXXXX". is printed at the terminal confirming the file name of the letter. 1.5 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. 1.5.1 CHECK MAIL AT LOG-IN The HELLO task for RSX-11M V3.1 has the ability to invoke an indirect command file (LOGIN.CMD) each time a user logs on to the system. By inserting the command: MAIL ? 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. user's guide Page 1-10 1.5.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. 1.5.3 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. 1.6 SAMPLE MAILING SESSIONS This section gives a series of examples in the use of ARC MAIL. 1.6.1 SENDING MAIL 1. Simple single-line command >MAIL LETTER TO SYSTEM (mails the file "SY0:LETTER.TXT;" to the user whose last name (as specified in the RSX user account file) is SYSTEM.) 2. Make up a letter at the terminal >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> _______ user's guide Page 1-11 DO YOU WANT A REPLY?YES __ ___ ____ _ ______ 3. Send a prepared letter >MAIL LETTER/NO WHO TO?SYSTEM ___ ___ WHO TO?PETE ___ ___ WHO TO? ___ ___ (mails "SY:LETTER.TXT;" as a notice (no reply requested) to SYSTEM and to PETE.) 1.6.2 CHECKING MAILBOX >MAIL ? YOU HAVE 3 LETTERS, 2 NOTICES AND 2 REPLIES IN 32 LINES. ___ ____ _ ________ _ _______ ___ _ _______ __ __ ______ > 1.6.3 RECEIVING MAIL >MAIL ME CHAPTER 2 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 V3.1 multi-user system. 2.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 protions of ARC MAIL. 1. 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: REPLIN=2 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.) 2. MAXLIN is a symbolic value which defines the maximum length of a line allowed in ARC MAIL. In the distribution: MAXLIN=80. 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 INSTALLATION PROCEDURES Page 2-2 library. 3. 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. 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 "DM1:[10,3]". 2.2 INSTALLATION OF ANCILLIARY TASKS NOT COMPLETED Table of Contents 0.1 INTRODUCTION . . . . . . . . . . . . . 2 1.0 user's guide . . . . . . . . . . . . . 1-1 1.1 GENERAL DESCRIPTION . . . . . . . . . . 1-1 1.2 SENDING MAIL . . . . . . . . . . . . . 1-2 1.2.1 PREPARING A LETTER . . . . . . . . . . 1-2 1.2.2 NAME SYNTAX . . . . . . . . . . . . . . 1-3 1.2.3 REUSABLE MAILING LISTS . . . . . . . . 1-3 1.3 RECEIVING MAIL . . . . . . . . . . . . 1-5 1.3.1 DESCRIPTION OF RECEIVED MAIL . . . . . 1-5 1.3.1.1 ^LETTERS . . . . . . . . . . . . . . . 1-6 1.3.1.2 ^NOTICES . . . . . . . . . . . . . . . 1-6 1.3.1.3 ^REPLIES . . . . . . . . . . . . . . . 1-7 1.3.2 SAVING RECEIVED MAIL . . . . . . . . . 1-7 1.4 ERROR RECOVERY . . . . . . . . . . . . 1-8 1.5 HELPFUL HINTS . . . . . . . . . . . . . 1-9 1.5.1 CHECK MAIL AT LOG-IN . . . . . . . . . 1-9 1.5.2 REMINDERS OR "CARBON COPIES" . . . . . 1-10 1.5.3 MEMO DISTRIBUTION . . . . . . . . . . . 1-10 1.6 SAMPLE MAILING SESSIONS . . . . . . . . 1-10 1.6.1 SENDING MAIL . . . . . . . . . . . . . 1-10 1.6.2 CHECKING MAILBOX . . . . . . . . . . . 1-11 1.6.3 RECEIVING MAIL . . . . . . . . . . . . 1-11 2.0 INSTALLATION PROCEDURES . . . . . . . . 2-1 2.1 TASK BUILDING . . . . . . . . . . . . . 2-1 2.2 INSTALLATION OF ANCILLIARY TASKS . . . 2-2