Omega Software Solutions presents: gmail/OL Off-Line mail retrieval, reading and replying for the Apple //gs and IBM-PC. gmail/OL, (C) 1993 Gregg D. Brekke, Omega Software Solutions 5638 Lake Murray Blvd., #173 La Mesa, CA 91942 Phone/FAX (619) 465-0421 Licensing Feel free to distribute gmail/OL. All files, including those in the GORP.SRC directory must be included in your distribution. gmail/OL is Shareware. To gain the rights to technical support and updates you must register your copy of gmail/OL. PLEASE SEE THE FILE, REGISTER.DOC, FOR REGISTRATION INFORMATION. Contact Omega Software Solutions for reasonable rates on network, classroom, and corporation licensing agreements. Copyright gmail/OL, (C) 1993 Gregg D. Brekke, Omega Software Solutions gmail/OL is owned by Omega Software Solutions and is protected by the copyright laws of the United States, international treaty provisions, and all other laws pertaining to copyrights. Warranty No warranty is extended to unregistered users of gmail/OL. Unopened software purchased from Omega Software Solutions may be returned to Omega Software Solutions for refund of purchase price. Damaged media or manuals, due to documented shipping mishaps, will be replaced free of charge. Other damages will be replaced with a $5.00 fee for each diskette item, $10.00 for manuals. Trademarks Used in This Manual Apple, Apple //gs, and Macintosh are trademarks of Apple Computer. DOS and MS-DOS are trademarks of Microsoft Corporation. IBM, PC, and IBM-PC are trademarks of International Business Machines. ProLine is a trademark of the Morgan Davis Group. Table of Contents Introduction iv Why use gmail/OL? iv Chapter 1 Getting Started 1 Installation 1 Before You Start... 1 Configuration 4 Usage Notes 6 Machine Specific Installation 6 IRQ Settings on the PC 7 The Signature File 7 Apple //gs File Types 8 Chapter 2 Operation 9 The Main Screen 9 The Mailer Screen 11 The Configuration Screen 13 Chapter 3 GORP and The Modem 14 How GORP Works 14 The Modem Connection 14 Finding a GORP Server 15 Chapter 4 Other Stuff 16 Using gmail/OL from a Shell 16 The 'aliases.gm' File 17 Email and Addressing a Message 17 Troubleshooting 18 Acknowledgments I would like to thank the following people for their help in the programming of gmail/OL: Al Rogers - For criticism, suggestions, compromise, and great beta testing. Jawaid Bazyar - The Apple //gs version of gmail/OL would have never been started without his Modem Manager Toolkit for the Apple //gs. Morgan Davis - For help and allowing me to use an adaptation of his MDSS protocol in GORP. Mark de Jong - The Apple //gs guy who laughed when I wanted to give up. My wife Patsy, for being patient... (& proofreading, & proofreading, ...) Introduction gmail/OL is the programming result of frustration with current email procedures and protocols. Originally designed to interface on my computer with the ProLine Apple // BBS, gmail/OL did not begin as a email retrieval system, it was merely a more efficient reading and replying mechanism for my personal email on my BBS system. Sure this was pretty selfish, but over a period of time the need for others to have access to an efficient means of gathering email from a Bulletin Board or UNIX system became more and more apparent to me. As a result gmail is now gmail/OL, incorporating a system to system communication protocol called GORP (see manual section on GORP for a complete description) to exchange email files via modem. Before writing gmail/OL I looked at various off-line readers and protocols. It seemed to me that most of them required an Masters degree in computer science just to operate the simplest of the off-line readers. gmail/OL is surprisingly easy to use. If you know your email address on your host system and how to log onto that system, you can use gmail/OL. The modem procedures are very easy and all file manipulation is handled by the program. All you need to do is have gmail/OL poll your GORP server to send mail out and get mail in. Mail replies and forwarding are handled by the server machine as if you were logged in to it rather than using gmail/OL. This file exchange is very quick and will greatly reduce the time you spend on-line to the host system. Some acronyms used in this manual are: email - Electronic Mail GORP - Gregg's Off-Line Reader Protocol DOS - Microsoft Disk Operating System Why Use gmail/OL? Imagine if you will... There are no mail carriers. You have to go to the post office to get all of your mail. That isn't so bad, but assume that you also have to read all of your mail and compose all of your responses while you are in the post office. Sure you can go home, but if you have any unfinished correspondence, you must leave the original mail at the post office and return to finish it later. What is worse, your post office charges you for the time you spend inside. That all sounds pretty foreign to us, since we are so used to the postal service's delivery and pick-up system. Yet, this is exactly the scenario most of us go through to use electronic mail. WHY SHOULD EMAIL BE ANY HARDER TO USE THAN THE POSTAL SERVICE? It should be easier. With gmail/OL it is! Off-Line email reading and replying is superior to being on-line for a number of reasons. Mainly though, it is just a better use of your time. Off-Line email gives you the advantage of reading and reply to your email when it is convenient for you, not when it is convenient or cheapest to be connected to your host system. Off-Line email is also better than on-line email for the following reasons: You spend less time on-line to your host system. You save money on phone bills and connection costs. It is relaxing. Read and edit your email at your leisure. There is no pressure of connection charges hanging over your head if you choose to read every message or write a short novel as a reply to one. You can read and edit email faster. On a BBS system, you can only read and edit as fast as your modem can get characters to the screen. You can customize your environment. Select the editor YOU want to use to edit outgoing messages rather than the one or two editors available on your host system. (Macintosh version includesgraphic editor with cut, paste, and more!) You will make your system administrator happy. You will be using the host system less, giving others access to modem lines and system resources. The more time you spend reading and replying to your email, the more you will benefit from gmail/OL and Off-Line reading. Your email will be better composed and thought out. Instead of having the burden of being on-line with your host system for long email sessions, you will have the pleasure of corresponding from your home or office without the worry of interruptions costing you valuable connection time. Enjoy. Gregg D. Brekke Chapter 1 Getting Started It is the intent of this chapter to help you install, configure, and begin to use gmail/OL as quickly as possible. Even if you are an experienced computer user, please read this section to familiarize yourself with the operation of gmail/OL. The last section in this chapter, Usage Notes, contains information about the implementation of gmail/OL on different platforms. Please read this section and follow any instructions pertaining to your type of computer. Installation gmail/OL can be installed in a number of ways. It is small enough that you can run it from a backup of the diskette it was distributed on. The only limitation to running gmail/OL from a diskette is the available space on this media for storing incoming and outgoing messages. Although there is plenty of room on the diskette, should your mail file become very large or if you save many messages for later use, you may run out of room. Extra room can be made available on the backup diskette by deleting the 'gorp.src' directory. Do not delete any other files as they will be needed in the operation of gmail/OL. Hard disk installation is also quite easy. Follow these steps and you should have no problems at all: 1. Make a directory on your hard disk named 'gmail'. 2.Copy all files from the distribution disk into the 'gmail' directory on your hard disk. 3.Make another directory inside the 'gmail' directory on your hard disk called 'out'. This directory will store outgoing messages. Here is a tree of necessary files: ../gmail/ out/ - directory for email replies gmail (DOS: gmail.exe) - main program file gmail.cf - configuration file aliases.gm - email aliases mailfile - email storage file signature - personal signature file tool.mm - Apple //gs version only! In addition to these files, when you first run gmail/OL, the program will create a file containing message pointers named 'gmail.o'. Do not delete this file as it contains important information on messages you have or have not read. Before You Start... This is a tutorial designed to help you set up gmail/OL before you get started reading and sending email. It is important for you to follow these instructions carefully to ensure your email is formatted correctly and gmail/OL operates as designed. Complete descriptions of each of the fields mentioned here are in the following section, "Configuration". To begin with, start gmail/OL. (DOS version only... You must change directory, 'cd', to the location of the gmail.exe file before launching gmail/OL. The files gmail.bat and gmail.pif are included on the distribution disk to facilitate this upon launch.) If you haven't used gmail/OL before, there should be only one message on the main screen. It is a README file formatted as an email message and will give you up to date information on any operational changes to gmail/OL. Press RETURN to read this update. Press the SPACE bar to see the next page until the 'more' prompt doesn't show up at the bottom of the screen. Now press 'I' to return to the index of your mail messages. Press 'C' to start the configuration editor. There are values in each of the fields, but they have only been put there to provide a starting point. 1. The first field is 'Mail file name/path:'. This tells gmail/OL the name of or path to the file you would like to keep your email in as it is received from the GORP server. DOS: Unless you have an alternate mail file, you need not change this value. Go to step 2. Apple //gs: If you are running gmail/OL from a copy of the distribution disk, you do not need to change this value; go to step 3. If you are running from a hard disk press RETURN to edit this field. Press CONTROL-X to delete this field. Now enter the FULL path name to the hard disk directory you have installed gmail/OL in to. Then add the word 'mailfile' to the end of this path. (Apple //gs continued) Full path name: /hd/gmail/ Enter in this field: /hd/gmail/mailfile Press RETURN to permanently change this field. 2. Press the down arrow (or 'J') to advance to the 'Outgoing message path:' field. This tells gmail/OL where to store messages you are sending to others via the GORP server. DOS: Unless you have an alternate outgoing directory, you need not change this value. Go to step 3. Apple //gs: If you are running gmail/OL from a copy of the distribution disk, you do not need to change this value; go to step 3. If you are running from a hard disk press RETURN to edit this field. Press CONTROL-X to delete this field. Now enter the FULL path name to the hard disk directory you have installed gmail/OL in to. Then add the word 'out' to the end of this path. Full path name: /hd/gmail/ Enter in this field: /hd/gmail/out Press RETURN to permanently change this field. 3. Press the down arrow (or 'J') to advance to the 'Editor to use from shell:' field. This is an editor you can access from the DOS shell (DOS) or programming shell (Apple //gs). DOS: This field is set to 'EDIT' which will use the standard DOS 5.0+ full screen editor. If you have an alternate editor to use such as STEVIE or EMACS you can enter it here. Apple //gs: If you are not running gmail/OL from a programming shell, leave this value as 'none'. gmail/OL will then use its built in editor (Apple //gs version ONLY). See the Usage Notes at the end of this chapter under "Apple //gs File Types" for instructions on using gmail/OL from a programming shell, which allows the use of alternate editors such as EDIT, VI, or EMACS. To change this field press RETURN, then press CONTROL-X to delete the input line. Enter the name of your editor of choice and press RETURN. 4. Press the down arrow (or 'J') to advance to the 'User Full Name:' field. This is the name that will be included with outgoing messages to let the recipient know the real name of the sender. Press RETURN and then press CONTROL-X to delete this field. Enter your full real name... Press RETURN to make this change permanent. 5. Press the down arrow (or 'J') to advance to the 'User Login Name:' field. This is your user name/alias on your GORP server machine. See the "Configuration" section for instructions if you don't know what this field does. Press RETURN and then press CONTROL-X to delete this field. Enter your user name on the GORP server. Press RETURN to make this change permanent. 6. Press the down arrow (or 'J') to advance to the 'GORP Server Site:' field. This is the complete domain name of your GORP server machine. This value is used in your outgoing email message to let others know where to return mail to you. See the "Configuration" section for instructions if you don't know the value for this field. Press RETURN and then press CONTROL-X to delete the field. Enter the domain name of your GORP Server. Press RETURN to make this change permanent. 7. Press the down arrow (or 'J') to advance to the 'Modem Baud Rate:' field. This should be set to the highest baud your modem supports. Press RETURN and then press the right and left arrows to highlight the highest baud rate supported by your modem. Press RETURN to make this change permanent. 8. Press the down arrow (or 'J') to advance to the 'COMM Port:' field. This is the communications port your modem is connected to on your machine. See the 'Configuration' section for more information concerning your machine and this field. Press RETURN and then press the right and left arrows to highlight the communications port your modem is connected to. Press RETURN to make this change permanent. DOS ONLY: Press the down arrow (or 'J') to advance to the 'COMM Port IRQ:' field. This field defaults to the standard IRQ to be used by the COMM port selected above. If you know your IRQ is different, change this field. If you haven't changed your IRQ settings on your internal modem or serial I/O card don't change this field! Press RETURN and then press the right and left arrows to highlight the IRQ number you have assigned to the selected COMM port. Press RETURN to make this change permanent. 9. Press the down arrow (or 'J') to advance to the 'GORP Server Phone Number:' field. This is the phone number to be called to exchange email with your GORP server. See the 'Configure' section for customization instructions for this field. Press RETURN and then press CONTROL-X to delete this field. Enter the phone number to your GORP server. Press RETURN to make this change permanent. 10. Once all the fields on this screen have been changed press 'ESCAPE'. Answer 'Y' to the question 'Save Changes to Configuration File?' to have these changes loaded automatically the next time you start gmail/OL. You are now asked if you want to change the GORP Waitfor/Send lines that facilitate logging gmail/OL into the GORP server. To continue, press 'Y' and enter the Waitfor/Send lines as described in the second half of "The Configuration Screen" in Chapter 2. Press 'N' to get back to the gmail/OL main screen. You now have a minimal configuration established for gmail/OL. To poll your GORP server for email exchange, you must edit the Waitfor/Send lines on the second configure screen. Configuration gmail/OL depends on the file 'gmail.cf' to run. If 'gmail.cf' is not present in the directory where the gmail/OL executable program is, gmail/OL will automatically start the configuration program to have you set the parameters for running gmail/OL. You can also change these parameters while running gmail/OL by selecting the 'Configure' option. The configure screen is described later, but for your convenience here is what all the fields in the 'gmail.cf' file represent: Path to email file Path to OUT directory Shell Editor Your full name Your user name on the host system The domain name of the host system Baud rate of your modem Port modem is connected to IRQ setting of modem port (DOS version only) Phone number of host system Waitfor/Send lines for logging into host system. Path to Email File: The full path name to the email spool file where gmail/OL will store your email in and read it from. Apples /hd/gmail/mailfile DOS c:\gmail\mailfile Path to OUT directory: The full path name to the directory you created to hold outgoing message files to be sent to the GORP host. Apples /hd/gmail/out DOS c:\gmail\out Shell Editor: Used only by DOS and Apple //gs shell versions. Specifies a shell editor that can: 1. Be called from your shell. 2. Accept a filename as an input parameter. Apple Editors- ORCA Edit, emacs, ROSE, vi (GNO/ME Shell) DOS Editors - DOS Edit, emacs, vi, stevie SPECIAL NOTE: When running the Apple //gs shell version of gmail/OL as a S16 file or when using 'windowed' versions of gmail/OL (not covered in this manual), set this field to 'none'. See the "Usage Notes" section later in this chapter for more information on running the Apple //gs shell version of gmail/OL as a S16 file. Your Full Name: Name you want included with your email address so people can identify you as a person rather than a login name on a machine. Gregg D. Brekke Jane Q. Public - Esquire Your User Name on the Host System: Commonly referred to as your login name. The name you send before sending your password to the host system. Email Address User Name greggb@acme.fred.org greggb goofy.disney.com!pluto pluto The Domain Name of Your Host System: The Internet name of your host machine. It is commonly the name that goes after the '@' in your email address. Email Address Domain Name greggb@acme.fred.org acme.fred.org goofy.disney.com!pluto goofy.disney.com Baud Rate of Your Modem: Highest speed, not exceeding 19,200 bps, supported by your modem. Valid entries are: 1200, 2400, 4800, 9600, 14400, and 19200. Modem Port: Lets the communication program know where to send its signals. The following are the only configurations supported by gmail/OL at this time: Apple //gs Printer Port = 1 Modem Port = 2 (default) DOS COM1 = 1 (default) COM2 = 2 COM3 = 3 COM4 = 4 IRQ Setting of COM Port (DOS Version ONLY!): If you don't understand what an IRQ is, don't worry. The default configurations should work. IRQ 2, 3, 4, and 5 are supported for all COM ports. COM1 = 4 (default) COM2 = 3 COM3 = 4 COM4 = 3 Phone Number of Host System: Standard telephone number used when dialing your host system. It doesn't have to start with the 'ATDT' string unless you would like to add any special modem commands. example: AT\\N0DT555-5555 Dials a number with v.32 turned off on an Intel Modem. The backslash '\' must be represented in your dialing string as a double backslash, '\\'. Waitfor/Send lines: The heart of the login script used by GORP to gain access to a GORP server system. The syntax for each of these lines is as follows: \[waitfor] "send" The waitfor string must not be in quotes, just encased in brackets with the starting bracket preceded by a backslash character. The send string must be enclosed in double quotes and follow the waitfor close bracket. Only one Waitfor/Send sequence is allowed on each line of the 'gmail.cf' file. A typical Waitfor/Send sequence will look like this: \[login:] "gorp" \[Password:] "gorpuser" \[Username:] "pluto" \[Password:] "toontown" When gmail/OL has executed all of the Waitfor/Send lines, it assumes it has logged in and will begin transferring email between your system and the GORP server. Usage Notes INSTALLATION Apple //gs: Use the following method from the ORCA or GNO shells to install gmail/OL onto a hard disk. Just insert the gmail/OL distribution disk into a drive and execute the following shell commands. ORCA GNO prefix /hd cd /hd create gmail mkdir gmail prefix gmail cd gmail create out mkdir out copy /gmail/= /hd/gmail cp /gmail/* /hd/gmail DOS: From the DOS shell execute the following commands after inserting the gmail/OL disk into drive a: or b: c: mkdir gmail cd gmail mkdir out copy a:\*.* c:\gmail or copy b:\*.* c:\gmail IRQ Settings (DOS Version Only) IRQ settings on the PC DOS computer control which hardware device has access to system resources at a given time. To make sure these resources don't step on each other, each hardware device is assigned a unique ID that the system uses to identify the device with. Commonly, COM1's IRQ setting is 4 and COM2 is 3. Most PCs come with these two COM ports installed and these IRQ numbers set. If you add an internal modem to be used as COM3 or a tape backup device, these devices also have to have an IRQ assigned to them. Fortunately, the PC has a few spare IRQs that work great for serial (COM) ports. These two IRQs are 2 and 5. Most internal modems and serial cards come with DIP switches or jumper blocks that allow you to change the COM port and IRQ settings. I personally have the case where I have an external 14,400 baud modem connected to COM1, a serial mouse on COM2, and an internal FAX card set to COM3. The above chart of default IRQ values shows that for both COM1 and COM3 the IRQ value is usually 4, which would cause an IRQ conflict. To alleviate this problem, I changed a jumper block on my FAX card to indicate it was to be used as COM3 with IRQ 5. I could have used IRQ 2 instead, but I have other plans for it. Make sure you read your modem or serial port manual before changing these settings. It can be annoying and even hazardous should you not set them correctly. One other consideration when changing information about serial ports, which has nothing to do with the IRQ setting, is the base address. You should never have to worry about these unless you have a really strange or non-standard card. Your hardware manual should mention it, but here are the default settings (the only ones gmail/OL will use) for the base addresses on each COM port: COM1 3F8 COM2 2F8 COM3 3E8 COM4 2E8 'SIGNATURE' File The 'signature' file ('signatur' in the MS-DOS' 8 character file limit) is used to include a short message about yourself or alternate contact routes or annoying ASCII art. The use of a signature file is optional, delete it if you don't want to include it with every email message you send out. See the included 'signature' file on the distribution disk for an example. Apple //gs File Type You can run the Apple //gs version of gmail/OL from either a command shell like ORCA or GNO/ME, or you can run it from the finder. The program file 'gmail' comes on disk as a S16 file for use from the finder. As such, you must specify 'none' in the 'gmail.cf' Shell Editor field. This will use a built in editor when running gmail/OL from the finder. To use gmail/OL from a command shell, execute the following command to change gmail/OL to a shell type executable file: ORCA: filetype gmail exe GNO: chtyp -texe gmail Chapter 2 Operation This chapter is the meat of the manual. It will introduce you to all the functions of gmail/OL's main, mailer, and configuration screens. Included will be reading messages, polling the GORP server, and configuring gmail/OL. You will also take a look at the mailer screen functions, where you can send, save, and reply to messages. The Main Screen Start gmail/OL and look at the main screen. Some important features of the main screen are: The highlighted top bar: -> Arrow pointer to current message. # Message numbers. Date Date message was sent. From Who sent the message. Lines How long is this message anyway? Subject Subject from sender. Each line contains a header summary for messages in your 'mailfile'. Positioning the Current Message Pointer ( -> ) To position the current message pointer on a selected message, press 'K' or 'N' to move down the list or 'J' to move up the list. The Apple //gs version also lets you press the up and down arrows on the keyboard to position the pointer. You can also type in the number of the message you would like to go to. The message number is under the '#' heading. The message pointer will only move if you input a valid message number. gmail/OL allows you to have up to 999 messages in your 'mailfile'. Other Main Screen Commands The functions denoted as mailer functions will be covered more closely in the next section. D - Mark message for deletion. F - Forward message to a user. I - Return to main screen Index if reading a message M - Mail a new message to a user. N - Go to next message R - Reply to sender of current message. S - Save current message to a file. U - Undelete message if marked for deletion. Alt-P (DOS) or Command-P (Apple //gs) - Poll GORP server for email transfer. C - Edit gmail.cf file. Return - View Current Message. J - Position message pointer on next message. K - Position message pointer on previous message. Delete Message Marks message with a 'D'. After quitting program, this message will be deleted from the 'mailfile'. Forward Message - Mailer Function Sends entire message to another user, noting that you forwarded to them and were not the original author. Mail New Message - Mailer Function Lets you compose a new message to another user. Reply to Message - Mailer Function Sends a response to sender of message. Save Message to File - Mailer Function Store message as a text file on disk. Undelete Message If a message is marked for deletion with a 'D', this will undelete it, sparing it from deletion when the program quits. Reading a Message To read a message, position the current message pointer on the number of the message you want to read and press ENTER. A few important header lines are displayed along with the text of the email message. If the email message is longer than one screen, there will be a 'more' prompt at the bottom of the screen. To continue reading the message press the space bar. To return to command mode press 'Q' to quit 'more'. After quitting the 'more' prompt or if the message was less than one screen long you can type 'I' to return to the message header screen, 'N' to read the next message, or any of the commands mentioned above in the main screen commands. Message Marker Next to each message number, just before the date field, there is space for a message marker. This marker can be: N - new and unread messages. U - unread message that wasn't read the last time you used gmail/OL. D - marked for deletion. Space - message has been read and will not be deleted when you quit. Poll the GORP Server To prevent key command mishaps, this is the only main screen command that requires you to press a key sequence to activate it. gmail/OL will dial your GORP server and perform a mail exchange when you select this function. Alt-P (DOS) Command-P (Apple //gs, the 'Command' key was formerly called the 'Open-Apple' key) The Mailer Screen The mailer screen can be accessed from gmail/OL's main screen by pressing one of the following keys: M - Mail a new message to a user. R - Reply to sender of current message. F - Forward message to a user. S - Save current message to a file. When selecting one of the above commands, you will be prompted for additional information before gaining access to the mailer screen's functions. Here is the information you will have to supply for each of the above commands. Mailing a new message: 1. From the main menu press 'M'. 2. Enter the users email address. 3. Enter a subject for the new message. 4. After the editor starts, enter your message. 5. Save your message in the editor and exit the editor. 6. You are now at the mailer screen command menu. Replying to a message: 1. From the main menu press 'R'. 2. gmail/OL automatically picks out the address and subject lines. 3.Answer 'Y' or 'N' to the question asking if you want to include the current message. If 'Y', each line of the message you are replying to, preceded by a '> ', will be included in your response. 4. After the editor starts, enter your message. 5. Save your message in the editor and exit the editor. 6.You are now at the mailer screen command menu. Forward a message: 1. From the main menu press 'F'. 2. Enter the email address to forward the message to. 3. gmail/OL picks out the subject line. 4. You are now at the mailer screen command menu. Save message to a text file: 1.From the main menu press 'S'. 2.Change the name you want the message saved to. 3.Press RETURN to save the file. 4.You are returned to the main menu. Mailer Screen Commands Here are a list of the mailer screen commands: A - Append a text file from disk to the outgoing message. B - Add or change the Bcc: line. C - Add or change the Cc: line. E - Edit the message you have composed so far. I - Include a message (from the main menu) in your reply. S - Send the message (save it in the outgoing directory). T - Change the To: line. W - Write your message to a file. Q - Quit, don't send the message. Z - Change the Subject: line. Append a file: Get a text file and append as part of your outgoing message. This must be a text file or gmail/OL will return unpredictable results. You must enter the full path name to the file unless it is in gmail/OL's home directory. Bcc: line: The Bcc: line is used by the mailer to send a "Blind Carbon Copy". That is, only the persons listed in the Bcc: field know they have gotten the message from you. Use it when you want each recipient of your message to believe they have gotten an original message. Multiple Bcc: recipients can be specified by separating each email address with a space. Contrast this operation with the Cc: line below. Press Control-X to delete the input line and start over. example: Bcc: pluto@goofy.disney.com ed@comp.geek.edu Cc: line: Add a "Carbon Copy" line to your message. This line tells the mailer to send a copy of this message to each person listed in the Cc: line. All of the recipients get the same Cc: line in their message, letting them know the others who have gotten the message. Use the Cc: line when you want to send public information to a group of people. Again, specify multiple recipients by separating each email address on this line with a space. Press Control-X to delete the input line and start over. Edit the message: Edit the message you have composed so far. This allows you to add or revise a message you have already worked on before you send it. DOS and Apple //gs shell versions will launch the editor specified in their gmail.cf file. Desktop versions will launch the built in editor. Include a message: Lets you include a message from the main menu message list in your outgoing message. The message will be imported into your reply with each line preceded by a '> '. After, you can re- enter the editor with the 'Edit' command to add clarification. By default this function will include the message the current message pointer is on. You can override this by specifying a message number to include. Send this message: Saves the message in your outgoing directory for delivery to your GORP host. The message is formatted as standard text with a minimal RFC-822 mail header at the top. This assures mail delivery on all systems using the standard Internet email message format. To: line: Specifies a recipient for your email message. Like the Cc: and Bcc: lines, you can list multiple email addresses on this line, each separated by a space. Press Control-X to delete the input line and start over. Write message to file: Save the message you have composed so far to a file. This will include entered text, appended files, and included messages. Use this function to keep a record of important outgoing messages. You are prompted by this function to enter the name of the file you wish to save it as. Enter this name and press return to save and return to the mailer command screen. Quit: Quit back to the main message screen. If you have not selected to 'Send' the outgoing message it will be lost. Z (change Subject: line) Enter or change the subject line. This line identifies your email's topic to the recipient. Press Control-X to delete the input line and start over. The Configuration Screen Selecting 'C' from the main screen starts the configuration file editor. Although, you could edit the configuration file, gmail.cf, with any text editor, this screen allows you to change the settings of gmail/OL without quitting back to your operating system. You can also add or change Waitfor / Send lines used in connecting to your GORP server through this screen. The basic commands in the configuration screen are: Escape Exit the current configuration screen. Down Arrow (J) Go to next / previous field. Up Arrow (K) Go to next / previous field. Return Accept field for input. Using the Configuration Editor To skip editing the configuration fields and go directly to editing the Waitfor / Send sequence, press ESCAPE and answer 'Y' when prompted. As you use the Up and Down Arrow keys (or K/J) to move the next or previous field, the field descriptor is highlighted. Press RETURN when the field you wish to edit is highlighted and use standard key presses to edit the field. Pressing Control-X deletes the input line and allows you to start over. When you have finished editing the field, press RETURN again and continue moving through the different fields. When you have finished editing all the fields you want to change, press ESCAPE. You will be asked if you would like to save your changes. Answer 'Y' to save them, 'N' to ignore the changes. Next, you are asked if you want to edit the Waitfor / Send fields. If you answer 'Y', the Waitfor / Send editor is started. This editor is similar to the configuration field editor. Select the field you want to edit by using the Up and Down Arrow keys (or K/J) and press RETURN. Edit the Waitfor field and press RETURN. You will then edit the Send field. When finished press RETURN and continue editing the Waitfor / Send sequences until finished. You can have up to 15 Waitfor / Send sequences in your configuration file. When you have completed editing the Waitfor / Send sequences press ESCAPE. You will be asked if you would like to save these values in the 'gmail.cf' file. If you answer 'Y', gmail/OL will save the 'gmail.cf' file and begin using these new values immediately. Answering 'N' deletes any changes you have made while using the configuration editor. Chapter 3 GORP and Your Modem GORP is merely an acronym for "Gregg's Off-Line Reader Protocol". It is an adaptation of another protocol common to some Apple // and UNIX systems known as MDSS, written by Morgan Davis of the Morgan Davis Group. How GORP Works As implemented in gmail/OL, GORP accesses the modem to dial the GORP server system and exchange mail files. Here are the steps gmail/OL takes to make a GORP transfer: 1.Initialize modem. 2.Dial GORP host number from the 'gmail.cf' file. 3.Execute the Waitfor / Send sequences from the 'gmail.cf' file. 4.Check to see if the 'out' directory has any messages in it. 5.If there are messages, send them via XMODEM to the GORP server until all have been sent. 6.Wait for messages from the GORP server. 7.If there are any, receive them via XMODEM. 8.Append these mail files to your 'mailfile' and terminate the connection with the GORP host. When the GORP host receives your mail messages, its program will: 1.Extract the To:, Cc:, and Bcc: lines. 2.Compose a complete mail header from the partial header given by gmail/OL. 3.Send the message to each of the recipients via its mail transport. If any errors occur during transmission the outgoing message will not be deleted; or if receiving, the incoming message will not be appended to your 'mailfile'. GORP will try to send a message three times before it quits. You can press ESCAPE during a GORP session to cancel the transfer. If you would like to quit before GORP logs into the server computer, press ESCAPE as many times as you have Waitfor / Send lines. The Modem Connection To use gmail/OL as a true Off-Line reader you must have a modem attached to your system and have a host system to call. Following the guidelines below will almost assure you of hassle free GORP connections. First, the Apple //gs version must be used in conjunction with an EXTERNAL modem connected to either the Printer Port (port 1) or Serial Port (port 2) via an RS-232 serial cable. No other configuration on this computer is supported. The DOS version supports both external and internal modems on IBM PC and compatibles. Modems may be connected as COM1, COM2, COM3, or COM4. Also, the modem IRQ for any of these COM ports may be set to 2, 3, 4, or 5. See the section on "IRQ Setting" in chapter 1 for the default configuration and more information. On all systems the modem must be "Hayes AT compatible" and support one of the following baud rates: 1200, 2400, 4800, 9600, 14,400, or 19,200. Unpredictable results will occur if your modem does not conform to these parameters. Not to worry, 99% of the modems available for sale in the last 5 years have fulfilled these requirements. Your modem package should contain information on attaching it to your computer. Contact the manufacturer of your modem if you have difficulties with connecting your modem to your computer. Finding a GORP Server You are in luck! The GORP server software is included on your distribution disk. The directory "gorp.src" contains the C language source code and installation instructions for use with UNIX systems. If you already have a UNIX account, contact your system administrator and have him install GORP for you. It doesn't take any programming experience to install it, but the installer must have ROOT access on the UNIX machine. There are also several Bulletin Board software systems that allow GORP access. Most notably are the ProLine and FrEdMail BBSs. If you have access to a ProLine or FrEdMail system, you have access to a GORP server. All ProLine and FrEdMail systems have Internet mail access and most have no charge for user accounts. As the popularity of GORP grows, there will surely be more Bulletin Board software systems incorporating it. Feel free to play with and incorporate the GORP source code on other platforms. As email becomes more popular, Off-Line reading will become more necessary. To help others with their modifications, please send Omega Software Solutions the information on any changes you make to GORP for implementation on other systems. GORP and gmail/OL A GORP session is initiated from gmail/OL by issuing the poll command, 'P', from the main screen or while reading a message. It then dials the system, attempts to login, and if successful, exchanges email files. GORP can be canceled during the login by pressing ESCAPE, but can not be canceled while sending or retrieving a file. This is to protect the data integrity of your email messages. When GORP is finished exchanging files with the server, it returns to the main screen or the message you were reading when you polled the server. Look at the header index (press 'I' if reading a message) and go to the end of your email header list to view newly received email messages. New messages will have an 'N' directly after the message number. Chapter 4 Other Stuff The gmail/OL manual is finally drawing to a close. In this chapter you will find extra information about using gmail/OL from a command shell, a general description of how to use email, and some troubleshooting facts for gmail/OL. Using gmail/OL from a Shell Command shells such as COMMAND.COM in DOS or ORCA and GNO on the Apple //gs allow you greater flexibility when launching and running gmail/OL. The command shell version of both the Apple //gs and DOS gmail/OL allow you to use parameters, preceded by a '-' to pass the following information to the program: -d spooldir - Tells gmail/OL to spool outgoing messages in spooldir instead of to the 'out' directory specified in the configuration file, 'gmail.cf'. -f filename - Set gmail/OL to start the mailer right away, loading in filename as part of the message. Quitting from the mailer screen returns you to the command shell. -m filename - Tells gmail/OL to read in messages from 'filename' instead of from the 'mailfile' parameter in the configuration file, 'gmail.cf'. -s subject - Tells gmail/OL to use this value in the 'Subject:' line. Must be used in conjunction with a 'user' input described below. -p - Poll the GORP server specified in the 'gmail.cf' file upon entering the program. Do not show the main message screen before polling the server. When gmail/OL is done polling the GORP server, it starts the main screen, ready to read your new messages. user - Use no dash in front of this parameter. Simply type 'gmail a@b' to enter the mailer screen immediately to send a message to a at site b. Quitting from the mailer screen returns you to the command shell. Examples: gmail -p -m othermail - start gmail/OL, polling the GORP server before loading in messages from the file 'othermail'. gmail greggb@acme.fred.org -f textfile -s Transmission - start gmail/OL, go directly to the mailer screen to compose a new message for greggb@acme.fred.org. Include the file 'textfile' in this new email message. Also include a subject line 'Transmission' to denote a file is being sent. When finished sending the message, return to the command shell. gmail -d c:\tmp -p - start gmail/OL, storing any outgoing messages in OR get any messages for the GORP server from the directory c:\tmp. Also, poll the GORP server, sending any messages stored in c:\tmp. Note about using path names When using path names as command line parameters it is always best to fully qualify a path with the full path name, including the volume. The above example 'gmail -p -m othermail' will not work unless the file 'othermail' is in the directory where gmail/OL is launched from. Even if the file is in the launch directory, it is best to send fully qualified path names. This example would be better written as: gmail -p -m /hd/gmail/othermail (Apple //gs) - OR - gmail -p -m c:\gmail\othermail (DOS) Launch Directory Because of the way the Apple //gs system software operates, it is not necessary to be in the same directory as the 'gmail' file when launching the program. On the other hand, the DOS version requires that you have changed directories to the directory where 'gmail.exe' is. The files 'gmail.bat' and 'gmail.pif' are included on the distribution disk to facilitate this launching from the DOS shell or MS Windows respectively. Please edit these files to ensure gmail/OL is launched properly. The 'aliases.gm' File The 'aliases.gm' file, located in the gmail/OL boot directory is used to store shorter names that correspond to actual email addresses. The format of this file is as follows: alias: adress@longsite.wherever.org gregg: greggb@acme.fred.org Edit the 'aliases.gm' file and place each alias on its own line, separated by a carriage return. When gmail/OL boots, it loads these aliases into a table that it uses when you send a message. When prompted for the 'To:' line while sending a new message, all you need to type is 'gregg' to have 'greggb@acme.fred.org' placed in the actual 'To:' field. As you can imagine, this will save you much time and frustration when trying to remember machine granted user names, like a friend of mine who's user name is 'stg33s-2' on his host machine! All I have to type when sending a message is 'mike' and his complete email address is automatically placed in the 'To:' field. Email and Formatting a Message Electronic mail is a new frontier for many people. The greatest challenge for email users and those who program email utilities is ease of use and convenience. gmail/OL is designed to fulfill these two requirements. The email format gmail/OL uses is called RFC-822 (Request For Comments), a standard established by the Internet networking standards group. RFC-822 is the most commonly used message format in the world. Most universities, businesses, and newer bulletin boards use RFC-822 as a guideline for their mail messages. The common RFC-822 email message is formatted like this: From user@site date Date: day, date month year time From: user@site (user full name) X-Mailer: gmail version To: otheruser@othersite Subject: subject text < blank line with only a newline character > Message text to end of file. The above format is what the GORP server received from gmail/OL during a GORP on-line session. As you can see, there is no mystery about electronic mail. You need only supply the correct address of a user for the To: line and the message text to send a message to anyone on the Internet. Troubleshooting What if... "I launch gmail/OL and it starts the configuration editor every time." gmail/OL expects to find the file 'gmail.cf' in the same directory as the executable program file. The Apple //gs version automatically knows how to find this file but the DOS version must first change directories to the directory where both these files are kept. DOS users should edit the 'gmail.bat' file to reflect the directory where 'gmail.exe' and 'gmail.cf' are stored. "I launch gmail/OL and my message headers don't show up on the main screen." Check the configuration options to make sure the path to your 'mailfile' is correct. If the problem still persists, try using a full path name that includes the drive name: DOS: c:\gmail\mailfile Apple //gs: /hd/gmail/mailfile "I tell gmail/OL to poll the GORP server and it just sits there until I get a 'timeout' error." When you tell gmail/OL to poll the GORP server it should echo the phone number to the screen and activate your modem immediately. The only reason this won't happen is if the modem parameters are configured improperly. Check the modem settings in the configuration editor and modify these settings appropriately. The most common error is using the wrong port setting. Make sure your modem is connected to the port you specify. "When polling the GORP server it hangs up instead of starting to send files." Most likely one of your login parameters is incorrect. Make sure you are logging into the GORP server correctly. Try dialing into your account, using the same username and password you have included in the waitfor/send lines of your 'gmail.cf' file. If this doesn't work you need to contact the system administrator to find out your real username and password before logging into GORP again.