Äbˆçéneed to terminate receipt of the file at any time, press [BREAK]. Transmitting a File: Control-3 To start the XMODEM transmit routine, press control-3. The file to be transmA K£§Äbˆçé *+*+*+*+*+*+*+*+*+*+*+*+* + + * M I K E Y T E R M * + Version 4.0 + *+*+*+*+*+*+*+*+*+*+*+*+* Copyright (C) 1985 by Michael D. Ward Documentation Written by Donald D. Hutchison MIKEYTERM Users Manual Version 4.0 Page 1 T A B L E O F C O N T E N T S Introduction . . . . . . . . . . 2 Getting Started . . . . . . . . 3 COMMUNICATIONS Mode . . . . . . 7 DISPLAY Mode . . . . . . . . . . 14 Marking the Buffer . . . . . . . 15 MODEM Mode . . . . . . . . . . . 17 RESETTING THE BUFFER . . . . . . 17 TAPE UTILITY . . . . . . . . . . 18 DISK UTILITY . . . . . . . . . . 19 BUFFER ENTRY Mode . . . . . . . 22 CHANGING PARAMETERS . . . . . . 23 EXIT . . . . . . . . . . . . . . 24 Appendix Going Online Fast . . . . . A-1 Quick Summary . . . . . . . B-1 Description of XMODEM . . . C-1 MIKEYTERM Users Manual Version 4.0 Page 2 I N T R O D U C T I O N MIKEYTERM is an advanced, user friendly, general purpose terminal program that supports many of the popular file transfer protocols, such as ASCII, XMODEM, and pure binary. Advanced buffer entry is also provided, as well as support for modems, printers, and BOTH disk and tape systems. First time users will find MIKEYTERM to be easy to use and extremely forgiving, yet experienced users will find their most wanted features included. Users may also configure MACRO key definitions for specific functions, such as CompuServe ID's and passwords. In addition, MIKEYTERM may be used with the more common "smart" modems. Version 4.0 includes support for the standard CoCo serial port at 300 baud, the Radio Shack RS-232 Program Pack or PBJ 2-SP card for 1200 baud and higher speeds, and the PBJ WordPack or WordPack II. MIKEYTERM will adjust itself automatically to use whichever of these hardware additions is present. MIKEYTERM requires a fully implemented 64K Color Computer (or TDP-100) using either Disk BASIC Version 1.0 or Version 1.1, although many custom ROMs function equally well. At least one disk drive, a cassette recorder/player, a printer, and a modem will enable the user to avail himself of all of the features that are inherent in MIKEYTERM. MIKEYTERM does NOT support any version of JDOS. NOTICE: The author does not warrant the suitability of this program for any particular user application and will not be responsible for damages (consequential or otherwise) that are incidental to its use in a user system. This document and the program it describes are Copyright (c) 1985 by Michael D. Ward. MIKEYTERM Users Manual Version 4.0 Page 3 Getting Started With MIKEYTERM MIKEYTERM comes pre-configured to the following settings: Full duplex RS232 Pack baud rate = 300 Printer baud rate = 600 7-bit word length No parity No linefeed on carriage return Auto buffering on Buffer open at startup Startup at Main Menu Word wrap enabled Auto halt off Cursor color for closed buffer is dark blue. (&HAF) Cursor color for open buffer is yellow. (&H9F) No predefined strings for control keys. No ASCII filter values For WordPack and WordPack II: Slow, blinking cursor Solid block to indicate open buffer Underline to indicate closed buffer These settings are the common defaults for most information services and bulletin board systems. A BASIC program has been provided with MIKEYTERM in order to allow the user to set the default options to whatever is desired. CNFG40.BAS is menu driven and fairly straightforward in itself, so this section will cover only those aspects which may not be obvious. The function of "CNFG40" is to allow one to customize MIKEYTERM to the most convenient default values for: 1. Function key definitions 2. Duplex, full or half 3. Word length, 7 or 8 bits 4. Auto Halt ON/OFF 5. Linefeed on carriage return ON/OFF 6. Auto-buffering ON/OFF 7. Cursor colors 8. Buffer initially open or closed 9. Word wrap ON/OFF 10. Initial entry into Communications or the Main Menu. 11. RS232 Pack baud rate 12 Printer baud rate 13. WordPack defaults 14. ASCII filter values CNFG40.BAS is set up to configure Mikeyterm version 4.0 only, and will work with either cassette or disk systems. MIKEYTERM Users Manual Version 4.0 Page 4 Because things can go wrong and accidents can happen, be sure to use a BACKUP copy of Mikeyterm. Simply insert the BACKUP copy of the distribution disk into your default drive and enter the line RUN "CNFG40" [ENTER] to begin. You'll be prompted for the necessary information as you progress. The first question asked by "CNFG40" is "Filename to configure?". Just pressing the [ENTER] key will load the distribution version of MIKEYTERM. Text input is NOT required for the control key string definitions. For these, just pressing [ENTER] will advance to the next (optional) string definition, or you may enter any apropriate string of text that you choose. Text string length for the configurable keys is limited to 31 characters. You may use all keyboard characters up to and including this length. "CNFG40" will alert you if you attempt to use strings that are too long. You will then be prompted to re-enter the desired string. The "ASCII Filter" is an extremely useful mechanism for filtering out annoying control characters, but may have little practical value in normal day-to-day communications. If you specify a filter it will be active anytime you're in Communications mode in either 7 or 8-bit mode. XMODEM transfers are NOT affected. If you just hit [ENTER] at the first "received value" prompt no filtering will take place and you may continue with the rest of the configuration process. If, however, you have to deal with a host computer that sends a "DEL" character (ASCII 127) at the beginning of every line, (or some other useless control code) you can filter it out by using the ASCII filter. You may filter any 3 ASCII values you want. "Filter" means that you may do one of two things with any three data values: (1) you may "discard" a character by replacing its ASCII value with a zero byte (null), or (2) you may change a byte by replacing its ASCII value with any other ASCII value. For example, let's say we want to discard ASCII 127's as they come in. Here's what the configuration program would show: Received value 127 Replacement value 0 This is repeated for up to three values. If you want to stop after one value, just hit [ENTER] when prompted for the second "Received value" and your one-byte ASCII filter will be saved. Next, we'll set our default printer baud rate. Here, just enter the value you would use if you were going to print something from a BASIC program. This would be the same value you normally poke into location 150. For example, if you have a 1200 baud printer you would usually use "POKE 150,41" to set the baud rate. Here you just enter the 41, or whatever works for you with BASIC. MIKEYTERM Users Manual Version 4.0 Page 5 Next, you'll be asked several questions about how MIKEYTERM should communicate with other systems and computers. If in doubt about exactly which communications parameters you should select, choosing the following will usually provide successful communication with the great majority of BBS's and telecommunication services: Full duplex 7-bit word length Auto halt OFF No linefeed on carriage return Automatic buffer open/close option ON The "Auto Halt" feature needs a little explanation, since it isn't implemented in most other terminal programs. When in Communications with the "Auto Halt" feature turned ON, (and assuming that the host supports XON/XOFF protocol) leaving Communications will send a control-S to disable the host's transmission. When returning to Communications, MIKEYTERM will send a control-Q to restart the host's transmission. This means that if there was any traffic pending, it will be sent at this time. It is even possible to exit in mid-sentence, if desired. When returning to Communications, all defaults and communication parameters will be restored, just as before. (It's a good idea to leave this feature OFF if in doubt about the host.) Linefeeds are not normally needed since they are usually supplied by the host, so the "linefeed on carriage return" option is generally set to "no". However, linefeeds must be inserted after each carriage return when operating in half-duplex mode, especially while communicating with another Color Computer. If half-duplex operation is chosen, a linefeed after a carriage return option is automatically set to "on", but may be reset to "no" through the "Change Parms" option. Automatic buffer control is a desirable option, as it is used by most BBS systems for downloading purposes. When initiating a download, the BBS or the host will send a special character (a control-R) to open MIKEYTERM's buffer. After the download is complete, the BBS or host will send another special character (a control-T) to close the buffer. Normally, the automatic buffer option should be set to "yes" unless its operation would cause undesirable effects. (Note: automatic buffer control is not possible in the 8-bit mode. If you have selected 8-bit mode, the automatic buffering option will be ignored by MIKEYTERM.) The cursor colors are normally set to yellow for an "open" buffer, and to dark blue for a "closed" buffer unless overridden during the configuration process. Just pressing the [ENTER] key at the prompt for each cursor value will automatically assign the above default cursor colors. You may define any values that you desire for the cursor characters, just as long as they are each greater than 128 (&H80). You may even define a checkerboard cursor if you like! The "CNFG40" program will optionally display all possible cursor colors for you, if desired. After viewing them, you'll be returned to the cursor selection menu where you can insert the desired colors. (Note that this is for the normal video, not the 80 column Wordpak.) MIKEYTERM Users Manual Version 4.0 Page 6 Next, you'll be prompted for the initial status of the buffer, whether "open" or "closed". Normally, you should choose to have the buffer "open", but the option is provided for those who choose otherwise. You'll then be asked to choose whether you want "word wrap" enabled. (Incidentally, this option is only in effect for the normal 32-column text screen, and will NOT affect the WordPack display.) It's generally best to choose "yes" at this point, in order that MIKEYTERM will format the screen display into 32-character lines. Words that would normally be "broken" at the right-hand side of the screen will then be "wrapped" around to begin on the next line. This option will produce the most readable display for most people. You'll then be asked for the initial entry point into MIKEYTERM. Until you become familiar with the operation of the program, you may choose to enter at the "Main Menu". Later on, it's a simple matter to change the entry point to "Communications". The next series of questions is for those of you that have the PBJ Wordpak 80 column card. You may specify two different kinds of cursors to provide you with visual feedback on whether your buffer is open or closed. They are specified separately and may blink slow, fast, or not at all. You may also specify the size of each cursor. A size specification of zero is a huge solid block on both the Wordpak-I and Wordpak-II. A one-pixel-high underline is a 7 for Wordpak-I and a 9 for Wordpak-II. Use anything you like in the range 0 through 7 for the Wordpak-I, or 0 through 9 for the Wordpak-II. If you have the Radio Shack "Custom" keyboard #277-1019, (the one with the arrow keys all on the right-hand side and a "CTRL" and "ALT" key on the left) and you want to use the "CTRL" key instead of down-arrow for a "control" key, specify at the appropriate prompt. If you have an RS232 Pak or a PBJ 2-SP you may set your default start-up baud rate. MIKEYTERM 4.0 will support baud rates between 110 and 9600 baud using these hardware serial ports. At this time, you have (FINALLY!) completed "CNFG40", and you'll be asked for a filename for your customized version of MIKEYTERM. Use a standard formatted disk to save it. By the way, NEVER give anyone a customized copy of MIKEYTERM! The reason for this is that your configuration data is stored within your customized version(s) in the area from &HE00 to &HEFF. Your configuration data could conceivably include things like your User ID numbers, personal passwords, etc. MIKEYTERM Users Manual Version 4.0 Page 7 C O M M U N I C A T I O N S Main Menu Option 1 "Communications" is where you'll undoubtedly spend most of your time, so it's a good idea to get off to a good start. If you haven't run the "CONFIG" program yet or used Main Menu Option #8 to adjust your communications parameters, then now is the time to do so. If in doubt about exactly which communications parameters you should use, the following are usually successful when used with the great majority of BBS's and telecommunication services: 300 baud 7-bit word length No parity Full duplex Auto halt OFF No local linefeed on carriage return Automatic buffer open/close option ON When auto-buffering is ON and your parameters are setup for 7-bit mode, receipt of a control-R (hexadecimal 12) will open the buffer and turn the cursor to yellow if the buffer wasn't previously open. A control-T (hexadecimal 14) will close the buffer and turn the cursor to dark blue. (The buffer is closed automatically whenever the buffer is filled.) This protocol, sometimes called either DC2/DC4 protocol or "ASCII buffer capture", is used by CompuServe and many of the more popular BBS systems. (Note: the cursor colors may be modified to your taste by using the "CONFIG" program.) In 8-bit mode, detection of the buffer open/close control characters is not possible since those characters may form a part of the incoming data stream. If auto-buffering has been set to ON, it will be ignored in 8-bit mode and data will be stored in the buffer only if the buffer has been opened manually. MIKEYTERM Users Manual Version 4.0 Page 8 Operation All single-key commands may be entered in either upper or lower case text. In all cases, the key is used as a "control" key, since the Color Computer lacks a designated "control" key. (Most other terminal programs use this convention also.) To send a control character, press and simultaneously press the control key of your choice. Example: + will send a control-C. will send a control-C. + will do the same, and so will +. + will send a true line-break. will transmit a space. If you wish to transmit a horizontal tab, then use the + pair. will send a left bracket ([) character. + will send a right bracket (]) character. + toggles the display and the keyboard between the upper- and lower-case modes. Selecting lowercase mode affects what is displayed on the screen and sent from the keyboard, but does NOT affect the data that is being stored in the buffer. + issues an "escape" character, decimal 27. +<=> will issue a "rubout" character, decimal 127. MIKEYTERM Users Manual Version 4.0 Page 9 Control Key Designations 1 Open/close the buffer 2 Adjust RS-232 Pack baud rate between 110 and 9600 baud 3 XMODEM transmit from the buffer will abort at the end of the block being sent 4 XMODEM receive into the buffer will abort immediately 5 Exit Communications into Display mode, and display most recent data in the buffer 6 Send predefined text string 7 Exit Communications and go to the Main Menu 8 Send predefined text string 9 Transmit the buffer 0 Send predefined text string MIKEYTERM Users Manual Version 4.0 Page 10 XMODEM File Transfer One of the more noteworthy features in MIKEYTERM is the inclusion of the XMODEM protocol originally developed by Ward Christensen, a landmark pioneer in computer communications. The purpose of the XMODEM protocol is to guard against inaccuracies in file transfer caused by bad signals on the telephone line. It is an error-detecting, error-correcting protocol that ensures accurate transmission and receipt of data and binary files. The protocol is in wide use today among a variety of microcomputer systems and telecommunication services. To operate with the XMODEM protocol, both computers must have communications software that is capable of executing the XMODEM protocol. The file transfer will proceed, block by block, until the end of the file is reached. The transfer will then terminate automatically. The XMODEM routine in MIKEYTERM has been tested with other implemen- tations of the protocol and will give you good results. If the other computer is also running MIKEYTERM, you can definitely be assured of a rapid and accurate file transfer. For those who are interested, a technical description of how the file transfer takes place can be found in Appendix C at the end of this documentation. Receiving a File: Control-4 To start the receive, press press control-4. From here on, the process is almost automatic. Once the receiving process is in operation, a block count will be displayed along with a count of the number of retries attempted and the number of timeouts that have occurred. Usually, these last two parameters will be zero. When the receive operation is complete, you'll be prompted to hit [ENTER] or [BREAK] in order to continue. After doing this, save the file to disk or tape using the appropriate option from the Main Menu.itted must be in the buffer already. Once the transmission is in progress, no further action is required on your part. The transmission routine will terminate automatically at the end of the file. MIKEYTERM Users Manual Version 4.0 Page 11 If the program detects an error while transferring the file, you will see the "retries" count increase as MIKEYTERM tries to recover from the error. If successful, the "retries" count will again be zero. In some cases, MIKEYTERM will not be able to recover, particularly if the line signal is degraded. The transfer will automatically terminate after repeated errors. You can also terminate manually at any time by pressing [BREAK]. If the XMODEM transfer does not succeed, please do not assume that there is something wrong with your computer or with MIKEYTERM. It is suggested that you hang up, re-establish communications over a new line, and try again. A Note on Communications Terminology The MIKEYTERM prompts and documentation generally avoid use of the words 'uploading' and 'downloading'. However, a convention in the mainframe world has been to use 'uploading' to refer to transmitting a file to a remote computer and 'downloading' to refer to receiving a file from a remote computer. Advanced Features: Certain remote computer systems may send unwanted characters to your computer. If you have need to strip or convert certain characters as they are being received, you can specify those and the required stripping/conversion using MIKEYTERM's ASCII filter capabilities. Use the CNFG40 program to configure up to three filtered values according to your particular needs.