Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PROGRAMS / UTILS / COMMUNIC / EMMA22.ZIP / EMMA.DOC < prev next >

Wrap

Text File | 1990-09-27 | 26.5 KB | 602 lines

Emma ==== Documentation for version 2.2 by Pete Maclean -- ---- ------- (Note for users updating to 2.2: a summary of new features is given at the end of this document. There is also a new section on using Emma with an MNP modem.) I have prepared this document to accompany Emma, the PC/MS-DOS version of my MCI Mail utility published by PC Magazine. While this document is intended to be a complete user's guide to Emma, users may also benefit from reading my original article about it in PC Magazine (Issue 19, November 14, 1989). Each time you run Emma it attempts to connect to MCI Mail, upload any messages you have prepared to your outbox, and download any messages waiting in your inbox. Emma can handle messages of all kinds including those to be sent to fax machines, telex machines, Internet mailboxes and CompuServe subscribers. Without a program like Emma, one connects to MCI Mail in what is called "terminal mode." Terminal-mode operation involves a lot of manual work and bypasses one of MCI's most powerful features, the ability to ship arbitrary files to other MCI subscribers. Emma connects to MCI Mail in a different manner called "batch mode." With Emma, you never have to manually interact with MCI's computers; Emma becomes your own private MCI agent. Thanks to a script-file mechanism, Emma can be configured for use in any part in the world. It already has supporters in Canada, Hong Kong, Taiwan and many European countries. If you are using it outside the U.S.A., you may have to write your own script file or find another user who has created a suitable one. Emma correctly handles messages that contain accented letters and other characters from the extended PC character set (that is, with codes of 128 and above). Emma has one major limitation compared to other agent programs: it has no built-in error-correction capability. Thus it is an ideal utility only for those people with suitable error-correcting modems, specifically modems that support MNP. Without such a modem, you should consider using Emma only if you normally experience a negligible number of transmission errors when connecting to MCI Mail. Emma does have error-detection capability and guarantees that when it completes delivery of a message that message will be free of errors. Should a transmission error intrude, Emma aborts the session. No data is lost in such an event, but any message being transferred at the time must be transferred again. Before you use Emma ------ --- --- ---- Emma is designed to operate with modems that use the Hayes AT Standard Command Set. Should you have a modem that requires a different command set, you can still Emma but you will have to write a special script to enable it to work with that modem. Before running Emma for the first time, you must customize a script for the program to follow in connecting to MCI Mail. You will do best to start off with one of the standard script files included in this package. Select one as follows: MNP.CSF if you have an MNP modem, otherwise 800.CSF if you connect, or plan to connect, to MCI Mail on a tollfree number, LOCAL.CSF if you connect, or plan to, via a local telephone number, TYMNET.CSF if you want to connect to MCI Mail via TYMNET. or DATAPAC.CSF to connect via Canada's DataPac network Use the DOS COPY command to copy the selected file to a file called EMMA.CSF. Then edit EMMA.CSF according to the instructions contained within it. Running Emma ------- ---- Early versions of Emma required a companion program, Bess, to provide communication services. Bess has now been integrated into Emma providing extra convenience for almost all users. To run Emma, enter at the DOS prompt: C>emma Emma must be able to find its script, EMMA.CSF, so normally you need to be in the directory where that file resides. An alternate method is to set up a batch file to take care of the whole job. I use a batch file that looks like this: CD \MCI EMMA The first command switches to the directory where I manage my electronic mail. I call my batch file 1.BAT so, at any DOS prompt, all I have to do is type a '1' and press Enter. Once logged into the MCI Mail system, Emma looks for messages to be uploaded. It searches the current directory for files named with an extension of "OUT". Hence every message you create should be stored on such a file, e.g., PETE.OUT, SALLY.OUT, etc. When Emma has successfully delivered a message to MCI it renames the corresponding file to give it an extension of "MLD" (for mailed). Having completed any uploads, Emma downloads any waiting messages and appends them to a file called MAIL.IN. As each message is transferred, Emma displays the envelope on your screen so that you can know at once who has sent you mail. If you miss any of this information, there is no loss since it is all preserved in MAIL.IN. Once Emma has completed its work, you can inspect any new messages by reading MAIL.IN with a word processor or a browsing program. You may want to extract certain messages and save them on other files. After reading your mail it's a good idea to delete or rename MAIL.IN so that when you next connect to MCI that file will contain only your new mail. Preparing Outgoing Messages --------- -------- -------- The format of outgoing messages is described in a separate document file, COMPOSE.DOC. Things to remember when running Emma ------ -- -------- ---- ------- ---- * When you run Emma it must be able to find its script file, EMMA.CSF. * You can abort a session at any time by pressing the Escape key. Emma ignores any other keyboard input. * If your modem is not powered on or is disconnected, Emma will probably complain about a timeout error. This is because it sends a command to the modem and receives no response. * If MCI Mail sends an error message to Emma that message will be displayed on your screen. The only things that MCI is likely to complain about are: - misformatted envelopes - messages directed to unknown addressees - messages with ambiguous addressees - data damaged by transmission errors * If MCI Mail rejects a message then Emma terminates the session. Any other messages awaiting transmission are left as they are. Correct the problem or rename the message before running Emma again. * A "checksum error" is an almost certain indication of a transmission error. If you see one reported, try running Emma again. If the error happens again, you are probably getting connections that are too noisy. * If you suffer a lot of aborted sessions because of transmission errors a good trick to get cleaner connections is to run at a lower speed. For example, should you get frequent failures at 2400 bps, try 1200. Message transfer will take a little longer but, as long as you connect directly to MCI Mail, the cost will be the same. * After you upload a long message or attachment, it may take MCI a considerable time to respond, close to two minutes in the worst cases. This effect is internal to MCI Mail; there is nothing that Emma can do to expedite matters. If you send a file of several kilobytes, be patient waiting for the transaction to complete. Do not assume that the session is hung if nothing happens for a while. * Without an MNP modem it is unwise to use Emma to send messages or attached files that exceed 10 KB. The chances of the transmission being aborted by an error grow with the length of the transaction. Likewise, if you want to transfer several files of substantial size as attachments, you should attach each one to a separate message. * Be very careful if you use WordStar to edit MAIL.IN. Should you do a save to MAIL.IN then WordStar pads the end of the file with Control-Zs, characters that some programs including WordStar interpret as end of file markers. If Emma then appends further messages to MAIL.IN these messages appear after the Control-Zs so that WordStar will fail to "see" them. This phenomenon may occur with certain other editors as well. To be safe, no matter what editor/word processor you use, it is very good practice to clear out and delete MAIL.IN each time you read your new mail. And in particular never do a save to MAIL.IN. Writing Scripts ------- ------- Emma needs a script file for four purposes: 1. To tell it which COM port and what line speed (1200, 2400,...) to use. 2. To give it the sequence of modem commands and expected responses required to connect to MCI Mail. 3. To tell it how to login to the MCI systems, which means providing your username and password. 4. To inform it of other options that you may choose. See the discussion of "Advanced Options" below for details of these. Normally, Emma looks for a script file called EMMA.CSF ("CSF" for connect script file), but you can override that by providing Emma with an alternate name as a command-line argument. For example: C:\MCI>EMMA REG tells Emma to use the script on file REG.CSF. The extension of a script file is assumed to be "CSF". Script files are composed of simple commands written one per line as in the following example: C "Calling MCI Mail on an 800 number^M^J" P 1 "2400" T "ATDT1-800-234-6245^M" R 40 "CONNECT" B D 2 T "^M" R 25 "name:" T "username/batch,1ST/password^M" M R 10 "CLR DTE^M^J" This is a barebones script to connect to MCI and run a mail-exchange session. It serves as an illustration of the most important commands but, in practice, you would want a slightly fuller script such as one of those distributed with Emma. Each command is identified by a single letter. Here is a complete list: B - autoset bps C - display a comment D - delay for a number of seconds K - sends a BREAK signal L - enable logging of the session to a file (see advanced options) M - conduct a mail-exchange session with MCI P - configure the COM port to be used for communication Q - select quick mode (see advanced options) R - wait for an expected reply to arrive S - specify an alternate message separator (see advanced options) T - transmit a given string With these descriptions it should be easy to figure out how the sample script works although you may have to guess a few things. Any command may take up to two arguments: a numeric argument written as a decimal integer and a string enclosed in double quotes. Command letters and arguments are separated by white space, that is spaces and/or tabs. The command: P 1 "2400" tells Emma to use COM1 and set the speed to 2400 bps. Every script must contain a 'P' command which should appear before any 'T' or 'R' commands. The command: T "ATDT1-800-234-6245^M" tells Emma to transmit the given string, a dial command for the modem in this example. Any control characters that are required in strings must be expressed using the common keyboard-equivalent notation. Thus: ^M means a carriage return (Control-M or Enter) ^J signifies a linefeed (Control-J) ^L indicates a formfeed (Control-L) ^P indicates a DLE (Control-P) used as an escape code by some PSNs. and so on. Emma ignores any literal control characters included in strings. There is one exception to this rule: horizontal tabs are accepted. The command: R 25 "name:" tells Emma to wait up to 25 seconds for the strings "name:" to come from MCI. If the expected characters do not turn up in the allotted time, Emma aborts the session with a timeout diagnostic. The 'B' command is for the benefit of speed-adjusting modems. It tells Emma to look at the characters arriving from the modem and to decode a speed if such is present. A typical modem response would be "CONNECT 1200". The 'M' command initiates a session between Emma and MCI Mail using MCI's proprietary mail-exchange protocol. The operation of the rest of the basic commands should be evident from the above example. More advanced commands are described below. You should never have to write a script from scratch. But if you connect to MCI internationally or have a weird modem, you will need to edit one of the scripts provided. Advanced Options -------- ------- (*). You may include comment lines in script files for documentation purposes. Emma recognizes any line that starts with an asterisk or a semicolon as a comment. Don't confuse these internal comments with the external kind, that is comments that are written to the user's screen via the 'C' command. C "This is a comment that is written to the screen^M^J" * This is an internal comment that Emma ignores (*). Emma can be run in an optional quick mode designed to minimize connection times for those users who have to pay hefty line charges. In quick mode, Emma disconnects very quickly from MCI when there are no messages to be delivered; it does not wait for all the commentary that MCI usually sends indicating the numbers of messages sent and received. Quick mode is selected by including a 'Q' command in your script file. Here is an example: Q "There are no messages waiting in your INBOX^M^J" The argument is a string defining a line that Emma can recognize as signifying that MCI has no messages waiting for download. The string must include one entire line including the terminating CR and LF. When Emma spots the given line, and if it has no messages to upload, then it terminates the session. Most users who want to use quick mode will do best by copying the above example exactly. I chose to require that the user include the line explicitly in the 'Q' command because wiring it into the program might lead to incompatibilities with foreign-language versions and future revisions of MCI's system. There is a means that Emma could use to determine automatically the number of INBOX messages, but taking advantage of that would substantially increase the connect time! The 'Q' command may be placed anywhere in your EMMA.CSF before the 'M' command. (*). You may select how messages are separated in the MAIL.IN file. By default, Emma adds three blank lines after each message. If you want something different then add an 'S' (for separator) command to your script file. The argument is a string defining the separator text. Here is one example: S "^M^J*************************************************************^M^J" The 'S' command may be placed anywhere in your EMMA.CSF before the 'M' command. (*). Three options are available on the 'M' command: send-only, attachment-overwrite and ASCII-mode. Each option is selected by including a key letter in a string argument. In send-only mode, Emma sends MCI any outgoing mail without downloading INBOX messages. The feature is selected thus: M "S" Send-only mode is intended for users with secretaries who create and dispatch mail but who do not handle incoming messages. Normally, when Emma receives an attachment with a name that matches an existing file, it generates a new name for the attachment of the form ATTACHED.xxx. By selecting attachment-overwrite mode, you instruct Emma to store attachments under their original names even if such files already exist. This option is useful for those people who update remote files by MCI. You select this option by editing your 'M' command to read M "O" Finally, Emma's ASCII mode is provided for users of WordStar and similar editors that bend high bits to their own uses. The effect of selecting this option, by M "A" is that all messages are stripped down to 7-bit characters before transmission. (This stripping applies specifically and only to message texts and not to attached files.) You may combine options as in this example: M "AOS" The option letters may appear in the string in any order. (*). Emma's screen output can be redirected allowing the program to be used in a more automated fashion. You can, for example, invoke Emma from a batch file and have it run "silently," that is with no screen output. You can discard the output completely by redirecting it to the null device, e.g. EMMA >NUL: Or you can redirect it to a file, e.g. EMMA > OUTPUT Warning: don't carelessly redirect to a file named, say, EMMA.OUT. Emma would, of course, treat that file as a message to be sent to MCI. (*). For the benefit of those who want to invoke it from batch files, Emma terminates with one of the following exit codes: 0 => Emma completed successfully but received no new mail 2 => file i/o error (no new mail received) 3 => script error (no new mail received) 4 => user interrupt, i.e. user pressed Esc (no new mail received) 5 => timeout (no new mail received) 6 => protocol error (no new mail received) 100 => Emma completed successfully and received some new mail 102 => file i/o error (after new mail was received) 103 => script error (after new mail was received) 104 => user interrupt (after new mail was received) 105 => timeout (after new mail was received) 106 => protocol error (after new mail was received) Note that exit codes 1 and 101 are not used. Emma adds 100 to whatever exit code it would otherwise use if it has downloaded any new messages to MAIL.IN. See the file, SAMPLE.BAT, for a model of how you might use these exit codes. (*). Emma can create a transcript of each session it conducts with MCI Mail. If you want a transcript for troubleshooting or any other reason, you must tell Emma by adding an 'L' command to your .CSF file. The argument is the name of the file to which you want the log written, for example: L "emma.log" It is best to put this command near the beginning of the script file. In future versions, I may add options for selecting different levels of logging. (*). The K command tells Emma to transmit a standard BREAK signal on the COM port. (A BREAK consists of approximately 385 milliseconds of SPACE.) It is included for compatibility with certain foreign packet switch networks that require such a signal as a trigger for setting PAD parameters. (*). Suppose you love Emma but are wary about keeping your MCI password in a script file that someone else might look at. Or suppose that you use Emma on a portable PC and need a different dialing code every time you run it. Emma can help. Place a question mark in front of any string argument and Emma displays it on the screen as a prompt for you to type in the "real" string you want used. For example, to avoid putting your password in your .CSF file, you could set up the appropriate section of it as follows: R 15 "name:" T "your_username" T "/batch:1ST/" T ? "^M^JPlease type your password (and press Enter): " T "^M" R 20 "COM^M^J" You can use this facility with any script command although it is not obviously useful with any but 'T'. Note that while you press Enter to terminate the string that you type in, the Enter itself (i.e. a carriage return) is not included in the string. You may type in strings of up to 80 characters; anything typed beyond this limit is quietly ignored. You can use the Escape key to abort a session while typing a string just as you can at any other time. You can even go one step further with this mechanism. When Emma reads the response to a prompt, it reads standard input (not the keyboard directly). Thus you can redirect input from a file. For example, set up your EMMA.CSF with null prompts (?"") and create a file, RESPONSE, containing the responses, one per line. Then start Emma with the command: EMMA <RESPONSE This would allow you, for instance, to set up a totally generic script file for Emma then have some other application query the user for dialing code, username, password, etcetera, write that information out to a file and then invoke Emma as above (perhaps via a batch file). Using Emma with an MNP Modem ----- ---- ---- -- --- ----- With a properly configured MNP modem, Emma should work with perfect reliability. Unfortunately, setting up your MNP modem with all the correct options may not be trivial, especially since there is no uniformity among modems for the AT commands that select MNP features. Start with the MNP.CSF model script provided, and make sure that your modem is sent the appropriate commands to select: Flow control: local birectional XON/XOFF. Disable bps-rate adjustment. Reliable mode (forces modem to make an MNP link or nothing). Enable data compression during MNP connections. Note that the last option is usually a default but the other three are not. By disabling the bps-rate adjustment, you can take advantage of higher throughput thanks to MNP compression. If you select this option then set the port speed to a bps rate higher than that of the modem, for example 9600. Also be sure that you do not have a B command in your .CSF script. Should Emma complain about overrun errors then reduce the port speed; on slow PCs, Emma may not be able to keep pace with 9600 bps. Troubleshooting Tips --------------- ---- If MCI finds faults with a message, an explanation will be displayed on your screen. (Unless, of course, you have redirected Emma's screen output.) The most common problems are with misformatted envelopes. For a message to be delivered, the subscriber must be exactly identified. If you address a message to a name that's not unique, the IDs of all MCI subscribers with the name are listed: At least one problem with envelope 608 More than 1 MCI Mail user matches recipient information MCI ID Name Organization Location 000-0000 Zoltan Shah Whizzo Chocolate New York, NY 111-1111 Zoltan Shah Sunshine Desserts Fresno, CA Select the right one and edit your message to include the ID. Remember that the name should be separated from the ID by a slash, as in Zoltan Shah/111- 1111. In fact, an ID alone is a perfectly acceptable address. If MCI objects to something else in the envelope of a message, you may receive a response such as: At least one problem with envelope 610 Improper information in the envelope SUBJECT: EMMA This text is part of the message... In this case, the blank line needed to terminate the envelope is missing. Other causes might be a mistyped keyword or the appearance of lines in an order that MCI cannot handle. Some errors offend MCI so much that it stops responding, such as a message with two or more addresses on a line. A message may be addressed to any number of people, but each address must be on a separate To: or Cc: line. And, if you receive either a Checksum error or Malformed data message, you can be almost certain that a transmission error has ruined your session. Just try again. With an MNP modem, Emma should be perfectly reliable. If it proves not to be then consider the following possible problems: (1) You are not configuring the modem so that it establishes an MNP connection with MCI. (2) You have the modem configured for the wrong type of flow control. Emma uses Control-S/Control-Q flow control. If you set the modem for hardware flow control or any other flow-control option then you are very likely to see errors. (3) If your PC is on a LAN the network software may steal sufficient processor time that Emma misses characters coming in on the serial port. Should you suspect this, verify it by temporarily unloading the network software and seeing what happens. Notes for International Users ----- --- ------------- ----- Emma is the only publicly available agent software for MCI Mail that is "internationalized." As such, it has users all over Europe and Asia. To use Emma from a foreign location, you will likely need to make substantial modifications to a script in order to complete the connection. The most important thing to remember in doing so is that the connection must be set up with no echoing. This is different from terminal-mode connections and may entail changing PAD parameters for foreign packet switch networks. Should Emma give you the diagnostic: ***Protocol failure: unrecognized message received*** after completing a login to MCI, it is almost certain that echoing is the problem. Determine what has to be done to turn it off. New Features In Version 2.2 --- -------- -- ------- --- Version 2.2 brings two new features to Emma: DataPac compatibility and saving/restoring of the COM port. The standard way of connecting to MCI Mail from Canada is via DataPac and then through a gateway to TYMNET. Earlier versions of Emma failed to operate via DataPac due to some strange echoes apparently produced by that network. The new version is designed to discard these stray echoes and is accompanied by a script file, DATAPAC.CSF, designed for such access. Emma now saves the entire state of the COM port that it uses and restores that state before terminating. This feature was added for users who run Emma in a multitasking environment such as DESQview. * * * * * * * * Emma is Copyright (C) 1989 Ziff Davis Communications Co. This document is Copyright (C) 1989, 1990 by Pete Maclean. It may be freely distributed with Emma as long as no additions, deletions, or alterations are made. All other rights reserved. NOTICE: Emma was developed, in part, using, with permission, proprietary, trade secret information of MCI Telecommunications Corporation. The user agrees to use this program only for the purpose of communicating with MCI Mail.