@part(APPLE,root="kuser") @chapter(Apple II Kermit) @Index @case(device,file="@*--------@* This document is formatted as an ordinary, plain text ASCII disk file, from SCRIBE text formatter source. Typeset copies are available from Columbia University.@*--------@*") @begin Authors:@\Antonino N. J. Mione (Stevens Institute of Technology),@* Peter Trei (Columbia University),@* Ted Medin (NOSC),@* Bob Holley (SERDAC) Version:@\3.86 Date:@\1989 Sept @end @i @begin @tabclear()@tabset(3.5inches,4.0inches) Local operation:@\Yes Remote operation:@\Yes Transfers text files:@\Yes Transfers binary files:@\Yes Wildcard send:@\Yes @q<^X/^Y> interruption(Q):@\Yes Filename collision avoidance:@\Yes Can time out:@\Yes 8th-bit prefixing:@\Yes Repeat count prefixing:@\No Alternate block checks:@\No Terminal emulation:@\Yes (VT52, VT100) Communication settings:@\Yes Transmit BREAK:@\Yes IBM communication:@\Yes Transaction logging:@\No Session logging (raw download):@\Yes Raw upload:@\No Act as server:@\Yes Talk to server:@\Yes Advanced commands for servers:@\Yes Long packets:@\Yes Sliding windows:@\No Local file management:@\Yes Handle file attributes:@\No Command/init files:@\Yes Printer control:@\Yes @end Kermit-65 is a program that implements the Kermit file transfer protocol for the Motorola 6502 processor family (hence the name, Kermit-65) on the Apple II microcomputer system. It is written in 6502 assembly language and should run on any Apple II or compatible running DOS 3.3 or PRODOS. This section will describe the things you should know about the file system in order to make effective use of Kermit, and then it will describe the special features of the Kermit-65 program. @Section There are several different Apple II's which can run Kermit-65. Kermit will have no problems running on an Apple II, II+, //e, //c or //gs system. Of the different communication devices available for the Apple II, Kermit-65 supports the ones shown in Table @ref<-k65cd>. @begin @bar() @blankspace(1) @begin AE Serial Pro (super serial driver - sw 1 & 3 open 2 & 4 closed) AIO II (Uses the Apple Com Card driver??? - untested) ALS dispatcher (Uses the Apple Com Card driver) Apple Cat Serial Card Apple Com Serial Card ASIO (Uses the Apple Com Card driver??? - untested) Apple Super Serial Card & //c Serial Port Apple //gs Serial Port CCS 7710 Serial Card CCS 7711 (Uses the Apple Com Card driver??? - untested) D.C. Hayes Micromodem. Microtek sv-622 Card Prometheus Versacard (Uses the Apple Com Card driver) SSM AIO (Uses the Apple Com Card driver??? - untested) @end @caption(Apple II Communication Cards Supported by Kermit-65) @tag(-k65cd) @bar() @end(table) It is possible that other cards may have operational characteristics very similar or identical to one of the devices above. If this is the case, it may work using one of the currently available device drivers. The user may want to try each of the above options to see if any of them work. Kermit-65 must be told in which slot the card resides. This may be done with the 'SET' command (documented below). @section @index Items of importance which will be discussed in this section include filenames and file characteristics. @subh @index Filenames under Apple DOS may contain almost any ASCII character (including space). It is not recommended that special characters, (i.e. control characters or spaces) be used in a filename to be transferred by Kermit-65 since they may cause problems when parsing the filename. Filenames may be up to 40 characters in length. @subh All files in Apple DOS have a file type associated with them which is contained in the directory entry for the file but is not part of the filename itself. There are four types of files in DOS 3.3. They are: @begin APPLESOFT BASIC INTEGER BASIC BINARY TEXT @end All file types have their data stored in eight-bit bytes although not all of them need the eighth bit. The two file types containing basic programs required the eighth bit due to the nature of the data being stored. BINARY files are images of memory copied into a file. Often, these are machine code programs. These files require all eight bits. TEXT files normally contain only printable or carriage control characters. They are stored in the form of seven-bit ASCII characters but the eighth bit should always be set since Apples manipulate all text internally as 'Negative ASCII'. When transmitting non-text files the user must insure that both Kermits are handling eight-bit data so that no information is lost. If an eight-bit data path is not available (i.e. the remote Kermit needs to do parity checking with the eighth bit), then eight-bit quoting should be used. Of course, BINARY files as well as Apple BASIC files will not have much meaning on a different system. If the user desires to edit a BASIC file on a mainframe, for instance, s/he must convert it to a TEXT file before sending it over. After receiving the file back on the Apple, the user may convert it back to BASIC once again. The reason BASIC files would be meaningless to a different machine is that the Apple stores BASIC keywords as single character tokens to save space and processing time. To convert a BASIC program to and from a TEXT file, consult the Apple DOS 3.3 Manual. File information can be obtained by issuing the CATALOG command. For example: @begin ]CATALOG DISK VOLUME 010 *A 002 HELLO B 078 KERMIT A 002 READER T 005 TESTFILE ] @end When Kermit-65 is receiving a file, the file it creates on diskette will be of the type indicated by the FILE-TYPE parameter. The file will always be left in an unlocked state after it is closed by Kermit-65. When sending a file, Kermit-65 will use the FILE-TYPE parameter to determine how to detect an End-of-file condition. Thus, it is important to have this set properly in all cases. @subh @index When using a large system for archiving purposes, there is no reason to convert Apple Basic programs into text files before sending them if there is no need to edit them on the mainframe. The FILE-TYPE parameter must always be set correctly when sending and receiving files. The procedure for archiving files is: @begin Run Kermit on remote system. @q (@i@q< APPLESOFT >@i@q< ...>) on Kermit-65. Send the files. @end @section @index The PRODOS system is essentially the same as the DOS system with the exception that performance has been improved, hardware usage has been expanded and file names have different syntax. File names are the major importance to the Kermit system. File names have the following syntax: @example where "volname" is the volume name where the file is located. Subdirectory(n) is a subdirectory on the volume and may be omitted. Filenames are much more restrictive than DOS filenames. PRODOS filenames are limited to 15 characters with no embedded spaces and few special characters, and must begin with an alphabetic character. /volname/sub ... may be omited from the filename by use of the SET PREFIX command. Binary file transfer using PRODOS has its dangers when creating new files. PRODOS keeps the file's size and starting location in the directory which is of course not transferred. Therefore a new binary file will have its starting location 0 which can cause some interesting problems if you try and BRUN the file. Basic files all start at $801 (it says here) so Kermit creates new basic files with a starting address of $801. @section Prior to using Kermit-65 for transferring files, the modem interface must be set to handle data in a certain manner. First, the data format should be 8 data bits and 1 stop bit. Second, the card should be set to no parity. The baud rate (if adjustable) must be set to whatever rate the modem can handle. For the D.C. Hayes Micromodem, these parameters are set correctly by default, so very little has to be done. For the Apple Super Serial Card these are set from within Kermit-65 except the interrupt switch (sw6-2) which must be set for interrupts on. For the Microtek SV-622, all applicable parameters are set by Kermit-65. Some mainframes may need parity checking (i.e. most IBM machines). In this case some parity setting (other than none) will usually work. When talking with such mainframes, binary and basic files on the Apple cannot be transferred unless Eighth-bit-quoting is acceptable to the host. If you have the parameters set correctly then the "CONNECT" command will start Kermit talking out the communication port. File transfer is very dependent upon parity. Make sure the host and local parity are the same. Following are a couple of site's method for file transfer. We have an IBM 3033 and 4381 and use both 3705/3725 and 7171 or Series/1 front ends. The differences in front ends as far as any microcomputer Kermit is concerned duplex (local-echo on for the 3705, local-echo off for the 7171 or Series/1), parity (the two front ends might use different parity, e.g. Mark for the 3705 and Even for the 7171), and flow control (None for the 3705, XON/XOFF for the 7171). In Kermit-65, IBM mainframe users need to set the following parameters: @begin BAUD@\Whatever is supported. PARITY@\EVEN, ODD, or MARK, whatever your front end requires. FLOW@\XON for the 7171, NONE for the 3705. FLOW DELAY@\00 LOCAL-ECHO@\OFF for 7171, ON for 3705 @end In Kermit-65, SERDAC VAX 8800 users need to set the following parameters: @begin BAUD SERDAC Dial-up & 300, 1200, or 2400 baud FIRN Dialup: (the highest your modem and the dial-up connection will support) Ethernet Hardwire: 300, 1200, 2400, or 4800 baud. PARITY NONE FLOW XON FLOW DELAY 00 (higher for printers, logging, or "slow" Apples) LOCAL-ECHO OFF NOTE: If you want to do a binary file transfer (Apple binary or BASIC files) via a FIRN Network connection to the SERDAC VAX 8800, you must SET PARITY SPACE before the transfer is initiated; that will insure that eight-bit quoting is used. If you dial directly into the VAX 8800, SET PARITY NONE; eight-bit quoting (which is less efficient) is not required. @end @subh Kermit-65 reads file @q from the default drive when started. The lines of this file are executed one at a time starting at the beginning. This file should be an ASCII text file and contain commands to set up Kermit's parameters as desired. It will also execute Kermit's other commands. However, any command which reads a file (like MODEM) or leaves local mode (like CONNECT) will terminate reading of this file and continue with the command specified. Use your favorite editor to produce this file. Here's a sample: @begin set display 80 3 set keyboard 2e set baud 4800 modem @end Kermit-65's prompt is "@q(Kermit-65>)". To run Kermit-65 and issue commands to it, type "@q". Example: @begin ]@ux NOSC/STEVENS/CU - APPLE ][ KERMIT-65 - VER 3.86 Kermit-65>@ux @ @ @ @ @i<(file is sent...)> Kermit-65>@ux @ @ @ @ @i<(performance statistics are printed...)> Kermit-65>@ux[@i<(other commands...)>] . . . Kermit-65>@ux[exit] ] @end @index Like many Kermit programs, Kermit-65 uses a DEC-20 style command parser. During interactive operation, you may use the ?-prompting help feature ("?") and recognition (ESC) features while typing commands. A question mark typed at any point in a command displays the options available at that point; typing an ESC character causes the current keyword to be completed (or default value to be supplied). If you have not typed sufficient characters to uniquely specify the keyword (or if there is no default value) then a beep will be sounded and you may continue typing. Keywords may be abbreviated to any prefix that is unique. @subh Kermit-65 is normally run in local mode. It may be run as a remote Kermit as well although there is no advantage to doing things that way. Kermit-65 supports User-mode commands for talking to a Server, and it does support a limited server mode. @section @subsection(The CATALOG Command) @index(CATALOG Command) Syntax: @q Typing CATALOG produces a catalog (directory) listing of your default drive. @subsection @index Syntax: @q Establish a terminal connection to the remote system using all the current SET parameters for terminal type, speed, parity, etc. Get back to Kermit-65 by typing the escape character followed by the letter C. The escape character is Control-@q<@@> by default. When you type the escape character, several single-character commands are possible. These are shown in Table @ref(-k65esc). @begin
@bar() @blankspace(1) @begin @Begin(Description,leftmargin +8,indent -6, spread 0) @q@\List all the possible single-character arguments. @q@\send a Break signal. @q@\Command mode (returning to kermit-65). @q@\Drop the phone line to the remote and return to Kermit-65. @q@\Erase the screen (useful for clearing garbage on screen). @q@\toggle Keypad application-mode on/off. @q@\execute the Modem command. @q@\execute the Quit command. @q

