COMMODORE 64/128 KERMIT USER'S GUIDE Version 2.1 Preliminary Documentation -- Subject to Revision Version 2.0 & 2.1 Enhancements by Ray Moody User's Guide by Kent Sullivan Dr. Evil Laboratories P. O. Box 190 St. Paul, IN 47272 This preliminary document was produced on April 18, 1988 - - - - - - - - - - - - - - - - - - - Information specific to use at Penn State provided by Neil Dowlin, PSU College of Agriculture May, 1989 SUMMARY OF C-64/128 KERMIT VERSION 2.1 What Kermit Is? The term "Kermit" denotes both a specific protocol for transferring files between computers and those computer programs which can do the transferring. Kermit as a protocol is often called the Kermit Protocol to distinguish it from an actual computer program. Various versions of the Kermit program for different computers also have longer, official names to distinguish themselves. Kermit for the Commodore 64/128 was originally known as Kermit-65. C-64/128 Kermit is a public-domain telecommunications program that utilizes the Kermit protocol for file transfers. The "65" in Kermit-65 signifies that the Commodore 64 has as its microprocessor the 6510A, a member of the 6500 series family, which also includes the Apple II. Kermit for the Commodore 64 was originally translated from Apple II Kermit. Kermit has been in existence for the C-64 (as the Commodore 64 is also known) since March, 1984. Hall of Fame Many people have worked on Kermit, continually adding improvements and fixing bugs. Below is a list of the people who have worked on the Commodore 64/128 Kermit project over the years. Programming: David Dermott Eric Lavitsky Michael Marchiondo Ray Moody Frank Prindle Documentation: Eric Lavitsky Kent Sullivan Version 2.1 Improvements This section describes the improvements this version of Kermit has over the previous version (2.0). If you are a first-time user of Kermit, you may want to move directly to the Introduction to the Kermit User's Guide section. Version 2.1 is the second version of Kermit Ray and I have worked on. The main improvements to Version 2.1 are as follows: + Enhanced DEC VT-100 terminal emulation with support for the VT-100 keypad. Kermit should now work fine on operating systems such as VMS. V2.1 has some VT-102 features added as well: Insert/Delete Line/Character. + Limited Tektronix 4010 graphics terminal emulation. Kermit can plot both graphics and text with a resolution of 320 x 200 (C-64) or 640 x 200 (C-128). + Commodore 128 grey key and numeric keypad support. The grey keys and the numeric keypad, not normally accessible on a C-128 in C-64 mode, are active within Kermit. + A special file-type for transferring C Power (now Power C) source code files. You can now download C source code ASCII files as well as upload C Power source files. All necessary character translations are handled automatically. + A screen driver for the Batteries Included BI-80 80 column card. This device gives a display as nice as the Commodore 128's 80-column hardware, but lacks many attributes such as blinking and bold. In addition to these major improvements, many smaller changes were made. Several bugs were squashed that affected VT-100 emulation, the STATUS command, and other things. For related information, please see Appendix A: Implementation Notes. TABLE OF CONTENTS Section Page SUMMARY OF C-64/128 KERMIT VERSION 2.1 ................................. 1 What Kermit Is? .................................................... 1 Hall of Fame ....................................................... 1 Version 2.1 Improvements ........................................... 1 INTRODUCTION TO THE KERMIT USER'S GUIDE ................................ 2 What You Need to Know .............................................. 2 Recommended Introductory & Supplementary Texts ..................... 2 Dr. Evil Labs' Commitment to the Kermit Project .................... 3 Syntax of Commands ................................................. 3 INTRODUCTORY TUTORIAL .................................................. 3 Booting Kermit ..................................................... 3 Choosing a Screen Driver ........................................... 4 The Three Modes of Kermit .......................................... 4 Command Mode .................................................... 4 Connect Mode .................................................... 6 File-Transfer Mode .............................................. 6 TROUBLESHOOTING ........................................................ 8 USING TERMINAL EMULATION ............................................... 8 VT-100 Emulation ................................................... 8 VT-102 Emulation ................................................... 9 VT-52 Emulation .................................................... 9 TEKTRONIX 4010 EMULATION ............................................... 9 Alpha Text Mode .................................................... 10 Point Plot Mode .................................................... 10 Vector Plot Mode ................................................... 10 SCREEN DRIVER COMPARISON ............................................... 10 C-128 80 Column Driver ............................................. 10 C-64 80 Column Driver .............................................. 10 Batteries Included BI-80 Driver (Standard) ......................... 11 Batteries Included BI-80 Driver (Custom) ........................... 11 C-64 40-Column Driver .............................................. 11 TRANSFERRING FILES ..................................................... 11 Choosing the Correct File-type ..................................... 11 ASCII File-type ................................................. 11 Binary File-type ................................................ 12 C-Power File-type ............................................... 12 PETSCII File-type ............................................... 12 Script File-type ................................................ 12 Setting the File-byte-size ......................................... 12 Using Eight-bit-quoting ............................................ 13 Special File-Transfer Mode Features ................................ 13 COMMAND REFERENCE ...................................................... 13 Command List ....................................................... 13 Command Summary .................................................... 13 Bye ............................................................. 13 Connect ......................................................... 13 Directory ....................................................... 14 Disk ............................................................ 14 Exit ............................................................ 15 Finish .......................................................... 15 Get ............................................................. 15 Quit ............................................................ 15 Receive ......................................................... 15 Restore ......................................................... 16 Save ............................................................ 16 Send ............................................................ 16 Set ............................................................. 16 Set Baud ..................................................... 16 Set Bold ..................................................... 17 General Notes on Color .................................... 17 Set Border ................................................... 17 Set Character ................................................ 17 Set Dark-background .......................................... 17 Set Debugging ................................................ 18 Set Eight-bit-quoting ........................................ 18 Set Escape ................................................... 18 Set File-byte-size ........................................... 18 Set File-type ................................................ 18 Set File-warning ............................................. 19 Set Flow-control ............................................. 19 Set IBM ...................................................... 19 Set Light-background ......................................... 19 Set Local-echo ............................................... 20 Set Parity ................................................... 20 Set Receive .................................................. 20 Set Receive Eight-bit-quote-char .......................... 20 Set Receive End-of-line ................................... 21 Set Receive Packet-length ................................. 21 Set Receive Pad-char ...................................... 21 Set Receive Padding ....................................... 21 Set Receive Quote-char .................................... 21 Set Receive Timeout ....................................... 21 Set RS232-registers .......................................... 22 Set Screen-driver ............................................ 22 Set Send ..................................................... 22 Set Terminal-emulation ....................................... 23 Set Word-size ................................................ 23 Show ............................................................ 23 Status .......................................................... 23 Appendix A: IMPLEMENTATION NOTES ..................................... 24 Summary of Kermit Capabilities .................................... 24 Known Restrictions ................................................ 24 Future Plans for Kermit ........................................... 24 Appendix B: DEFAULT INITIALIZATION SETTINGS .......................... 25 Appendix C: KEYBOARD LAYOUTS ......................................... 25 Commodore 64 Map .................................................. 25 Commodore 128 Map ................................................. 26 Appendix D: UNIX TERMCAP SETTINGS .................................... 26 Appendix E: BI-80 REPLACEMENT ROM INFORMATION ........................ 27 Appendix F: SPECIAL PENN STATE CONVENTIONS ........................... 27 Kermit-65 Simulation of IBM PC Input .............................. 27 Sample Session With Kermit on Commodore 64 ........................ 28 INTRODUCTION TO THE KERMIT USER'S GUIDE What You Need to Know This manual will introduce Kermit to new users as well as provide an organized reference for experienced users. Some basic knowledge of computers is required to use Kermit. New users should understand the basics of computers and telecommunications. Please see Recommended Introductory & Supplementary Texts below for a short list of books recommended for background knowledge. Don't become frustrated if you have problems initially using Kermit. Careful reading of this manual will clear up most problems that you might have. If you have questions, don't be afraid to ask around. Kermit is a very popular program, so many people know how to use it. You may direct any questions to Ray or me at the address on the front of this manual as well. This manual is a preliminary version and is subject to revision. It will be available in final printed form (laser-printed!) beginning in May or June 1988. The final version will also be on-disk as this version is. This manual can be printed out using most any sequential file printer or word processor. All special features such as underlining and bold have been removed from the on-disk manual so it should be printable on any printer. Recommended Introductory & Supplementary Texts The following is a short list of recommended background texts. The area covered is listed first, followed by the title of the text and publishing information. + Basic Commodore Computing: Commodore 64/64C/128 User's Guides. + Basic Telecommunications: Compute!'s Telecomputing on the Commodore 64, Compute! Books. + The Kermit Protocol: Kermit: A File-Transfer Protocol for Universities, 2 parts, Byte magazine, June & July, 1984. Dr. Evil Labs' Commitment to the Kermit Project All Kermit distribution for versions that Ray and I have worked on (Versions 2.0 and later) is handled by Dr. Evil Laboratories. Dr. Evil Laboratories is a small software company in which Ray and I are partners. Our company has the facilities to distribute Kermit much more efficiently than either of us could personally. Also, Dr. Evil Labs has a permanent address, something that we, being in college, don't have. If you have any questions or recommendations concerning Kermit, please contact us at Dr. Evil Labs. Syntax of Commands Most Kermit commands are simple English phrases. Commands are represented in this document in capital letters (e.g., CONNECT) to set them off from any surrounding text. Many standard abbreviations for keys are used. Below is a table showing the abbreviations and what they represent: Abbreviation Actual key Commodore Clear (Shifted Home) Control Delete Insert (Shifted Delete) Spacebar Return ,... Function key 1,2...8 For a list of keys that have been re-defined to implement special characters, please see Appendix C: Keyboard Layouts. INTRODUCTORY TUTORIAL Booting Kermit Kermit is written for the Commodore 64 and 128 (in 64 mode). One Commodore disk drive (or compatible) is required, and a modem. Almost any modem will work except the Commodore 1660. Support for the 1660 modem will be included in a future version. To boot Kermit, follow these easy steps: FOR COMMODORE 64: (PENN STATE SPECIAL ROUTINE) 1. Turn on monitor, drive, and computer. 2. Insert the Kermit disk, label side up, into device 8, drive 0, and close the drive door. 3. Type: LOAD "FAST",8,1 and press and then also Type: LOAD "KERMIT",8 and press FOR COMMODORE 128: 1. Insert the Kermit disk, label side up, into device 8, drive 0, and close the drive door. 2. Turn on the monitor, drive, and computer. 3. Kermit will automatically boot on power-up. Once loaded, you should see the following in black on a grey screen with a blue border: Commodore 64/128 Kermit version 2.1 (68) Type '?' for help Kermit-65> A blinking block cursor should be just to the right of the ">". If you don't see this on your screen, turn off all your equipment and try again. If you still have problems booting Kermit, please see the Troubleshooting section. Choosing a Screen Driver Kermit can use many kinds of displays. You can use either 40 columns (not very useful) or 80 columns (software-driven) on a standard C-64, or, if you have a Batteries Included 80-column card, you can use it too. All of these options are available on a C-128, plus the use of the 128's built-in 80-column display. Kermit defaults to the C-64 80-column screen driver. Each of the screen drivers has its advantages and disadvantages. Not all of the drivers, for example, are capable of supporting features such as underlining or bold. Please see the Screen Driver Comparison section for further details. If you want to switch to a different screen driver now, please see the example given in the Command Mode section below. The Three Modes of Kermit Kermit has three basic operational modes: Command, Connect, and File- Transfer. In Command mode, you can communicate directly with Kermit to change various program settings and also enter either of the two other modes. In Connect mode you can communicate with another computer (known in many other terminal programs as Terminal mode). In File-Transfer mode you may send to and receive files from the computer to which you are connected. Let's begin by learning about Command mode and the Kermit parser. Command Mode When Kermit first boots, you are placed automatically in Command mode. From here you can communicate with the program by typing commands at the "Kermit-65>" prompt. Command mode is really the program's command parser, which is that part of any computer program which takes your command input and tries to interpret it and then execute the appropriate action. Kermit's command parser is very easy to use. Let's begin with a look at the main level commands. At the top of the screen you should see "Type ? for help". So let's do just that: Type a "?". A list of Kermit's main commands (there are 16 of them) should appear on the screen in two columns like this: Kermit-65>? Keyword, one of the following: bye connect directory disk exit finish get help quit receive restore save send set show status The "?" is a very helpful feature of the command parser. You can type a "?" at ANY point in the middle of a command to receive a list of the valid ways to complete the command. A complete list of commands may be found in the Command Reference section. Let's try a slightly more difficult command to give you practice with the parser. For example, let's say we want to change which screen display we are using. After looking at the various main level commands, we deduce that the SET command might be the way to get the job done. Type: SET followed by a space and then a "?" Kermit should respond with a list that looks like this: Kermit-65>set ? Keyword, one of the following: baud bold border character dark-background debugging eight-bit-quoting escape file-byte-size file-type file-warning flow-control ibm light-background local-echo parity receive rs232-registers send screen-driver terminal-emulation word-size After looking through this list, we can determine we need the SCREEN- DRIVER sub-option. Notice that the parser conveniently reprinted the SET command so that we can continue where we left off. So, type: SCREEN-DRIVER followed by a space and a "?". Now we have another list, looking like this: Kermit-65> set screen-driver ? Keyword, one of the following: 40-columns 80-columns bi-80 commodore-128 custom-bi-80 It should now be obvious what to do to change to a different screen driver. Try it out. Now, let's go back to 80 columns. One thing you are probably wondering is, "Do I have to type ALL of that out?" Luckily, no, you don't. The left arrow key (upper left corner of the keyboard) will spell out a command one level at a time for you if you provide it with the first few characters of the command. To try this out, type: SET SC and hit the left arrow. Kermit should spell out SCREEN-DRIVER and put a space at the end. Notice that we had to use "sc" and not just "s". Consulting the list above, we can see why. Both SEND and SCREEN-DRIVER begin with an "s". If we had just typed "s", Kermit would have chosen SEND because it is the first command in the list that meets the specified requirements. The same applies for why we spelled out SET. SEND is before SET in the main command list, making the left arrow useless. So keep in mind that you must always use enough characters to uniquely identify the command before hitting the left arrow. Ok, let's finish our command. Type "8" and hit the left arrow. Kermit should finish the command. Now press . Presto! We're back to 80-column mode, saving 19 character's worth of typing. Not all commands are nearly this long, but the left arrow (along with the "?") can be very helpful. There are a few other useful tricks to know about the parser. They are: 1) Pressing or - instead of to execute a command will clear the screen first and then execute the command. 2) Pressing - while typing a command will back the cursor up to the previous word, erasing any associated text. 3) Pressing - while typing a command will cancel the command by backing the cursor up to the "Kermit-65>" prompt. Connect Mode Connect mode is the mode in which you will spend most of your time while using Kermit because it is in this mode that you can communicate with another computer (often known as the remote host). Now let's prepare to connect to another computer. Type: CONNECT. This command will take us out of Command mode and into Connect mode. If you type CONNECT then hit , the screen will be cleared before entering Connect mode. Every time you enter Connect mode, you will see the message: {Connecting to host: Type Y c to return} This tells us that we are in Connect mode and that to return to Command mode we should type - then type "c". Try it out. Then return to Connect mode. Now we will call the other computer. A Commodore 1670 or other Hayes compatible modem can dial directly from Connect mode via its built-in dialing commands, but with most other modems you will have to dial manually. In other words, Kermit does not have an auto-dial command. Also please note that Kermit currently does not work with the Commodore 1660 modem. It will, however, be supported in a future version. Please see Appendix A: Implementation Notes for further information. We need to check a few things before dialing. Each computer you connect to may have different baud, parity, and word-size requirements. Kermit defaults to 1200 bps transmission, eight bit word length, no parity, and VT-100 terminal emulation. To adjust any of these parameters, escape back to Command mode and use the SET command as we did above to change the screen-driver. For example, to change to 300 bps transmission speed, type: SET BAUD 300. If you wish to save any changes you make as new defaults, please see the SAVE command explanation in the Command Reference section. Once you have set up your communications parameters correctly, all that's left to do is dial the phone and connect to the remote host. File-Transfer Mode Once you have connected to a remote host you may wish to send and/or receive files. With Kermit you can send and receive most any kind of file, as Kermit has automatic translation features for many types of files. For example, you can automatically convert a PETSCII (Commodore's special ASCII) text file to ASCII when sending it to another machine, and vice versa. For a list of the various file-types supported, see the SET FILE-TYPE command explanation in the Command Reference section. The procedures for transferring files with Kermit can differ widely depending on the system to which you are connected. This tutorial can't possibly cover every possible situation. Instead, we will walk through a simple transfer and point out some things of which you should be aware. The MOST important thing when attempting to transfer files with Kermit is to have your file-transfer parameters set correctly! You may want to skip ahead to the Transferring Files section for more information. Now, we will show two examples: 1) uploading a PETSCII sequential text file, converting it to standard ASCII, and 2) downloading a C language program source code file for use with the C Power (now sold as Power C) C compiler for the 64/128. TEXT FILE: We are sending and the other end is receiving. In note form, here is what we need to do: 1) Check file-transfer parameters!! Make sure the FILETYPE is set to PETSCII. 2) Start Kermit on the host machine using the appropriate command. 3) Tell the host Kermit to RECEIVE the file. 4) Escape to Command mode in our Kermit ( - then <"c">). Type SEND followed by the filename of the Commodore text file you wish to send. When the two Kermits have finished transferring the file, you will be returned to Command mode. Type: CONNECT and continue with your login session. NOTE: The recommended parameters (work most of the time) are: File type is PETSCII File byte size is EIGHT-BIT (If possible with the host system) Everything else should retain its default value. C POWER FILE: We are receiving and the host is sending. In note form, here is what we need to do: 1) Check parameters!! Make sure the FILE-TYPE is set to C-POWER. 2) Start Kermit on the host machine using the appropriate command. 3) Tell the host Kermit to SEND the file. 4) Escape to Command mode in our Kermit ( - then <"c">). Type RECEIVE followed by the filename of the C source code file you wish to receive in C Power format. 5) When the two Kermits have finished transferring the file, you will be returned to Command mode. Type: CONNECT and continue with your login session. NOTE: The recommended parameters (work most of the time) are: File type is C-POWER File byte size is EIGHT-BIT Eight bit quoting is ON Parity is NONE (If possible with the host system) Word size is EIGHT-BIT (If possible with the host system) Everything else should retain its default value. If you have persistent problems with transferring files, don't hesitate to ask someone for help. Also try VERBOSE debugging to see more of what is happening during transfers. Kermit is very flexible, but flexible can mean complicated! We now have completed the Introductory Tutorial. The next section of this manual, Troubleshooting, may help if you have some problems using Kermit. The Command Reference section describes in detail each of Kermit's commands and will prove to be invaluable to successfully using this program. Good Luck with Kermit! TROUBLESHOOTING Here are some common problems and their most likely solutions. I have found the best troubleshooting comes from someone who has experience using Kermit, but this isn't always available. 1) Problem: Kermit won't boot. Solution: Make sure all of your equipment is hooked up correctly. If the red error light blinks, you might have a bad disk. Dr. Evil Labs will replace any defect Kermit disks. 2) Problem: I can't get out of Connect mode. Solution: Remember to type - , let up, then hit the letter "c". 3) Problem: When I connect to a host machine, all I get is garbage. Solution: Check the baud, parity and word-size parameters. You may have to hang up and try again if you change some of the parameters. 4) Problem: I can't see what I am typing, but I see what the host machine is sending. Solution: You might need to SET LOCAL-ECHO ON. 5) Problem: I downloaded a binary file but the file I received was garbage. Solution: Remember to SET EIGHT-BIT QUOTING ON. Also, check the file type on the host Kermit. It should be set to BINARY as well as on your end. 6) Problem: All of a sudden output stopped appearing on the screen and nothing I type shows up either. Solution: You may have hit the key accidently, which pauses all I/O temporarily. Pressing it again will re-start I/O. USING TERMINAL EMULATION Kermit is a very powerful terminal emulator. It can emulate both a VT-100 (with or without added VT-102 features) and a VT-52. Emulation can be turned completely off as well. It is beyond the scope of this manual to present each of the escape sequences that a VT-52/100/102 terminal uses. This section will instead describe in general terms what each of the emulations can do. VT-100 Emulation Most people will use Kermit's VT-100 emulation more than any other. The DEC VT-100 terminal is an industry standard, and so is supported on virtually every medium-to-large-sized operating system. The VT-100 terminal provides you with many powerful features that make communicating with a remote host (especially at speeds under 9600 bps) much more efficient and therefore, quicker. The major VT-100 features are summarized below: 1) Scrolling regions. This feature of the VT-100 allows selected parts of the screen to be scrolled, cutting down on character transmission greatly -- making telecommunicating faster. 2) Text attributes. Text on a VT-100 can be displayed in normal or bold, and be vanilla, underlined, or blinking (or any logical combination), and displayed on either a dark or light background. Kermit has the added feature of selectable colors for text, bold text, dark-background, light-background, and border for most screen drivers. 3) Numeric keypad. A VT-100 has a numeric keypad that includes four personal function (PF) keys. Kermit has this feature on both a C-64 and 128. 4) Graphics characters. A VT-100 has a wide range of graphics characters that can be used for graphs on charts. 5) Status line. Kermit has an extra 25th line that can be used as a system status line on operating systems such as UNIX. Note that a standard VT-100 terminal does not have a sysline. For a chart showing what keys have been re-defined in Kermit, please see Appendix C: Keyboard Layouts. Also, if you are using Kermit on a machine running UNIX, please see Appendix D: UNIX Termcap Settings, for information on how to customize your termcap to take full advantage of Kermit's features. Not all of the VT-100's features were feasible to support in Kermit. Below is a list of the VT-100 features not supported: 1) No 132 column mode 2) No double high/double wide characters 3) Limited terminal reports (only the important ones are emulated) 4) No foreign character sets 5) No smooth scrolling 6) No terminal LEDs For related information, please see the Screen Driver Comparison section. VT-102 Emulation Only the four most important VT-102 terminal features are present in Kermit. These are Insert Character, Delete Character, Insert Line, and Delete Line. The Insert Character function is really a switchable Insert/Replace mode. No other VT-102 features are supported. VT-52 Emulation Kermit emulates a VT-52 terminal as a subset of its VT-100 emulation, just as a real VT-100 terminal does. It is a complete emulation, except that the graphics character set is the VT-100's, not a true VT-52's. All of the real VT-100 terminals we have seen also use the VT-100 character set in place of the true VT-52 set in VT-52 mode. TEKTRONIX 4010 EMULATION Kermit supports a limited kind of Tektronix 4010 emulation. Two resolutions are supported: 320 x 200 (C-64) and 640 x 200 (C-128 80 col.). You can use the Tektronix emulation even if you are using a BI-80 card, as Kermit will automatically switch between the appropriate graphics screen and the BI-80. All plots and text are plotted using the current character color and are plotted on the current background color. Both the 320 x 200 and 640 x 200 screens are a little too wide horizontally scale-wise compared with a real Tektronix 4010 terminal. We thought it was better to use the full width of the screen given the limited resolution than to have perfect scaling. Kermit supports three Tek modes: Alpha Text, Point Plot, and Vector Plot, for a total of eight different Tek commands. The commands are: Sequence Action FF (Form Feed) Activate Tek emulation and clear screen RS (Record Separator) Switch to incremental plot mode US (Unit Separator) Switch to alpha text mode GS (Graphics Start) Switch to vector plot mode CAN (Cancel) Deactivate Tek emulation and clear screen Tek mode is also exited when any VT-100/52 escape sequence is received. This includes any sequences beginning with "{" or . Also, once Tek mode is activated, any further FF sequences received will clear the current graphics screen. Finally, the current text screen is not saved when Tek mode is entered, and the current Tek screen is not saved when Tek mode is exited. Alpha Text Mode Alpha Text mode uses the standard ASCII character set and can display 79 columns by 24 lines of text if Tek mode is entered from any of the screen drivers except C-64 40 columns. If Tek mode is entered from the C-64 40 column screen driver, up to 40 columns of text can be displayed. This mode is used generally to label graphs. No on-screen editing should be attempted while in this mode. Point Plot Mode In this mode the drawing pen is given a direction to move and whether to have the pen up (no line drawn) or down (line drawn) when moving. This allows considerable freedom in drawing odd-shaped objects. Vector Plot Mode In Vector Plot Mode, the endpoints of a line to be drawn are specified. This allows lines to be drawn quickly. SCREEN DRIVER COMPARISON Each of Kermit's screen drivers has different capabilities. Below is a discussion of the various limitations of the different screen drivers. C-128 80 Column Driver This driver is the best that Kermit has. All video attributes are supported with no limitations, and the highest Tek resolution (640 x 200) is available. The only feature not available with this driver, that is on some others, is a border. This is because the C-128's 80 column chip (the 8563 VDC) does not support a border. One note: many people who use the 80-column mode on the C-128 do so on a monochrome monitor. With this setup, only three colors are possible: bright, normal, and black. This can pose a problem when trying to set up readable light- and dark-background screens. One solution to this is to buy a grey scale attachment for the 80-column video cable, which will create more shades of intensity. C-64 80 Column Driver This screen driver is traditionally the most popular, mainly because more people have C-64's than C-128's. When this driver is in use, even on a C-128, the Tek 320 x 200 mode will be used if graphics mode is activated. Every feature is available with this driver, but there is one minor limitation. Because of the way hi-res graphics screens are mapped on a C-64, if two characters with different either bold or flashing attributes are placed adjacent horizontally, the first character will not have the correct attribute. For example, if a bold character is printed immediately followed by an flashing character, the bold character will change to a flashing character. This can easily be avoided by inserting a space between the two characters. Batteries Included BI-80 Driver (Standard) The BI-80, an excellent 80-column card for the C-64 (also C-128 in 64 mode), is no longer in production and generally very hard to find used. We added support for it because it offers the same text resolution as the C-128's 80 column screen, making it clearer than the standard C-64 80 column screen. There are several limitations when using this driver. The main limitation is that the BI-80 character set is not redefinable through software, meaning that some characters like the braces, tilde, underscore, etc., are not available. Also, the VT-100/52 graphics character set is not available. A closest match was made on many of the characters, but many of them look pretty unrecognizable. Also, the only character attribute available is reverse. All other modes, such as blinking, bold, and underlined, are mapped into reverse, so you can at least tell when the text is not plain vanilla. Finally, no color change options are available as the BI-80 card operates only in black and white mode with no border. Batteries Included BI-80 Driver (Custom) This driver is for use with the custom BI-80 character ROM available from Dr. Evil Laboratories. This driver makes use of the re-defined characters in the replacement ROM. The full ASCII character set is available, as well as the VT-100/52 graphics character set. All other restrictions from the standard BI-80 driver apply. Please see Appendix E: BI-80 Replacement ROM Information for details on how to obtain a replacement character ROM. C-64 40-Column Driver This driver supports all character attributes and screen functions. Its main limitation is its width -- 40 columns is generally not very useful when communicating with most large computer systems. TRANSFERRING FILES Transferring files with Kermit isn't really any more difficult than with most other Commodore telecommunications packages/protocols. In fact, Kermit is much more flexible -- but that's where confusion begins. There are three major parameters to be concerned with when transferring files. They are: 1) File-type, 2) File-byte-size, and 3) Eight-bit-quoting. Let's discuss each of them in turn, beginning with File-type. Choosing the Correct File-type Kermit currently supports five different file types. They are: a) ASCII b) Binary c) C-Power d) PETSCII e) Script Each of these file types has a distinct use. When to use one file-type over another can be confusing initially. So, we'll discuss each of them separately, starting with ASCII. ASCII File-type This file-type is used a lot less often than you might think at first. Because Commodore computers (except for the Amigas and PCs) use their own, modified character set arrangement (PETSCII), most text files you transfer to and from your Commodore will be PETSCII files, not standard ASCII. You will use this file-type only when you a) wish to down-load a standard ASCII file and not convert it to a form usable on your Commodore (PETSCII), or b) you have, for some reason, a standard ASCII file that you wish to upload to another computer. If you happen to choose this file-type when you really needed PETSCII, you wll be able to tell immediately, as the case of all the text will be reversed. Binary File-type The Binary file-type is not used very often. This file-type is used to transfer Commodore programs that are executable (i.e. a BASIC program or a machine language game, or even Kermit). In other, more technical, terms, this file-type allows you to transfer files that have full eight- bit data words. Text files, by definition, contain only seven-bit data words. Note that it's generally a good idea to have Eight-bit-quoting set on when transferring binary files, but more about that below. C-Power File-type This file-type is designed specifically to transfer source code files for use with the C Power (now Power C) C compiler for the C-64 and C-128. C Power files have, in addition to the standard PETSCII file- type base, a few re-defined characters that are needed for C programming, such as braces, the underscore, the pipe, etc. When you use this file-type, any standard C source code files you download to your Commodore will be converted to C Power format. On the other side of the coin, any C Power files you upload to another computer will be converted to standard ASCII source code files. PETSCII File-type This file-type is the most common file-type, and so it is the default Kermit file-type. When you use this file-type, any Commodore text file you upload to another computer will be converted to standard ASCII text. Going the other direction, when you download a standard ASCII text file to your Commodore, it will be translated to PETSCII. If you choose this file type when you really meant ASCII, the case of all the letters in the text will be reversed. Script File-type This is a special file-type for use when transferring files for the Commodore Speedscript word processor (Compute! Publications). Speedscript files have a special file format. If you want to download a standard text file from another computer for Speedscript, you must use this format. The same applies for sending a Speedscript file to another computer that uses standard ASCII text files. Setting the File-byte-size This parameter is often confused by Kermit users because it sounds a lot like the Word-size parameter. These two parameters are actually quite different. Whereas Word-size describes the data path, File-byte-size describes the size of the data words within files being transferred. This parameter can always be left set to Eight-bit. Technically, though, it is really only necessary to be set to Eight-bit when you are transferring Binary or PETSCII files. Using Eight-bit-quoting This feature allows you to transfer Binary or PETSCII files to and from computers that would normally be unable to handle them. Eight-bit-quoting allows you send files with eight-bit data words over a seven-bit data path. This parameter can always be left set to ON. For instance, I often communicate with a machine where my communications parameters have to be Word-size of Seven-bit and Even Parity. In this kind of environment I would normally be unable to send a program file to a friend on that machine, as program files are Binary (eight-bits). But if I make sure Eight-bit-quoting is ON, everything will be fine. Technically, Eight-bit-quoting prefixes each byte of data that is over seven bits long (greater than ASCII 127 decimal in value) so that it can be transferred along the seven-bit data path. Special File-Transfer Mode Features There are three helpful features available when transferring files. These features are standard in most versions of Kermit. They are: Key Sequence Action Force remote Kermit to re-send current packet - Cancel transmission of current file - Cancel transmission of entire batch of files All of these commands are available when receiving a file or files. Because C-64/128 Kermit can't send more than one file per SEND command (a feature called "wildcard send"), the - feature is not available when sending a file. COMMAND REFERENCE Command List Kermit v2.1 has 16 major commands, most of which have sub-options. Below is a list of the major commands. Bye Connect Directory Disk Exit Finish Get Help Quit Receive Restore Save Send Set Show Status Command Summary Each of the major commands will now be described in alphabetical order. Following the description is one or more examples using the command previously described. Please note that all commands may be entered in either lower or upper case. Case distinction is not made by the Kermit parser. Bye This command will cause C-64/128 Kermit to tell a server Kermit at the other end of the connection to exit from Kermit and, if applicable, terminate its job (or process, etc.). Bye has no arguments, with the format: Kermit-65>bye Connect The CONNECT command puts Kermit into Connect Mode (see the Introductory Tutorial section for more information on Connect Mode). Kermit can then begin communication with another computer as a terminal (as defined by the SET TERMINAL-EMULATION command. Connect has no arguments, with the format: Kermit-65>connect To return to Command Mode (see the Introductory Tutorial section for more information on Command Mode), type the escape character followed by a <"c">. The default escape character is - . The escape character may be followed by characters other than <"c">. The other valid options and what they do can be viewed by substituting a <"?"> for the <"c">, giving the display: One of the following: ? - this help message. b - send a break signal. c - close the connection. s - status of connection. 0 - send a null. escape-char - transmit the escape character. Directory The DIRECTORY command will return a disk directory of the specified files on device 8 (the normal device number for the first serial Commodore disk drive). DIRECTORY with no arguments returns a complete disk directory. The directory may be paused by pressing and resumed by pressing any key, and aborted by pressing . The format is: Kermit-65>directory {filename} where {filename} is a valid CBM DOS filename. Some examples: Kermit-65>directory (directory of all files on device 8) Kermit-65>directory ker* (directory of files beginning with "ker") Kermit-65>directory k?w (directory of files 3 characters long, beginning with "k" and ending with "w") Disk The DISK command will allow you to send DOS commands directly to the disk drive controller. This command is useful for initializing the drive, formatting a disk, and deleting unwanted files. This command supports all the standard Commodore DOS commands, except that no spaces in filenames are allowed. DISK with no arguments will return the drive error in standard DOS format if the drive's red light is blinking. The format is: Kermit-65>disk {string} where {string} is a valid CBM DOS command. Some examples: Kermit-65>disk s0:k* (delete all files beginning with "k" on device 8) Kermit-65>disk i0: (initialize device 8) Kermit-65>disk n0:files,01 (format disk in device 8, giving it name "files" and id "01" -- note the lack of spaces in the disk name chosen) Exit The EXIT command will cause C-64/128 Kermit to stop execution and return control of the machine to BASIC. This command is the same as the QUIT command. Kermit may be restarted immediately with the command RUN. If you type NEW, Kermit can still be restarted most of the time with the command SYS 2064. Exit has no arguments. The format of this command is: Kermit-65>exit Finish This command will cause Kermit to tell a server Kermit at the other end of the connection to exit. When C-64/128 Kermit receives the acknowledgement that this is being done, you will be prompted for another command. Finish has no arguments. The format of this command is: Kermit-65>finish Get This command will cause C-64/128 Kermit to request that the other Kermit (which must be running in server mode) to transmit the specified file to the C-64/128 Kermit. The format of this command is: Kermit-65>get {file-specification} where {file-specification} is a valid file specification for the system on which the other Kermit is running. Quit This command will cause C-64/128 Kermit to return to the BASIC command level. QUIT is identical to the EXIT command (see EXIT above for more information). QUIT has no arguments, with the format: Kermit-65>quit Receive The RECEIVE command makes C-64/128 Kermit wait for the Kermit on the other end of the connection to initiate a file transfer. The format for this command is: Kermit-65>receive {filename} where {filename} is any valid CBM DOS file name not containing spaces. If no file name is given, C-64/128 Kermit will wait for a file transfer initialization sequence from the other Kermit. If a file name is given, that file name will be used to store the received file(s), regardless of what name is supplied by the other Kermit. If more than one file is received, the second file will have a ".00" appended to it. The third file will have a ".01", and so on. The file name will be truncated appropriately to accommodate the ".XX" suffix. If FILE-WARNING is turned OFF, the ".XX" suffix scheme will not be used -- the file will be continuously overwritten. Some examples: Kermit-65>receive Kermit-65>receive myfile Restore The RESTORE command is used to re-initialize Kermit parameters that have been previously saved with the SAVE command. Kermit will search the disk in device 8 for a file named KERMIT.INI. If the file is present on disk, Kermit will load the parameters contained therein and restart itself with those parameters. If no KERMIT.INI file is found, Kermit's parameters will be trashed and must be reset by hand or by another RESTORE command (with a disk containing a KERMIT.INI file). RESTORE has no arguments, with the format: Kermit-65>restore Save The SAVE command will save to the disk in device 8 the current Kermit settings and parameters in the file KERMIT.INI. If a KERMIT.INI already exists on the disk, no attempt is made to write over the existing file. The red light on the disk drive will blink, indicating error #63, It can be scratched using the DISK command, however. The parameters may later be recalled with the RESTORE command. SAVE has no arguments, with the format: Kermit-65>save Send The SEND command allows you to send a file to the other Kermit. The command format is: Kermit-65>send {filename} where {filename} is any normal CBM DOS filename. Please note that C-64/128 currently does not have a wildcard send capability. In other words, the entire file name must be specified -- no pattern matching is allowed. Also, only one file may be sent per SEND command. Set The SET command is used to alter various parameters in Kermit. The format of the command is: Kermit-65>set {option} {suboption}... where {option} is one of the following: Baud Bold Border Character Dark-background Debugging Eight-bit-quoting Escape File-byte-size File-type File-warning Flow-control IBM Light-background Local-echo Parity Receive RS232-registers Screen-driver Send Terminal-emulation Word-size Many of the above options have sub-options. A description of the options and sub-options follows. Set Baud The SET BAUD command is used to set the speed at which communications will take place. Kermit-65>set baud {value} where {value} is one of the following: 50 75 110 150 300 1200 1800 2400 Please note that communication speeds above 1200 are unreliable at best -- they may not work at all for you, depending on your set-up. Set Bold The SET BOLD command sets the bold character color, which can be used for highlighting text in VT-100 emulation mode. An example of bold text is the "Type ? for help" message when Kermit boots. The default bold color is white. The format of this command is: Kermit-65>set bold {color} where {color} is one of the following: Black Blue Brown Cyan Dark-grey Green Light-blue Light-green Light-grey Light-red Medium-grey Orange Purple Red White Yellow GENERAL NOTES ON COLOR The colors in the above table correspond exactly to the C-64 VIC chip colors. A closest mapping was done for the C-128 8563 VDC (the 80-column chip) but orange is really a dark purple while medium-grey has a greenish tint. Also, note that: 1) the C-128 display has no border 2) the BI-80 has no color options or border -- and, any bold text is printed as reverse 3) none of the SET commands for color currently have a corresponding SHOW command Set Border The SET BORDER command sets the border color, which is available only when using the C-64 40 or 80 column screen drivers. The default border color is blue. The format of this command is: Kermit-65>set border {color} where {color} is one of the colors listed under the "Set Bold" section. Set Character The SET CHARACTER command sets the normal character color. The default character color is black. The format for this command is: Kermit-65>set character {color} where {color} is one of the colors listed under the "Set Bold" section. Set Dark-background The SET DARK-BACKGROUND command sets the VT-100 dark background color (the one normally used). This is also the background color used in VT-52 mode or when no terminal emulation is used. The default dark- background color is medium-grey. The format for this command is: Kermit-65>set dark-background {color} where {color} is one of the colors listed under the "Set Bold" section. Set Debugging The SET DEBUGGING command is used to set the type of debugging generated by C-64/128 Kermit during a file transfer. The format is: Kermit-65>set debugging {keyword} where {keyword} is either OFF, TERSE, or VERBOSE. OFF causes all debugging output to be suppressed. TERSE directs a copy of each packet to the screen, printing any control characters as CTRL-"char". VERBOSE prints identifying text for each field in the header and prints the actual data section of the packet in the same manner TERSE uses. Set Eight-bit-quoting This command will turn on or turn off the eight-bit-quoting feature. Eight bit quoting is used to transmit eight-bit bytes over a seven- bit data path. If the FILE-BYTE-SIZE is SEVEN-BIT, eight bit quoting allows full eight-bit data to still be transmitted. If the FILE- BYTE-SIZE is EIGHT-BIT, the quoting is ignored as it is not needed. The format of the command is: Kermit-65>set eight-bit-quoting {keyword} where {keyword} is ON or OFF. Set Escape This command will set the escape character, which is the character used to "escape" back to Command Mode from Connect Mode. The command will take a hexadecimal value of the chosen character to use as the escape character. It defaults to - ($19). It is usually a good idea to set this character to something which is not used (or at least not used very much) on the system to which C-64/128 Kermit is connected. The format of the command is: Kermit-65>set escape {hex value} where {hex value} is the ASCII value, in hex, of the character to use as the escape character. Set File-byte-size This command sets the byte size C-64/128 Kermit will use for files being received or transmitted. The file byte size can almost always be EIGHT-BIT, as this setting will work for most SEVEN and EIGHT-BIT data files. The format of this command is: Kermit-65>set file-byte-size {size} where {size} is SEVEN-BIT or EIGHT-BIT. Set File-type This command tells Kermit what type of file is being sent or received. It is important that this parameter be set correctly since it is used to determine the exact file length when sending files in addition to determining special processing which may have to be done (i.e. when receiving a text file, write all characters in PETSCII). The format of this command is: Kermit-65>set file-type {type} where {type} is ASCII, BINARY, C-POWER, PETSCII, or SCRIPT. An ASCII type file is any standard ASCII text file. A BINARY type file is a memory image (i.e. machine language program, graphics screen, etc.) and is normally transferred in eight-bit mode. A C-POWER type file is a C language source file for use with the C Power C compiler from Pro-Line (now Power C from Spinnaker). A PETSCII type file is a CBM ASCII text file. A SCRIPT type file is a file produced by the Speedscript word processor published by Compute! Publications. Set File-warning This command determines what C-64/128 Kermit will do when it receives a file with a filename that already exists. If FILE-WARNING is turned ON, C-64/128 Kermit will not overwrite the old file. Instead, it will create a file with the original file name with a ".00" appended to it. It will increment the ".XX" number until it succeeds in creating a unique file name. If FILE-WARNING is turned OFF, C-64/128 Kermit will overwrite the existing file. The format of this command is: Kermit-65>set file-warning {keyword} where {keyword} is either ON or OFF. Set Flow-control The SET FLOW-CONTROL command enables or disables XON/XOFF flow control. With flow control on, C-64/128 Kermit will automatically send a - to the host computer when it can't keep up to prevent loss of characters (i.e. buffer full). Kermit will then send a - when it is ready to receive more data. This option is recommended for communication speeds of 1200 baud or higher. The format of this command is: Kermit-65>set flow-control {keyword} where {keyword} is either ON or OFF. Set IBM The SET IBM command sets up C-64/128 Kermit to communicate with certain IBM mainframes. This command is needed on a limited number of systems. The format of this command is: Kermit-65>set ibm {keyword} where {keyword} is either ON or OFF. With IBM mode on, C-64/128 Kermit will wait for the IBM turnaround character (XON, CTRL-Q) before sending any characters to the other Kermit. It also forces the parity type to be mark, the word length to be seven-bit, turns on local echo for the CONNECT command and turns off flow-control. All of these changes are temporary. When IBM mode is turned off, the parameters altered will return to their previous values. Set Light-background The SET LIGHT-BACKGROUND command sets the VT-100 light background color (the one not normally used). The light background is generally used only by programs to catch your attention (usually by flashing the background color quickly). The default light-background color is light-grey. The format for this command is: Kermit-65>set light-background {color} where {color} is one of the colors listed under the "Set Bold" section. Set Local-echo The SET LOCAL-ECHO command specifies whether characters should be echoed locally when connected to another computer. If LOCAL-ECHO is set ON, any character typed on the C-64/128 will be echoed immediately to the C-64/128 as well as being sent to the other computer. If LOCAL-ECHO is set OFF, the characters typed on the C-64/128 are sent only to the other computer (which would normally echo the characters). The format of this command is: Kermit-65>set local-echo {keyword} where {keyword} is either ON or OFF. Set Parity This command determines the type of parity to use during communication. Kermit normally uses characters which consist of eight data bits with no parity bit. For systems or transmission media which require a specific parity type, Kermit can send characters as seven data bits plus a parity bit. The format of this command is: Kermit-65>set parity {keyword} where {keyword} is one of the following: NONE (default) - eight data bits and no parity bit. MARK - seven data bits with the parity bit set to one. SPACE - seven data bits with the parity bit set to zero. EVEN - seven data bits with the parity bit set to make the overall parity even. ODD - seven data bits with the parity bit set to make the overall parity odd. Set Receive It is possible to set various parameters associated with the receiving of data from the Kermit on the other end of the connection (the remote Kermit). SET RECEIVE will enable you to set the various receive parameters. The format of this command is: Kermit-65>set receive The suboptions of the SET RECEIVE command are: Eight-bit-quote-char End-of-line Packet-length Pad-char Padding Quote-char SET RECEIVE EIGHT-BIT-QUOTE-CHAR This command sets the character to be used to quote characters when EIGHT-BIT QUOTING is ON. The default value is hexadecimal 26 (decimal 38, ASCII "&"). Please see SET EIGHT-BIT QUOTING for further information. The format of this command is: Kermit-65>set receive eight-bit-quote-char {value} where {value} is the ASCII value of the character (in hex) to use for eight-bit quoting. SET RECEIVE END-OF-LINE This will set the end of line character that C-64/128 Kermit expects to receive from the remote Kermit. This is the character which terminates a packet of data during file transmission. The default value is hexadecimal 0D (ASCII - , which is ). The format of this command is: Kermit-65>set receive end-of-line {value} where {value} is the ASCII value of the character to use for the end of line character (in hex). SET RECEIVE PACKET-LENGTH This will set the receive packet length. The value for this parameter must be between hexadecimal 0A (decimal 10) and $60 (decimal 96). Packet lengths outside of this range are illegal. The default value is $5E (94 decimal). The format of this command is: Kermit-65>set receive packet-length {value} where {value} is ASCII value of the receive packet length (in hex). SET RECEIVE PAD-CHAR This parameter is the padding character that is expected from the remote Kermit. The parameter must be a hex number between 0 and $1F or $7F. All other values are illegal. The default value is 0 (ASCII NUL). The format of this command is: Kermit-65>set receive pad-char {value} where {value} is the ASCII value of the character to be used as a pad character (in hex). SET RECEIVE PADDING This command sets the number of padding characters that will be expected from the other Kermit. The default value is 0. The format of this command is: Kermit-65>set receive padding {value} where {value} is the number (in hex) of padding characters to use. SET RECEIVE QUOTE-CHAR This command sets the quoting character that C-64/128 Kermit will expect on incoming files. This is the character used to quote control characters. The default value is $23 (ASCII "#"). The format of this command is: Kermit-65>set receive quote-char {value} where {value} is the ASCII value of the quoting character (in hex). SET RECEIVE TIMEOUT This command sets the number of seconds that C-64/128 Kermit will wait for acknowledgement before it will retry sending or receiving the current packet of data (during a RECEIVE or GET). The default value is 15 seconds (hex 0F). Kermit-65>set receive timeout {value} where {value} is the number of seconds to wait for a message from the remote Kermit (in hex). Set RS232-registers This command sets the 2 RS-232 registers in the C-64/128 that control the baud rate, parity, etc. The 2 registers are treated as a 16 bit hex integer. The first 2 digits are the SECOND register and the last 2 digits are the FIRST register. If only 2 digits are entered, the second register is cleared. The format of this command is: Kermit-65>set rs232-registers {value} where {value} is a four-byte long hex integer. Some examples: Kermit-65>set rs232-registers 0006 sets the registers to 06,00 for 300 baud, 8 bit, no parity Kermit-65>set rs232-registers a026 sets the registers to $26, $A0 for 300 baud, 7 bit, parity mark. See the Commodore 64 or 128 Programmer's Reference Guides for a complete description of the RS-232 registers. Set Screen-driver This command switches the display mode. Kermit is capable of displaying text in 40 and 80 columns, using the Batteries Included BI-80 80 column card, and also using the Commodore 128's 80 column screen. Not all of the displays are capable of completely accurate displays. For example, the standard Batteries Included 80 column character set does not include certain standard ASCII characters. In all cases the best compromise was made to provide the most accurate display. The format of this command is: Kermit-65>set screen-driver {keyword} where {keyword} is 40-COLUMNS, 80-COLUMNS, BI-80, COMMODORE-128, or CUSTOM-BI-80. Set Send It is possible to set various parameters associated with the sending of data to the remote Kermit. SET SEND will enable you to set the various SEND parameters. These parameters should not normally be changed since, as part of the transfer initialization process, the two Kermits exchange their RECEIVE parameters. The capability of setting these parameters is provided so that the transfer initialization can be completed even if the default parameters are not correct. The format of this command is: Kermit-65>set send The suboptions of the SET SEND command are: Eight-bit-quote-char End-of-line Packet-length Pad-char Padding Quote-char The suboption descriptions for the SET SEND command are the same as those for the SET RECEIVE command (except that they affect sending, not receiving, parameters). So, to avoid redundancy, please refer to the appropriate suboption descriptions under the SET RECEIVE section for further information. Set Terminal-emulation Kermit is capable of emulating two popular terminals, as well as act as a dummy (glass) terminal. The SET TERMINAL-EMULATION command changes the type of terminal Kermit emulates. The format for this command is: Kermit-65>set terminal-emulation {type} where {type} is NONE, VT-52, or VT-100. Kermit provides very accurate emulation of the DEC VT-52 and VT-100 terminals. In VT-100 mode, Kermit can perform most all functions of a VT-100 terminal, including displaying a graphics character set as well as emulate certain VT-102 sequences. Set Word-size This option sets the data word length for communication with another computer. Although word lengths below seven bits exist, C-64/128 Kermit only supports seven and eight bit word lengths. The format of this command is: Kermit-65>set word-size {length} where {length} is either SEVEN-BIT or EIGHT-BIT. Show The SHOW command will allow you to show the various parameters that are set with the SET command. Kermit-65>show