Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP Path: utzoo!watmath!clyde!caip!brl-adm!brl-smoke!smoke!zben@umd5.umd.EDU From: zben@umd5.umd.EDU Newsgroups: net.sources Subject: Kermit ][ (file 1 of 3) Documents Message-ID: <4710@brl-smoke.ARPA> Date: Fri, 17-Oct-86 20:36:14 EDT Article-I.D.: brl-smok.4710 Posted: Fri Oct 17 20:36:14 1986 Date-Received: Tue, 21-Oct-86 22:23:08 EDT Sender: news@brl-smoke.ARPA Lines: 1556 GVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGV From: Ben Cranston Subject: Kermit ][ (file 1 of 3) Documents To: unix-sources@brl-smoke.arpa Return-Path: Received: from BRL-SMOKE.ARPA by Xerox.COM ; 17 OCT 86 16:35:33 PDT Received: from USENET by SMOKE.BRL.ARPA id a017123; 17 Oct 86 15:33 EDT Newsgroups: net.sources Message-ID: <1293@umd5> Original-Date: 16 Oct 86 20:48:49 GMT Keywords: kermit apple GVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGVGV Well, we finally got the manual scanned, and with about a day of manual editing it is reasonably usable (though certainly not perfect). Look for the source code over the next several nights. Thanks to Chris Torek and Liz Allen for the sharmaker. ------------ cut here ------------ : Run this shell script with "sh" not "csh" PATH=/bin:/usr/bin:/usr/ucb:/etc:$PATH export PATH all=FALSE if [ x$1 = x-a ]; then all=TRUE fi echo Extracting man.readme sed 's/^X//' <<'//go.sysin dd *' >man.readme Some notes on the manual "manual.txt" file. I started from a xerox of a xerox of a xerox of a Daisy output that had overstrike bolding, underlining, and margin bars. We used a Kurzweil scanner to re-input the text. The bolding and margin bars didn't make it. The underlining was manually entered, with the control strings "u" signalling start-underlining and end-underlining respectively. The shell script "man.ul" just removes these control strings, so it can be used if your output device does not do underlining. If you have access to a device that does have underlining, you can use an analagous shell script to change the control strings into the control sequences your device uses to make underlining. Page-ups are marked by a "formfeed" character in the text. I hope they make it through the distribution process... //go.sysin dd * if [ `wc -c < man.readme` != 842 ]; then made=FALSE echo error transmitting man.readme -- echo length should be 842, not `wc -c < man.readme` else made=TRUE fi if [ $made = TRUE ]; then chmod 644 man.readme echo -n ' '; ls -ld man.readme fi echo Extracting man.ul sed 's/^X//' <<'//go.sysin dd *' >man.ul sed u//g' //go.sysin dd * if [ `wc -c < man.ul` != 42 ]; then made=FALSE echo error transmitting man.ul -- echo length should be 42, not `wc -c < man.ul` else made=TRUE fi if [ $made = TRUE ]; then chmod 755 man.ul echo -n ' '; ls -ld man.ul fi echo Extracting manual.txt sed 's/^X//' <<'//go.sysin dd *' >manual.txt Appendix A-2 Kermit-][ for the Apple II July 1985 A2-i APPENDIX A-2 TABLE OF CONTENTS A2.1 Introduction . . . . . . . . . . . . . . . . . . . . . 1 A2.2 Getting started . . . . . . . . . . . . . . . . . . . 1 A2.3 SET and SHOW or STATUS commands . . . . . . . . . . . 1 A2.3.1 Baud . . . . . . . . . . . . . . . . . . . . . 2 A2.3.2 Local-echo . . . . . . . . . . . . . . . . . . 2 A2.3.3 Parity . . . . . . . . . . . . . . . . . . . . 2 A2.3.4 Slot . . . . . . . . . . . . . . . . . . . . . 2 A2.3.5 Card . . . . . . . . . . . . . . . . . . . . . 2 A2.3.6 Mark . . . . . . . . . . . . . . . . . . . . . 2 A2.3.7 Timeout . . . . . . . . . . . . . . . . . . . . 3 A2.3.8 File-warning . . . . . . . . . . . . . . . . . 3 A2.3.9 Debug . . . . . . . . . . . . . . . . . . . . 3 A2.3.10 Phone . . . . . . . . . . . . . . . . . . . . 3 A2.3.11 Scroll . . . . . . . . . . . . . . . . . . . . 4 A2.3.12 Video . . . . . . . . . . . . . . . . . . . . 4 A2.3.13 Escape . . . . . . . . . . . . . . . . . . . . 4 A2.3.14 Drive . . . . . . . . . . . . . . . . . . . . 5 A2.3.15 End of Line (EOL) . . . . . . . . . . . . . . 5 A2.3.16 Repeat-Proc . . . . . . . . . . . . . . . . . 5 A2.3.17 Save . . . . . . . . . . . . . . . . . . . . . 6 A2.4 Giving a DOS command within Kermit-][ . . . . . . . . 6 A2.5 CONNECT command . . . . . . . . . . . . . . . . . . . 6 A2.6 BREAK command . . . . . . . . . . . . . . . . . . . . 7 A2.7 Returning to Kermit-][ . . . . . . . . . . . . . . . . 8 A2.8 Transferring files from micro to host . . . . . . . . 8 A2.9 Transferring files from host to micro . . . . . . . . 10 A2.10 Exiting Kermit-][ . . . . . . . . . . . . . . . . . 12 A2.11 Converting an Applesoft BASIC file to a text file . . 12 A2.12 Converting text file to Applesoft BASIC program . . . 13 A2.13 Converting Apple binary file to/from text file . . . 13 A2.14 Kermit-][ transfer error messages . . . . . . . . . . 14 A2.15 Adding to or changing Kermit-][ code . . . . . . . . 18 A2-ii APPENDIX A-2 TABLE OF CONTENTS A2.16 Files on your Kermit-][ distribution disk . . . . . . 19 A2.17 Configuring a Kermit-][ working disk . . . . . . . . 22 A2.18 Modifying the KERMITA program . . . . . . . . . . . . 23 A2.19 Recent Improvements to SERDAC Kermit-][ . . . . . . . 24 Note: Changes to the original Kermit-][ documentation in Appendix A-2, published in May 1985, have been noted with vertical lines in the page margins. For a summary of major changes, see Section A2.19. A2-iii Appendix A-2 Kermit-][ for the Apple II A2.1 Introduction Kermit-][, Apple Kermit, can transfer sequential ASCII text files, with logical line lengths up to 256 characters, between an Apple II, II+, or IIe, running Apple DOS 3.3 (or any compatible Apple DOS operating system) and any host computer that is running its own version of Kermit. This appendix assumes that you know how to use both the Apple and the host you want to communicate with. The examples assume that you are communicating with the Sperry UNIVAC 1100, but it would be fairly easy to modify the commands to apply to other host computers. The commands necessary on the micro would remain essentially the same, no matter what host you are communicating with. There is a separate Appendix B describing the Kermit implementation for each SERDAC host computer. In the following examples, what Kermit (or the current computer operating system) prints is u, what you should type is shown with bold type, and explanation and comments appear in ordinary type. A carriage return is indicated as (cr). You can abbreviate any Apple Kermit command, as long as the abbreviation is unambiguous. A2.2 Getting started To run Kermit-][, either boot with the Kermit-][ distribution disk, or, if you have previously booted with another disk, insert the Kermit-][ disk, and type EXEC GOKERM (cr) (if you would like an illustrated introduction to Kermit-][, insert the Kermit-][ disk, and type EXEC GOKERMIL (cr). After Kermit-][ is loaded, you will receive the prompt >u. You need not keep the Kermit-][ disk in the Apple's drive once Apple Kermit has been loaded, except when you need to SET SAVE command parameters (see Section A2.3.17). Typing HELP (cr) or ? (cr) at the prompt provides a list of valid Kermit-][ commands. A2.3 SET and SHOW or STATUS commands Before you connect to another computer, you must set certain Kermit-][ parameters. To display the current settings of these parameters, type SHOW (cr) or STATUS (cr). To change a parameter, use a SET command. To determine a parameter's possible values, follow the command with a question mark, e.g.: SET LOCAL-ECHO ? (cr) u A2- 1 Note that although SET commands apply in most cases, due to hardware limitations, not all SET commands have an effect. For example, if you are using a Hayes Micromodem II, SET BAUD 1200 has no effect, since that modem works only at 300 baud. A2.3.1 Baud Your modem, serial interface card, and host system determine the correct baud rate to use. Default is 300. A2.3.2 Local-echo Set this parameter to ON when connecting with a host such as the UNIVAC 1100, which does not echo characters back to your terminal. Set it to OFF if the host does echo back characters (echoplex). Default is ON. A2.3.3 Parity Set parity to the parity of the host system. Default is EVEN. A2.3.4 Slot This is the Apple II slot number containing the serial interface or modem card you are using. Default is 2. A2.3.5 Card This parameter names the serial interface or modem card you are using. Kermit-][ is currently implemented for the following: Card SET CARD value Hayes Micromodem II MICROMODEM (or MIC) Apple Super Serial Card SUPER SERIAL (or SUP) Cal Comp Sys 7710-D Serial Card CCS Apple Communications Serial Card COMMUNICATIONS (or COM) Novation Apple Cat Modem NOVATION (or NOV) Default is MICROMODEM. A2.3.6 Mark Along with certain special pieces of information, characters in a text file are grouped into units called u before being sent to the other computer during a file transfer. The first character of a packet is always the u character, which by default is CTRL-A (ASCII 001). On some systems, ASCII 001 may be a flow control character- for instance, it might mean "disconnect." Therefore, it may be necessary with some hosts to set MARK to some other character. Default is 001. A2- 2 A2.3.7 Timeout This is the time in seconds after which the Apple will u (abort a transfer) if it gets no response from the host system. If the host response time is very slow, or if the message u appears, set TIMEOUT to a larger number. Default is 10 seconds. A2.3.8 File-warning In most cases, it is desirable to set FILE-WARNING to ON. This causes Kermit-][ to check your disk when receiving a file to see if that file already exists. If it does exist, then you are given the option to append the new file to the existing one, to overwrite the existing file, or to specify a new file name. Default is ON. A2.3.9 Debug In most cases, DEBUG should be set to OFF. If you would like to see every character (Kermit protocol characters plus actual text) that is transmitted through the serial port during a transfer, DEBUG should be set to ON. This would normally not be done unless you were trying to debug a new version of Kermit-][ or to try to discover why a particular transfer was not working correctly. Having DEBUG ON does increase the time required for a file transfer, so you may wish to use it sparingly. A2.3.10 Phone There are four possible settings of the PHONE parameter: 1. If you are using a Hayes Micromodem II, set the PHONE parameter to the host's phone number; for example, SET PHONE 5530803. If you set the PHONE parameter to NONE, Kermit-][ prompts you to enter a number. Direct keyboard commands to the Micromodem are not available through Kermit-][. 2. If you are using a Novation Apple Cat Modem, set the PHONE parameter to NONE. If you have Apple Cat firmware, you will be directed to use firmware commands to dial the host. If you do not have firmware, then you will have to physically dial-up the host using an alternative Apple II data communications program u you run Kermit-][. There is presently no Kermit-][ autodial capability for this equipment. 3. If you are using a serial interface card and an external modem combination that permits autodialing, set the PHONE parameter to the appropriate modem command plus the phone number. For example, if you are using a Hayes Smartmodem, you might SET PHONE ATDT5530803. If you set the phone A2- 3 parameter to NONE, you can type modem commands and the telephone number after issuing the CONNECT command. 4. If you are definitely not using an autodial system, set the PHONE to NONE. After you CONNECT, you will be given an opportunity to do a manual dialup. Default is NONE. A2.3.11 Scroll You can set the SCROLL to ON or OFF. If SCROLL is ON, the actual text of the file being transferred will be scrolled onto your screen. While this is handy to see where you are in the file transfer, it does increase the time required for the transfer. Default is ON. A2.3.12 Video The video features of Kermit-][ are quite nice. Most of the information scrolled onto your screen is done in hi-res. The program has its own hi-res character set, so you can see transmitted characters in the proper case, without having to have any special hardware such as an 80 column card (you still cannot type lower case characters on an unequipped Apple II, though). If you have a good monitor (not a TV), you may also see a 70 column display rather than the normal 40 column display. Optionally, you may also look at scrolled data in u, that is black on white. There are four parameters you can set with the SET VIDEO command:. I Reverse video N Normal video (default) A Auto line feed M No auto line feed (default) T Truncate at right edge W Wrap around to next line (default) 4 40 column display (default) 7 70 column display For example, to set the display for reverse video and 70 columns, enter: SET VIDEO I7 (cr). A2.3.13 Escape As explained in Section 3.3, once you are connected to the host, there must be a way for you to get back to the micro. This is accomplished with an escape character or sequence. As you type each character on the micro keyboard, it is checked to see A2- 4 if it is the escape character or if it is part of the escape sequence. When the character or sequence is recognized, control is returned to the micro Kermit. The escape character or sequence should always be easily typed on your keyboard and something rather unique that you would never output to the host in normal operations. Although it has a somewhat different meaning in other Kermits, the authors of Kermit-][ chose the default escape character to be ESCape. That is a sensible choice, but if you would like for it to be another character, you can specify it with the SET ESCAPE command. The parameter value should be the u value of the ASCII code- a value between 1 and 127. Default is 27, the decimal value for ASCII ESC. A2.3.14 Drive Sometimes while using Kermit-][, it is convenient to switch the default disk drive from 1 to 2 or vice versa. This can be accomplished by issuing some "throwaway" DOS command as described in Section A2.4 (e.g., CTRL-D CATALOG,D2), but it is much simpler just to use a SET command (e.g., SET DRIVE 2). Note that using the ,Dn specification with the SEND or RECEIVE commands (see Sections A2.9 and A2.8) also effectively changes the default drive. You may wish to use a SET DRIVE command to switch back to the other drive once a particular transfer is completed. Note that when you SET SAVE (see Section A2.3.17), the drive setting is always saved with the value 1. A2.3.15 End of Line (EOL) The Kermit protocol provides for the specification, by each computer participating in an exchange, of a character to denote the end of a terminal input line (in the case of Kermit, the end of a packet). In most systems, this character is the carriage return (ASCII code 13). The Apple doesn't really care what the value of EOL is; Kermit-][ will end packets (and recognize the end of packets) with whatever character the host wants to use. The catch is that both the Apple and host must agree on what EOL is, and for agreement, YOU must tell Kermit-][ what character the host needs to detect. Default is 13. A2.3.16 Repeat-Proc Kermit-][ allows for limited u when RECEIVEing data. With most data, the default processing (Repeat-Proc = ON) is sufficient; transfers may be accomplished without loss of data or any problems, and the special processing will save transmission time. If you are RECEIVEing data with many long strings of repeated characters, Kermit-][ repeat character processing may fail, and you will receive the message u If this happens, change the default by typing SET REPEAT-PROC OFF. Then, restart the transfer on both the host and the Apple. See Section A2.14 (REC A2- 5 BUFFER OVERFLOW) for further information. Default is ON. A2.3.17 Save Since it would be very cumbersome to reset all the above parameters each time you use Kermit-][, you can use a SET SAVE command to save the current parameter settings onto your Kermit-][ diskette (note that DRIVE is always saved with a value of 1). Each time you run Kermit-][, the parameters are automatically loaded back and become the initial settings for the program. The distribution disk contains a KERMIT/SETSAVE file with the above described default settings. You may reset them as required, and your settings, if saved, will become the new defaults. A2.4 Giving a DOS command within Kermit-][ You need not exit from Kermit-][ to issue most required Apple DOS commands (e.g., CATALOG, DELETE, RENAME). Instead, type CTRL-D at the >u prompt, followed immediately by the DOS command and (cr). If the DOS command you give is illegal, you will receive the message u. If the command is not executable (e.g., you try to delete a non-existent file), you will receive the message u. A2.5 CONNECT command The CONNECT command lets you log onto a host system as well as to return to terminal operation from Kermit-][. The u time you use a CONNECT command, and subsequently, whenever you reSET the local-echo, parity, baud, card, slot, or phone parameters, Kermit-][ initializes itself with the last values you SET and readies itself for a new dial-up and log-on to the host. If you are already logged-on to the host, this may break the connection and force you to log-on again. You may also have to reSET any Kermit parameters you SET previously. Otherwise, CONNECT commands merely return you to the host. Remember: Normally, to u Kermit-][, you must reSET at least one of the parameters listed in the paragraph above. You may SET the parameter to the same value it had previously, but it must be SET (e.g., if you were using the CCS card, you could initialize Kermit-][ by typing SET CARD CCS (cr)). Kermit-][ u be initialized anytime you wish to CONNECT to a host the first time (dial-up and log-on). Kermit-][ does u need to be reinitialized once you are physically connected to a host. If it u reinitialized while you are connected, the connection may be broken. Note: You may CONNECT to and log onto a host once all SET parameters have been correctly established. However, there may A2- 6 be DIP switch settings required on your serial interface or modem card that you will also have to change. On the Super Serial Card, for example, the terminal/modem block must point towards modem. On the CCS card, you must set the DIP switches for the desired baud rate. See your particular serial card or modem card manual for required switch settings! You should now be ready to log-on to a host. Type CONNECT (cr) at the >u prompt. As mentioned in Section A2.3.10, there are four different ways of dialing up a host. Consult Appendix D if you are not using a modem, or if you have difficulty connecting. If you are using an autodial modem and have set the PHONE parameter accordingly, just wait for the modem's response telling you that the host's modem has answered the phone and that you have a carrier signal. This is usually a u message. If you are manually dialing, you will be instructed to do so. If you do not get a connection (the host number is busy, for example), most autodial modems send a message u and hangup. If this happens, with one of the supported serial cards installed, you may reinitialize Kermit-][ (without issuing a SET command) and retry the same phone number by typing the Kermit-][ escape character ESCape, followed immediately (within 2-3 seconds) by the letter N. When you see the prompt, just type CONNECT (cr) . If the retry fails, or if you are using one of the supported internal modems, you will then have to ESCape back to Kermit-][, reSET the PHONE (or CARD) parameter and try to CONNECT again. When you know that you are connected to the host, type in the appropriate RETURNS or whatever to tell the host you wish to log-on. Log-on to the host and set its Kermit running with the appropriate commands. If you want to log off the host system and log back on to it or another host, you will have to get Kermit-][ to reinitialize itself as described at the beginning of this section. A2.6 BREAK command If you are using the Apple Super Serial Card, you may use the BREAK command to send a break signal to the host. The BREAK command will have no effect at all if you do not have the Super Serial Card installed! The break signal may be required to log-on to or disconnect from certain hosts (not the SERDAC UNIVAC!). If you need to send a break to log-on, first initialize Kermit-][ by SETting the appropriate parameters. Then, at the prompt, type in BREAK (cr). This will do an automatic CONNECT, let you dial-up, if applicable, and send the break signal. To complete the log-on to the host, type in the key-ins you would normally need after the break signal. If you need to send a break signal to disconnect a host, type the escape character to get the >u prompt, type BREAK (cr), and answer the u question with a Y (cr). You will be disconnected and then will have the opportunity to reconnect. A2- 7 Kermit-][ will be automatically reinitialized for the host and physical connection you were just using. If you do not wish to reconnect, type the escape character to get the prompt back. Reinitialize Kermit-][ to connect to another host or to do whatever is desired. No matter what kind of equipment you are using, if you need to send a break signal to the SERDAC UNIVAC (to interrupt output and @@X something), it's much better and easier to break by typing CTRL-SHIFT-P while "talking to" the host. A2.7 Returning to Kermit-][ To return to Kermit-][ from terminal operation, simply type the appropriate escape character. The default escape character is the ESCape key. After typing it, you should get the >u prompt. Note: When you are using one of the supported serial cards, the first time you escape back to your Apple, there will be a slight (2-3 second) delay before you get the prompt. A2.8 Transferring files from micro to host After CONNECTing and logging-on to the host: >u@USE K.,KERMIT*KERMIT. (cr) Run Kermit on the host (the Sperry u UNIVAC in these examples. The host >u@K.KERMIT,R MY*FILE. (cr) commands will vary from host to u host). Use your own file name or element name in place of MY*FILE. If you specify none, the target UNIVAC name(s) will be determined by the Apple Kermit SEND command(s). Note that the R option is used to give the UNIVAC Kermit a RECEIVE command. ESC Press the ESCape key to get out of terminal mode and return to Kermit-][. [Back at Apple] >uSEND CHESS (cr) Specify the file to be sent from the default disk. Substitute your own file name for CHESS. If SCROLL is ON, the actual text will scroll A2- 8 by on your screen as it is being sent. You may send a file from any drive by appending ,Dn to the file name; for example, SEND CHESS,D2 to send a file from a drive 2 disk. You can abort the transfer at any time, by typing the escape character several times. When the transfer is complete, you will see: *********************** * TRANSFER COMPLETED * *********************** and Kermit-][ will sound a bell. As stated in Sections 3.7 and A2.14, there are a number of conditions that can interrupt or abort a Kermit transfer, and different ways of handling those kinds of situations. If, for example, you should get an error message, u u, reSET Kermit-]['s TIMEOUT parameter to a higher value, and start the whole transfer over again. At this point, u u u, and the SEND was completed normally, you may SEND other Apple files to the UNIVAC without reCONNECTing to it. The received files on the UNIVAC will have the same names as the ones you specify in the SEND commands you use, so be careful to use simple names legal to the UNIVAC, and make sure that you don't overwrite something on the host! Or, if you want to be conservative:. >uCONNECT (cr) CONNECT to the host again to check that the file (or element) was properly received, to set the host Kermit up to receive/send another file, or to log-off if you are finished. There is no need to re-establish the physical connection (dialing or whatever method was used) or to rerun Kermit-][; all CONNECT commands A2- 9 after the first one put you directly back to the host, as long as you have not reSET any transmission parameters. @EOF (cr) When you return to the UNIVAC after u a transfer, you should ALWAYS type > @EOF (cr) (or just @ (cr)) to terminate UNIVAC's Kermit and get the operating system prompt (>). (You may have to type a few RETURNs to get other hosts' attention so you can terminate or command their Kermits). >....... Tell the host what to do next, and then return to Kermit-][ by typing:. ESC A2.9 Transferring files from host to micro After CONNECTing and logging-on to the host: >@USE K.,KERMIT*KERMIT. (cr) Run Kermit on the host (the Sperry u UNIVAC in these examples. The host >@K.KERMIT,SW MY*FILE. (cr) commands will vary from host to u host). Use your own file name or element name in place of MY*FILE. Note that the S option is used to give the UNIVAC Kermit a SEND command. The W option is used to specify a time delay so that you will have time to return to the Apple and set it up to receive the file. ESC Press the ESCape key to get out of terminal mode and return to Kermit-][. [Back at Apple] >uRECEIVE (cr) Tell Kermit-][ to receive the incoming file and to store it on the default disk. (You can change the default by using a SET DRIVE command (see Section A2.3.14) A2-10 u typing the RECEIVE command. If desired, you may also indicate the drive you want to use to store particular received data by appending ,Dn to the RECEIVE command, e.g., RECEIVE,D2 will have Kermit-][ store the data on the disk in drive 2). If SCROLL is ON, the actual text will scroll by on your screen as it is being received. Note that the file will be put on the default disk with the same name as you specified on the host Kermit SEND. You can abort the transfer at any time, by typing the escape character several times. When the transfer is complete, you will see: ********************** * TRANSFER COMPLETED * ********************** and Kermit-][ will sound a bell. As stated in Sections 3.7 and A2.14, there are a number of conditions that can interrupt or abort a Kermit transfer, and different ways of handling those kinds of situations. If, for example, you should get an error message, u u, reSET Kermit-]['s TIMEOUT parameter to a higher value, and start the whole transfer over again. >uCONNECT (cr) CONNECT to the host again to set the host Kermit up to send/receive another file, or to log-off if you are finished. There is no need to re-establish the physical connection (dialing or whatever method was used) or to rerun Kermit-][; all CONNECT commands after the first one put you directly back to the host, as long as you have not reSET any transmission parameters. A2-11 @EOF (cr) When you return to the UNIVAC after u a transfer, you should ALWAYS type > @EOF (cr) (or just @ (cr)) to terminate UNIVAC's Kermit and get the operating system prompt (>). (You may have to type a few RETURNs to get other hosts' attention so you can terminate or command their Kermits). >....... Tell the host what to do next, and then return to Kermit-][ by typing:. ESC A2.10 Exiting Kermit-][ After logging-off the host computer and terminating your physical connection (e.g., hanging up the phone), get back to Kermit-][ by typing the escape character. When you see the >u prompt, type either EXIT (cr) or QUIT (cr) to end the Kermit-][ session. A2.11 Converting an Applesoft BASIC file to a text file Since Kermit-][ transfers only sequential text files, you must convert Applesoft BASIC programs to text files before transferring them. A utility program called B2T (for BASIC-to-text) is on your Kermit-][ distribution disk specifically for this purpose. You can use B2T on any Applesoft BASIC program, as long as there is no line number 0 in it. To create a text file, load your Applesoft program and type: EXEC B2T (cr). To change the Applesoft program PRIMESl to a text file stored on disk as PRIMES2, for example: uLOAD PRIMESl (cr) uEXEC B2T (cr) u u uRUN (cr) uPRIMES2 (cr) Note that at this writing (7/85) there may be some difficulties encountered in transferring Applesoft BASIC text files to and from the UNIVAC. UNIVAC's UMd-Kermit will accept text lines greater than 132 characters in length, but it "breaks" the lines at character 132. For example, if you send a line of 157 characters, the UNIVAC will make it into two lines- one with 132 characters and one with 25 characters. When you transfer A2-12 the text file back to your Apple, and try to EXEC it back to a BASIC program (see next section), the second part of your original line, now a line of its own, will be taken as a SYNTAX ERROR or, if it happens to begin with a number, as an undesired BASIC statement. We are trying to modify the UNIVAC Kermit so that this problem will not occur, but in the meantime, it would be a good idea not to write new BASIC programs with lines exceeding 132 characters if you plan to transfer them to and from the UNIVAC. If this is not possible, or if you have old programs with many long lines that you need to transfer, contact SERDAC; we have developed several interim Applesoft BASIC utility programs to detect and fix "split" lines. Another thing that you should be aware of when transferring Applesoft BASIC text files to the UNIVAC is that the usual call to the UNIVAC Text Editor (@ED file-or-elt-name) WILL NOT let you look at columns 81-132 (132 characters is the maximum length you can look at). If you have uploaded an Applesoft BASIC text file, with lines 81-132 characters long, and you would like to look at or edit it, MAKE SURE to use the "D" option on the Text Editor call (i.e. @ED,D file-or-elt-name)! A2.12 Converting text file to Applesoft BASIC program This is very simple. Merely EXEC your file and SAVE it. If a file contains BASIC line numbers and statements, EXEC-ing that file causes the text to be read into memory and stored as a BASIC program, as if you had typed it directly into the system itself. You must then SAVE the program with an appropriate name. To change the text file PRIMES2 back to a BASIC program file and store it on disk as PRIMESl:. uEXEC PRIMES2 (cr) u (a series of right brackets will appear) uSAVE PRIMESl (cr) A2.13 Converting Apple binary file to/from text file Although the host will not be able to interpret the contents of a micro binary file under ordinary circumstances, it may be handy to store one on the host disk for future transfer back to an appropriate micro. Unfortunately, as with Applesoft files, there is no direct way to do such a transfer with Kermit-][. The Apple binary file must first be translated into a u file before it may be transferred to the host. The hex-text file must be easily convertible back to binary when it is transferred back to an appropriate micro. This process is relatively straightforward. For the specific purpose of converting Apple II hi-res pictures in memory locations $2000-$3FFF or $4000-$5FFF (or binary files containing those memory ranges), we have included a complete picture un/packer and binary <--> text A2-13 picture file converter on the Kermit-][ distribution disk-- Applesoft programs P/U-GO and P/U, which call Apple binary files PACK/UNPACK, BIN2TXT, and TXT2BIN. If you would like to un/convert other memory ranges (or binary files containing known memory ranges), we have included several Applesoft BASIC and 6502 assembler utility programs on the Kermit-][ distribution disk. Programs BITXT (executed via EXEC EBITXT) and B-T will convert a binary file or memory range to a transferable hex-text file. Programs TXBIN (executed via EXEC ETXBIN) and T-B will unconvert a hex-text file back to binary. Those programs should only be used for memory ranges between $300 and $89FF. A2.14 Kermit-][ transfer error messages As explained in Section 3.7, there are a number of conditions which can interrupt or abort a Kermit transfer. Specific Kermit-][ error messages and associated remedial actions are reviewed below: Micro-to-host transfer While you are SENDing a file to the host (uploading), you may see the following Kermit-][ transfer error messages: u The file you specified to SEND is not on the default drive's disk. The file transfer from the Apple cannot be begun. Check to make sure where the desired file is, and type the correct SEND command when you see the >u prompt. u An error was encountered while trying to read the file that you specified to SEND. The transfer is aborted at the point of error. The received file or element on the host will be incomplete. Make sure that the default drive is ready. Take out the disk and reinsert it; flip the drive door open and closed several times. Then, retype the SEND command when you see the >u prompt. If the error reoccurs, you will have to "repair" the file or submit another copy of it on a different disk. u The file you specified to SEND is on the default disk, but it is u a text file. The file transfer cannot be initiated. Check to see if you have the right disk in the default drive and have spelled the text file name correctly in the SEND command. Wait for the >u prompt and type in the correct SEND command. A2-14 u The host is taking too long to acknowledge data packets sent from Kermit-][. The received file or element on the host will be incomplete. ReSET the Kermit-][ TIMEOUT parameter to a higher value (say 5 or 10 higher than the current value) and restart the transfer on both host and micro. u u The micro <--> host physical connection is excessively noisy. The electrical interference is causing packets to be lost or distorted on the way to and from the host. Whenever the noise level exceeds tolerance, the transfer is automatically aborted. The received file or element on the host will be incomplete. You may know a way to eliminate the noise and proceed with your Kermit session by restarting the transfer on both the host and the micro. If you cannot eliminate the noise, re-establish your physical connection (i.e. hang up, reinitialize Kermit (see Section A2.5), reCONNECT, and redial (if applicable)), log-on, and restart the transfer on both host and micro. u You have chosen to manually abort the transfer by typing the Kermit-][ escape character several times. Any received file or element on the host will be incomplete. When you see the >u prompt, you may type in any legal command. If desired, you may reSEND the same file or SEND another by typing the appropriate SEND command when you see the >u prompt. u When you see this message without any accompanying explanation, there may have been a problem in exchange of Kermit initialization or control packets (Kermit-][ may have an incompatibility with the host Kermit-][), or in getting access to the target host disk file or element (e.g., the desired UNIVAC file is not assigned to your run or is rolled out, or the filename you specified in the SEND is illegal to the UNIVAC). The transfer is aborted, often before data is really sent. Check the status of the target host file or element. Make sure that the name used in the SEND is "translatable" to a legal UNIVAC name. If the name is in doubt, and you don't want to specify a legal target name in the host Kermit call, you may have to RENAME the Apple file before attempting to SEND it again. Alternatively. there may have been a line noise problem during data transfer which scrambled some of the critical packet information (such as sequence number or packet type) so that the A2-15 computers got confused in verifying whether packets were properly sent/received. In either of the cases just mentioned, the transfer should be restarted on both the host and the micro. Host-to-micro transfer While you are RECEIVEing a file from the host (downloading), you may see the following Kermit-][ transfer error messages: u (preceded by error # and line #) The Apple disk in the default drive is write protected, and no received data can be written onto it. Insert another disk, or remove the write protection strip. Restart the transfer on both the host and the micro. u (preceded by error # and line #) An error was encountered while trying to write the received file to the Apple disk. The received micro file will be incomplete. Make sure that the default disk drive is ready. Take out the disk and reinsert it; flip the drive door open and closed several times. Restart the transfer on both the host and the micro. If the error persists, use another Apple II disk. u (preceded by error # and line #) While trying to write the received data to the Apple disk, the disk was filled up. The received micro file will be incomplete. Delete some files from the disk or insert another. Restart the transfer on both the host and the micro. u Kermit-][ is attempting to append a text file to an existing Apple II file which is u a text file. Check to see if the file or element name you specified to be sent by the host already exists on the micro disk. If it does, and the file is not a text file, delete it, rename it, or copy the host file or element to one with a different name before reSENDing it. Restart the transfer on both the host and the micro. u The host is taking too long to acknowledge ACK/NAK packets sent from Kermit-][. The received file on the micro will be incomplete. Reset the Kermit-][ TIMEOUT parameter to a higher value (say 5 or 10 higher than the current value) and restart the transfer on both host and micro. A2-16 u u The micro <--> host physical connection is excessively noisy. The electrical interference is causing packets to be lost or distorted on the way to and from the host. Whenever the noise level exceeds tolerance, the transfer is automatically aborted. The received file on the micro will be incomplete. You may know a way to eliminate the noise and proceed with your Kermit session by restarting the transfer on both the host and the micro. If you cannot eliminate the noise, re-establish your physical connection (i.e. hang up, reinitialize Kermit (see Section A2.5), reCONNECT, and redial (if applicable)), log-on, and restart the transfer on both host and micro. u There are two conditions that can cause this error message. XFirst, Kermit-][ cannot accept logical lines greater than 256 characters in length. If the file that you are trying to transfer to the Apple has such lines, you must figure out some way of shortening them before you can use Kermit-][ to transfer them. Second, the Kermit protocol provides for u u whereby a sending Kermit can condense any string of repeated characters (whose length is greater than four and less than 94) to only three coded characters in a Kermit packet. The coded string is decoded by the receiving Kermit back to the original string. Thus, data with repeated characters may be transferred very efficiently by Kermit. Kermit-][ allows for repeat character processing when you are RECEIVEing data from a host. Unfortunately, because of design deficiencies in the code we received from the University of Wisconsin, this ability is not always adequate. If you are RECEIVEing data with numerous long strings of repeated characters in close proximity to each other within the file, Kermit-][ repeat character processing may fail. If it does, you will receive the u message. If you know that your data has long strings of repeated characters, get the >u prompt and SET REPEAT-PROC OFF. Then, restart the transfer on both the host and the micro. If you aborted due to too many repeat characters, turning off repeat processing should always correct the problem. u You have chosen to manually abort the transfer by typing the Kermit-][ escape character several times. Any received file on the micro will be incomplete. When you see the prompt, you may CONNECT back to the host to restart the transfer, or you may type any other legal command. A2-17 u, There has been a problem in micro <--> host exchange of Kermit-][ initialization packets, or there has been some problem on the host which has interrupted the normal flow of data packets. (Kermit-][ may have an incompatibility with the host Kermit-][), or in getting access to the host disk file or element (e.g., the desired UNIVAC file is not assigned to your run or is rolled out, or the filename you specified in the host SEND is illegal to the UNIVAC). Any received file on the micro will be incomplete. Restart the transfer on both the host and the micro. u When you see this message without any accompanying explanation, there may have been a problem in exchange of Kermit initialization or control packets (Kermit-][ may have an incompatibility with the host Kermit-][), or in getting access to the host disk file or element (e.g., the desired UNIVAC file is not assigned to your run or is rolled out, or the filename you specified in the host SEND is illegal to the UNIVAC). The transfer is aborted, often before data is really sent. Check the status of the host file or element you wanted to SEND. Alternatively, there may have been a line noise problem, during data transfer, which scrambled some of the critical packet information (such as sequence number or packet type) so that the computers got confused in verifying whether packets were properly sent/received. In either of the cases just mentioned, the transfer should be restarted on both the host and the micro. A2.15 Adding to or changing Kermit-][ code We encourage users to add code for presently unsupported Apple II serial or internal modem cards, or to improve on the existing code. The code modules you may need to access are described in the next section. As you can see by listing it, the Applesoft KERMSHELL code contains a large gap between statement numbers 3850 and 6170. This is where you would normally insert BASIC statements to drive a particular serial or modem card. The following information is needed for each additional card. If assigned to the proper variables as described below, the subroutine at statement 6250 will poke this information into KERMITA (KERM = 2065 decimal): Variable Poke to: Function STREG% KERM-l2 Status register address (least significant byte) TRREG% KERM-13 Transmit register address (lsb) RCREG% KERM-l4 Receive register address (lsb) TBIT% KERM-l5 Transmit bit mask RBIT% KERM-l6 Receive bit mask A2-18 Do pokes for parity, local echo, and baud using the variables PARITY$, LOC$, and BAUD. CALL KERM + 17,A$ sends a variable such as A$ out the serial port. Autodialing may be done in this manner. CALL KERM + 20 initializes the communications interface card and re-establishes previously set video parameters. Call this entry point before a call to KERM + 17, and before trying to autodial the Hayes Micromodem II. CALL KERM + 3 sends keyboard typeins out the serial port (checking for the escape character) and displays serial port input on the Apple screen. CALL KERM + 6 fast reads a line of text from the Apple disk file you are SENDing from. CALL KERM + 0 sends out a packet from the Apple and returns the status code of the packet sent back by the host. CALL KERM + 23 re-establishes previously poked video parameters. Call this entry point after any PR#0 statements. If you do successfully make changes, corrections, or additions to Kermit-][ or its documentation, or you have suggestions for same, please contact Robert Holley at SERDAC, (305)-554-2700 (SUNCOM 441-2700) or at @MAIL Mailstop BOB=HOLLEY. We would like to know about your work! A2.16 Files on your Kermit-][ distribution disk The following files should be on your Apple Kermit-][ distribution disk. The stars indicate locked files: * HELLO - Applesoft BASIC boot file for Kermit-][; invokes GOKERM. * GOKERM - Apple II EXEC file to relocate and RUN KERMIT. * GOKERMIL - Apple II EXEC file to relocate and RUN KERMIT, including an illustrated introduction. RUNs program FROGPROG to provide this introduction. * FROGPROG - Applesoft BASIC program to provide an illustrated introduction to Kermit-][. * FROGPIX - Apple II binary hi-res picture file loaded by program FROGPROG. A2-19 KERMIT - Applesoft BASIC part of Kermit-][. This includes the user interface to Kermit-][, and acts as a driver for KERMITA. The KERMIT file you originally receive on the distribution disk is set up to run with the Hayes Micromodem II and with the above defined defaults. If you have a different serial or modem card, you will need to DELETE the original KERMIT file and recreate it as described in the next section. * KERMITA - This is an Apple II binary file loaded by KERMIT. It contains the 6502 machine code that creates and decodes Kermit protocol packets, handles character I/O, sends ACK/NAK packets to the host, implements the video, scroll, and debug features, etc. * KERMITA.S - This is an Apple II text file containing the source 6502 assembler statements for KERMITA, as written for the Apple II Applesoft Tool Kit Assembler. * SET40 - This is an Apple II binary file that contains the special hi-res 40 column graphics character set used by Kermit-][. KERMIT/SETSAVE This is an Apple II text file that contains your saved SET parameters. It is used to initialize Kermit-][ each time it is RUN or each time you do a SET SAVE. * KERMSHELL - This is an Applesoft BASIC file containing all the statements you need to create an appropriate KERMIT program, except for those statements which are needed for a particular serial or modem card. * MIC.T - This is an Apple II EXEC file containing the Applesoft BASIC statements needed for the KERMIT program to control the Hayes Micromodem II. * SUP.T - This is an Apple II EXEC file containing the Applesoft BASIC statements needed for the KERMIT program to control the Apple Super Serial Card. A2-20 * CCS.T - This is an Apple II EXEC file containing the Applesoft BASIC statements needed for the KERMIT program to control the California Computer Systems 7710-D Serial Card. * COM.T - This is an Apple II EXEC file containing the Applesoft BASIC statements needed for the KERMIT program to control the Apple Communications Serial Card. * NOV.T - This is an Apple II EXEC file containing the Applesoft BASIC statements needed for the KERMIT program to control the Novation Apple Cat internal modem (both the 300 baud card and the 1200 baud card, if applicable). * B2T - This is an Apple II EXEC file used to convert Applesoft BASIC files to Kermit-][ transferable text files (see Section A2.11). * EBITXT - Apple II EXEC file used to relocate and RUN Applesoft BASIC program BITXT. * BITXT - Applesoft BASIC program which can be used to convert an Apple binary file or memory range to a transferable hex-text file. * ETXBIN - Apple II EXEC file used to relocate and RUN Applesoft BASIC program TXBIN. * TXBIN - Applesoft BASIC program which can be used to unconvert a hex-text file (originally produced by program BITXT) back to a binary file or memory range. * B-T - This is an Apple II binary file loaded by program BITXT. It contains the 6502 machine code which is needed to convert binary to hex-text. * T-B - This is an Apple II binary file loaded by program TXBIN. It contains the 6502 machine code which is needed to unconvert hex-text back to binary. A2-21 * TEXTTOPRINT - This is a useful Applesoft BASIC utility program you may use to print out the contents of a text file or to scroll them to your screen. * P/U-GO - This is an Applesoft BASIC program which introduces and documents the P/U program described below. When the intro is complete, it automatically RUNs P/U. * P/U - This is an Applesoft BASIC program which may be used to compact Apple II binary "picture files" or hi-res screen memory banks and to convert them to Kermit-][ transferable text files. * PACK/UNPACK - This is an Apple II binary file loaded by P/U. It contains the 6502 machine code which is used to pack/unpack Apple II hi-res pictures into a compressed binary form. * BIN2TXT - This is an Apple II binary file loaded by P/U. It contains the 6502 machine code which is used to convert an Apple II binary file to a hex-text file. * TXT2BIN - This is an Apple II binary file loaded by P/U. It contains the 6502 machine code which is used to convert an Apple II hex-text file back to a binary file. A2.17 Configuring a Kermit-][ working disk Many of the files on your Kermit-][ distribution disk will not be needed for your normal work. We suggest that you make one backup copy of the original distribution disk, and then make a working copy with only the files you really need. That way you will have some extra space with which to store text files to be sent/received. At the minimum, you will need HELLO, GOKERM, an appropriate KERMIT program file for your equipment (see below), an appropriate KERMIT/SETSAVE file, and KERMITA. B2T and TEXTTOPRINT may be very useful and only take up a few tracks. To minimize the size of the Applesoft KERMIT program, it is configured for only u specific serial/modem card. The distribution disk contains a KERMIT program configured to drive the Hayes Micromodem II internal modem. If you are using a Novation Apple Cat internal modem or one of the supported serial cards, you u u be able to use the furnished KERMIT program. You will need to follow the procedure outlined below to A2-22 configure a new KERMIT program: 1) Boot your system with your System Master disk. Remove it and insert the copy of the distribution disk. 2) uDELETE KERMIT (cr) 3) uLOAD KERMSHELL (cr) 4) uEXEC name.T (cr) 5) uLIST (cr) (if desired) 6) uSAVE KERMIT (cr) where "name" in step 4 is either NOV, CCS, COM, or SUP as determined by the equipment you plan to use. EXEC MIC.T (cr) if you need to recreate the KERMIT originally on the distribution disk. Then: 7) BRUN the System Master FID program to copy from the Kermit-][ distribution disk to your working disk, the KERMIT file you just created, HELLO (replace the HELLO on the initialized working disk), GOKERM, KERMITA, and KERMIT/SETSAVE. Also copy to the working disk any of the other files you think would be useful in your ordinary work. 8) Place the working disk in the default drive, and run Kermit-][ by typing in EXEC GOKERM (cr). SET all the parameters you need for your serial/modem card, and the host you plan to contact. Then, do a SET SAVE (cr) to save those default parameters on the working disk. You needn't change anything else on your working disk again, unless you plan to SET SAVE parameters for a different host or an alternative phone number or communications parameter like baud rate. If you want to change serial/modem cards, you will need to reconfigure the Applesoft KERMIT program file as outlined above in Steps 1-6. You will also need to run the new KERMIT-][ and SET SAVE appropriate parameters. A2.18 Modifying the KERMITA program Since page 1 of Apple II hi-res memory is utilized by Kermit-][, and the Applesoft KERMIT program is loaded over page 2 of the hi-res memory and above, there is really not much room left to expand the KERMITA code, but you may want to make small A2-23 changes. Follow the procedure outlined below:. 1) Delete the existing KERMITA file and make sure that binary file SET40 and text file KERMITA.S are available on the disk. 2) Modify KERMITA.S as required, and reassemble using the Applesoft Tool Kit or some similar 6502 assembler. Note the hex code address of the label SET40. Store the object code back into a disk file named KERMITA. 3) BLOAD KERMITA 4) BLOAD SET40,A$xxxx where xxxx is the hex code address saved in Step 1. 5) BSAVE KERMITA,A$801,L$1800 A2.19 Recent Improvements to SERDAC Kermit-][ Appendix A-2 of this manual has been revised to document the 7/85 version of SERDAC Kermit-][ and the associated programs distributed on the 7/85 Kermit-][ distribution disk. Changes to the documentation since the 5/85 Kermit-][ distribution have been noted by vertical lines in the page margins. Specifically, the 7/85 Kermit-][ contains the following corrections/improvements:. (1) Kermit-][ problems with SENDing files with logical line lengths of 128-256 characters have been corrected. Note that, for the present, caution must be exercised when transferring files with logical line lengths greater than 132 characters to/from the UNIVAC (see Section A2.11). (2) Kermit-][ problems with RECEIVEing files with long strings of repeated characters have been corrected. An option (SET REPEAT-PROC OFF) has been provided to disable repeat character processing if it is inadequate to handle specific data transfers. (3) It is now possible to SET SAVE a phone number with an embedded comma pause character. (4) A diagnostic message has been provided to warn you if you are trying to RECEIVE logical lines longer than 256 characters. (5) Screen instructions for auto-dialing when using an external modem and the Apple Communications Card have been corrected. (6) Statements 5449-50 in the Applesoft KERMIT program (see EXEC text file COM.T) have been removed. The Apple A2-24 Communications Card, as originally sold, can only be used with Kermit-][ at 300 baud. If the card has been modified for use at 1200/300 baud, it can only be used with Kermit-][ at 1200 baud. (7) Several redundancies and inconsistencies in Kermit-][ error messages have been eliminated. (8) Diagnostic messages have been added to flag erroneous or unexecutable Kermit-][ DOS commands. (9) Bells have been added to attract your attention to the normal (or abnormal) end of a file transfer, where you might not be watching your screen. (10) You can now toggle the default disk drive with a SET DRIVE command. (11) There is a new screen format for the SHOW/STATUS display. (12) It is now possible to toggle the default drive by appending the drive number to the RECEIVE command (e.g., RECEIVE,D2). (13) It is now possible to specify the Kermit EOL parameter (SET EOL) for transfers with a host machine which does not use the standard carriage return for EOL. (14) There is now an option to invoke Kermit-][ with an illustrated introduction. This requires the presence of files GOKERMIL, FROGPROG, and FROGPIX on the working disk. Associated programs on the 7/85 Kermit-][ distribution disk contain the following corrections/improvements: (1) There are four new programs (BITXT, B-T, TXBIN, T-B) and two new EXEC files (EBITXT and ETXBIN) which will allow you to convert Apple II binary files (or memory ranges), to transferable hex-text files and to unconvert such hex-text files back to binary. (2) A small error has been corrected in the P/U picture utility program. If you happen to answer the "PACK/UNPACK PIX FROM SCREEN 1 OR 2?" question with a non-numeric answer, the question will be repeated. A2-25 //go.sysin dd * if [ `wc -c < manual.txt` != 63514 ]; then made=FALSE echo error transmitting manual.txt -- echo length should be 63514, not `wc -c < manual.txt` else made=TRUE fi if [ $made = TRUE ]; then chmod 644 manual.txt echo -n ' '; ls -ld manual.txt fi ------------ ereh tuc ------------ -- umd5.UUCP <= {seismo!umcp-cs,ihnp4!rlgvax}!cvl!umd5!zben Ben Cranston zben @ umd2.UMD.EDU Kingdom of Merryland Sperrows 1100/92 umd2.BITNET "via HASP with RSCS"