@\toggle the Printer on/off. @q@\pRint the screen, >= //e required @q@\show Status of the connection. @q@\sWap the del and backspace key. @q<0>@\send a null (ASCII 0). @q<^@@>@\(or whatever the Connect-Escape character is): send the Connect-Escape character itself. @End(Description) @end @caption(Kermit-65 Single-Character CONNECT Escape Commands) @tag(-k65esc) @bar() @end(table) You can use the SET ESCAPE command to define a different escape character. When CONNECTed, Kermit-65 will be passing characters entered on the keyboard to the remote system, and passing characters from the remote system to the Apple screen. Incoming characters are interpreted according the selected terminal type (see SET TERMINAL). @index On an Apple II+ with an incomplete keyboard, special characters can be typed by prefixing regular characters with a right-arrow. On uppercase-only screens, uppercase characters are shown in inverse and lowercase characters are displayed as normal uppercase characters. Here are the rules for using the special 2/2+ input, to get all printable ASCII characters, and how they appear on the screen. Special meanings are applied in various contexts to certain characters. The left and right arrow keys do special things, and sometimes the escape key does as well. For letters, the keyboard is always in either default UPPERCASE mode or default lowercase mode. When in UPPERCASE, all letters typed are sent out as uppercase. In lowercase, all letters are sent as lowercase. To reverse the case for the next character only, hit the right-arrow ("prefix") key. To switch the default case, hit the prefix-key twice in a row. For funny characters, the prefix key is also used to get the unusual punctuation characters which are not on the Apple keyboard. Table @ref<-k65keys> shows the Apple II/II+ keyboard escapes; the letter "p" represents the prefix character. @begin

@bar() @blankspace(1) @begin @tabclear()@tabset(3inch,4inch) @ux@\@ux@\@ux Left Square Bracket@\ p@q<(>@\@q< [> Right Square Bracket@\ p@q<)>@\@q< ]> Left Curly Bracket@\ p@q(<)@\@q< {> Right Curly Bracket@\ p@q(>)@\@q< }> Underline@\ p@q<->@\@q< _> Backslash@\ p@q@\@q< \> Tilde (wiggle)@\ p@q(^)@\@q< ~> Vertical Line@\ p@q<.>@\@q< |> @end @caption(Apple II/II+ Keyboard Escapes) @tag(-k65keys) @bar() @end(table) The left-arrow key sends a rubout (ASCII 127). With left-arrow and right arrow doing special things, it's a little hard to enter their characters (@q<^H> and @q<^U> respectively). There is therefore an escape from prefix mode sequence. If you type prefix-ESC, the next character is sent without any interpretation. If you have the capability for upper/lower case, etc, then use the 'SET KEYBOARD' and 'SET DISPLAY' commands to specify complete keyboards. While in connect mode if you have a //e or better with 80 column display, the cursor will blink. The rate of blink is tied to the "SET TIMING" constant. @index @subsection(The DELETE Command) @index Syntax: @q@i Typing DELETE causes the file specified to be deleted. @subsection @index(EXIT Command) Syntax: @q@i@q< QUIT> Exit from Kermit-65. When using dos 3.3 you can probably restart the program, provided you haven't run anything else, by typing 'CALL 4096'. @subsection(The GET Command) @index(GET Command) Syntax: @q@i[,@i] The GET command requests a remote Kermit server to send the file or file group specified by @i. This command can be used with a Kermit server on the other end. The remote filespec is any string that can be a legal file specification for the remote system; it is not parsed or validated locally. So if the remote Kermit supports wildcards you can specify them in the @i. Local-filespec is optional and is the file name to be used locally. If the remote Kermit is not capable of server functions, then you will probably get an error message back from it like "Illegal packet type". In this case, you must connect to the other Kermit, give a SEND command, escape back, and give a RECEIVE command. Currently, a packet can be retransmitted manually by typing anything on the keyboard. If a 'Q' is typed, the entire transmission will be cancelled. @index @subsection(The HELP Command) @index(HELP Command) Syntax: @q Typing HELP alone prints a brief summary of the Kermit-65 commands. @subsection(The LOCK Command) @index(LOCK Command) Syntax: @q@i LOCK will file lock the given filespec on the default drive. @subsection @index Syntax: @q@i When connected to a remote site, log the remote session's output to the specified file. The file type and file warning protocols are observed. This command is dependent upon the flow control (XON/XOFF) working. Without flow control there is little possibility of getting a correct copy of the terminal session. The logging begins when you connect to the remote and is terminated when you escape back to the local Kermit with the ESCAPE character followed by the "C" command. @subsection(The MODEM Command) @index(MODEM Command) Syntax: @i @index @index @index @index This command is designed for the hayes smart modem. Typing MODEM causes the file @q in the default drive/path to be used as a menu. You will be able to select any line in the file to be sent to the modem. Sorry, you can't back up to a previous menu, you will have to Quit and execute MODEM again. A "CONNECT" response from the smart modem will cause Kermit to leave the modem command and execute the CONNECT command. The Hayes smart modem must reply with text status responses (not numbers). One command per line with comments allowed after the first space (blank). Use your favorite editor to produce this ASCII text file. Since the attention Hayes command (AT) requires a delay the @qq<&> character becomes the time delay for Kermit. Each @qq<&> causes a delay of one second on a 6502 chip. If you have a //gs or an accelerator board you may have to use the SET TIMING command to produce a one second delay. If you really need to send the "&" character to the modem then the "\" is the escape character. Put a "\" before any character and that character will be sent as is. Of course two "\"'s will produce one "\". Normally Kermit will wait for 27 seconds (again on a 6502 chip) for the modem to respond, but any character typed on the keyboard will terminate this wait. You may hear the busy signal and there is no sense waiting any longer, so hit (ouch!-not so hard) any key on the keyboard. Following is an example of the @q file: @begin +++&&ATH @i(Get the Hayes Smartmodem's attention and then hang up.) ATDP1234567 @i(Call your local BBS with pulse dialing.) ATDT8901234 @i(Call your work dialup phone with touch tone dialing.) @end @subsection @index Syntax: @q@i@q<]> The RECEIVE command tells Kermit-65 to receive a file or file group from the other system. If only one file is being received, you may include the optional filespec as the name to store the incoming file under; otherwise, the name is taken from the incoming file header. If the name in the header is not a legal filename, Kermit-65 will attempt to change it into something legal. If FILE-WARNING is on and an incoming file has a name identical to a file already existing on the diskette, Kermit-65 will issue a warning to the user and attempt to modify the filename to make it unique. Currently, a packet can be retransmitted manually by typing anything on the keyboard. If a 'Q' is typed, the entire transmission will be aborted. Filespec is required when xmodem protocol is used. @index @subsection(The REMOTE Command) @index(REMOTE Command) Syntax: @q@i
@begin @u
1003 byte main This is the baud rate index as follows: 3 - 110 4 - 135.4 5 - 150 6 - 300 7 - 600 8 - 1200 9 - 1800 10 - 2400 11 - 3600 12 - 4800 13 - 7200 14 - 9600 15 - 19200 eg:if index is 6 then line should be 300 baud 1004 byte unused 1005 word driver Address of a null terminated string. address should point to a capitalized string of the drivers id 1007 byte main Com slot in the form $n0 where n is slot #. 1008 byte main Force initialization flag when 0. init routine should always initialize when this flag is 0 & then set flag non-zero. 1009 word main Address of the end of Kermit main routine. 100b byte main Flow control is on when high bit is set. 100c word driver Address of the end of the com driver. 1020 3 bytes driver Jump to initialization routine. 1023 3 bytes driver Jump to command routine. A reg has command 0 - hang up the line $0b - set baud rate $0c - set break on the line $91 - do xon on the line $93 - do xoff on the line routine returns false (P reg zero flag) if unable 1026 3 bytes driver Jump to check for input from the line. routine returns false (P reg zero flag) if no character on line 1029 3 bytes driver Jump to get input character from line. routine returns character in A reg 102c 3 bytes driver Jump to put character in A reg on line. 102f 3 bytes driver Jump to reset com driver. 1040 3 bytes main Jump to Apple ROM wait rtn. microsecs delay =1/2(26+27A+5A*A) where A is the accumulator 1043 3 bytes main Jump to routine to print null-terminated string. X reg contains least significant byte of address Y reg contains most significant byte of address routine does not issue a carriage return. 1046 3 bytes main Jump to routine to read the keyboard. A reg contains the character read 1049 3 bytes main Jump to routine to print carriage rtn & line feed. 104f 3 bytes main Jump to routine to set characters parity. A reg contains the character before and after. @end @caption(Communications card vector area) @end(table) @begin
@bar() @blankspace(1) @begin @tabclear()@tabset(12) @\List of most of the prodos file types. @ux @ux @ux @ux @q<$00 > typeless @q<$01 > BAD both BAD blocks file @q<$02 > PCD SOS Pascal CoDe file @q<$03 > PTX SOS Pascal TeXt file @q<$04 > TXT both ASCII text file @q<$05 > PDA SOS Pascal DAta file @q<$06 > BIN both BINary file @q<$07 > CHR SOS CHaRacter font file @q<$08 > PIC both PICture file @q<$09 > BA3 SOS Business BASIC (SOS) program file @q<$0A > DA3 SOS Business BASIC (SOS) data file @q<$0B > WPD SOS Word Processor Document @q<$0C > SOS SOS system file @q<$0D > SOS SOS reserved file type @q<$0E > SOS SOS reserved file type @q<$0F > DIR Both subDIRectory file @q<$10 > RPD SOS RPS data file @q<$11 > RPI SOS RPS index file @q<$12 > SOS Applefile diskcard file @q<$13 > SOS Applefile model file @q<$14 > SOS Applefile report format file @q<$15 > SOS Screen library file @q<$16 > SOS SOS reserved file type @q<$17 > SOS SOS reserved file type @q<$18 > SOS SOS reserved file type @q<$19 > ADB ProDOS AppleWorks Database file @q<$1A > AWP ProDOS AppleWorks WordProcessing file @q<$1B > ASP ProDOS AppleWorks Spreadsheet file @q<$1C-$5F> Reserved @q<$60-$6F> ProDOS PC Transporter (Applied Engineering) @q< $60> PRE ProDOS ProDOS preboot driver @q< $61-$6A> ProDOS Reserved @q< $6B> NIO ProDOS PC Transporter BIOS and drivers @q< $6C> ProDOS Reserved @q< $6D> DVR ProDOS PC Transporter device drivers @q< $6E> ProDOS Reserved @q< $6F> HDV ProDOS MSDOS HardDisk Volume @q<$70-$9F> Reserved @q<$A0 > WPF ProDOS WordPerfect document file @q<$A1 > MAC ProDOS Macrofile @q<$A2 > HLP ProDOS Help File @q<$A3 > DAT ProDOS Data File @q<$A4 > Reserved @q<$A5 > LEX ProDOS Spelling dictionary @q<$A6-$AB> Reserved @end @caption(PRODOS file types, part 1) @tag(-ftother) @bar() @end(table) @begin
@bar() @blankspace(1) @begin @tabclear()@tabset(12) @ux @ux @ux @ux @q<$AC > ARC ProDOS General Purpose Archive file @q<$AD-$AF> Reserved @q<$B0 > SRC ProDOS ORCA/M & APW source file @q<$B1 > OBJ ProDOS ORCA/M & APW object file @q<$B2 > LIB ProDOS ORCA/M & APW library file @q<$B3 > S16 ProDOS ProDOS16 system file @q<$B4 > RTL ProDOS ProDOS16 runtime library @q<$B5 > EXE ProDOS APW shell command file @q<$B6 > STR ProDOS ProDOS16 startup init file @q<$B7 > TSF ProDOS ProDOS16 temporary init file @q<$B8 > NDA ProDOS ProDOS16 new desk accessory @q<$B9 > CDA ProDOS ProDOS16 classic desk accessory @q<$BA > TOL ProDOS ProDOS16 toolset file @q<$BB > DRV ProDOS ProDOS16 driver file @q<$BC-$BE> Reserved for ProDOS16 load file @q<$BF > DOC ProDOS document file @q<$C0 > PNT ProDOS //gs paint document @q<$C1 > SCR ProDOS //gs screen file @q<$C2-$C7> Reserved @q<$C8 > FNT ProDOS Printer font file @q<$C9 > ProDOS finder files @q<$CA > ProDOS finder icons @q<$CB-$DF> Reserved @q<$E0 > LBR ProDOS Apple archive library file @q<$E1 > Unknown (unlisted) @q<$E2 > ATI ProDOS Appletalk init file @q<$E3-$EE> Reserved @q<$EF > PAS ProDOS ProDOS Pascal file @q<$F0 > CMD ProDOS added command file @q<$F1-$F8> ProDOS User defined filetypes (popular ones include:) @q< $F1> OVL ProDOS Overlay file @q< $F2> DBF ProDOS Database file @q< $F3> PAD ProDOS MouseWrite file @q< $F4> MCR ProDOS AE Pro macro file @q< $F5> ECP ProDOS ECP batch file @q< $F6> DSC ProDOS description file @q< $F7> TMP ProDOS temporary work file @q< $F8> RSX ProDOS linkable object module @q<$F9 > IMG ProDOS ProDOS image file @q<$FA > INT ProDOS Integer BASIC program @q<$FB > IVR ProDOS Integer BASIC variables file @q<$FC > BAS ProDOS AppleSoft BASIC program @q<$FD > VAR ProDOS AppleSoft BASIC variables file @q<$FE > REL ProDOS ProDOS EDASM relocatable object module file @q<$FF > SYS ProDOS ProDOS8 system file @end @caption(PRODOS file types, part 2) @tag(-ft2) @bar() @end(table)