Columbia Kermit/kermit.zip/archives/trs80coco.zip/cckermitdoc.txt

Text File | 2011-08-08 | 21KB | 591 lines

1.0. TRS-80* Color Computer Kermit
     Version 1.1, March 1985


Kermit-CoCo is a program that implements the KERMIT file transfer
protocol  for  the TRS-80 Color Computer.  The minimum system re-
quirements are a Color Computer with 16K memory, one disk  drive,
and a 300 baud (Bell 103/113 compatible) modem.  Kermit-CoCo runs
under the Radio Shack disk operating system and uses the built-in
RS-232  port.   It  therefore does not require OS-9, the "deluxe"
RS-232 pack, or any other hardware or software add-ons.  It  uses
the  disk  ROM  for file I/O and is compatible with both versions
1.0 and 1.1 of the Radio Shack ROM.

Kermit-CoCo lets  your  Color  Computer  communicate  with  other
systems  in  three  ways.  First, it is a terminal program.  Your
computer can function as a terminal connected to  a  remote  com-
puter.   Second,  it  permits uploading (sending) and downloading
(receiving) text files to and from a remote computer.  Third,  it
provides  KERMIT  protocol file transfers of both text and binary
files to and from a remote computer running KERMIT.

KERMIT is a protocol designed for reliable file transfer.  It was
developed  at  the  Columbia  University Center for Computing Ac-
tivities in 1981-82  where  Bill  Catchings  and  Frank  da  Cruz
designed the protocol and implemented it for DEC-20 and CP/M com-
puters.  The two computers exchange information in small packets.
The  sending  computer  transmits  a  packet,  then  waits for an
acknowledgement before sending another.  Each packet includes in-
formation  used  to validate the packet contents.  If a packet is
received incorrectly, the receiving system  requests  retransmis-
sion of the packet.

In addition to reliability, an advantage of Kermit over raw  data
transfer is that it permits transfer of binary files.  This means
Kermit can transfer Color  Computer  machine  language  programs,
even over 7-bit connections.

Kermit-CoCo  implements  only  basic  functions  of  the   Kermit
protocol.  It does not provide time out, multiple file transfers,
or server mode communication and the user  interface  is  not  as
sophisticated  as  in  many versions.  It is, however, sufficient
for simple, reliable file transfers.







____________

  TRS-80 is a trademark of Tandy Corp., Fort Worth, Texas


Kermit-CoCo                   - 1 -                         03/85










1.1. Running Kermit-CoCo

Kermit-CoCo consists of two files.  CCKERMIT.BAS contains a short
BASIC  program to configure memory, load, and execute the machine
code file.  CCKERMIT.BIN contains the actual Kermit machine code.
If  you  have  obtained  Kermit-CoCo  in some way other than on a
diskette, see section 1.6, Bootstrapping Kermit-CoCo.

Make sure your modem is connected, place the Kermit-CoCo disk  in
your machine, and type:

        RUN"CCKERMIT"

This runs the BASIC driver program, which loads and executes  the
machine language code.

You can exit  from  Kermit-CoCo,  execute  other  commands,  then
return to Kermit-CoCo with an EXEC command.

Kermit-CoCo initially displays the following summary  of  command
codes and parameter settings.

                 KERMIT-COCO 1.1
            (PREFIX CONTROL OR COMMANDS
             WITH DOWN-ARROW)
              0 EXIT,  ? PRINT MENU
              1 LOCAL ECHO (N)
              2 PARITY     (E)
              3 AUTO LF    (N)
              4 JOURNALIZE (N)
              5 WRITE BUFFER TO FILE
              6 READ FILE INTO BUFFER
              7 UPLOAD BUFFER
              8 ERASE BUFFER
              9 DEF CHAR/LINE DELETE (08,18)
             KERMIT: = SET, < RECEIVE, > SEND
              ()!-# BRACES BAR TILDE DEL

The current settings are shown in parentheses, where Y=yes, N=no,
and  E=even.   The  character  and line delete codes are shown as
hexadecimal values.  If the default settings are correct for  the
system  you  are  calling,  continue  with  your  normal  sign-on
procedure.  First, however, the are a  few  things  you  need  to
know.

1.2. Multi-key Sequences

The Color Computer keyboard has only 53 keys.  It lacks  some  of
the  keys  found on terminals; the most important of these is the
CONTROL key.  Since CONTROL is normally located to  the  left  of
the  letter   A,  Kermit-CoCo  uses the key in this position, the
DOWN-ARROW, to indicate control codes.



03/85                         - 2 -                   Kermit-CoCo










Several other keys not shown on the keyboard  are  documented  in
the  BASIC  manual  that  came with your computer.  These include
using SHIFT-0 as a caps  lock,  SHIFT-DOWN-ARROW  for  [,  SHIFT-
RIGHT-ARROW  for ], SHIFT-CLEAR for \, and SHIFT-UP-ARROW for un-
derscore (underscore prints as a LEFT-ARROW).

1.2.1. ASCII Control Characters

Unlike terminals, on which you press some other key while holding
down  the  control  key,  in Kermit-CoCo you press the DOWN-ARROW
first, release it, then press the key you want it to modify.  For
example, DOWN-ARROW followed by A generates the hexadecimal value
01 which  is  the  ASCII  code  for  control-A.   Throughout  the
remainder  of  this  document,  control  sequences are printed as
"CTL-character"; for example, CTL-A for DOWN-ARROW followed by A.

ASCII control codes (hexadecimal 00 through 1F) are generated  by
the  standard combinations: CTL-@ for 00, CTL-A for 01, CTL-B for
02, ...  CTL-Z for 1A, CTL-[ for 1B, CTL-\ for 1C, CTL-] for  1D,
CTL-^ for 1E, and CTL-_ (SHIFT-UP-ARROW) for 1F.

1.2.2. Other Special Characters

A second use of the DOWN-ARROW prefix is to generate other  ASCII
characters not on the keyboard.  These are:

        `        CTL '  (Prints as inverse @)
        {        CTL (  (Prints as inverse [)
        |        CTL !  (Prints as inverse \)
        }        CTL )  (Prints as inverse ])
        Tilde    CTL -  (Prints as inverse ^)
        Rubout   CTL #  (Prints as
                          inverse LEFT-ARROW)

To help you remember these, they are shown at the bottom  of  the
menu display.

Some terminals have a special key for the ASCII escape code.   It
simply generates CTL-[ with a single key.

Another key on many terminals is LINE-FEED.  Use either CTL-DOWN-
ARROW or CTL-J to generate the ASCII line feed character.  On the
Kermit-CoCo screen, LINE-FEED moves the cursor to  the  beginning
of the next line.

The BREAK key generates a break by  sending  a  long  (about  1/4
second) series of 0 bits.

When CTL-G (bell)  is  received  or  typed  on  the  keyboard  it
generates a tone through the speaker on your monitor.

The LEFT-ARROW key backspaces the cursor  and  transmits  a  user
selectable character deletion code.  SHIFT-LEFT-ARROW transmits a
user selectable line deletion code.

Kermit-CoCo                   - 3 -                         03/85










The CLEAR key clears the screen and moves the cursor to the upper
left corner.  It does not transmit any character.

1.2.3. Kermit-CoCo Commands

A final use of the DOWN-ARROW key is  for  Kermit-CoCo  commands.
These  include modifying parameter settings and beginning special
actions such as KERMIT file transfers.

CTL-? displays the main  menu  with  current  parameter  settings
shown in parentheses.

CTL-0 terminates Kermit-CoCo and returns control to  BASIC.   You
can restart Kermit-CoCo by entering EXEC.

Modify control parameters by pressing the  DOWN-ARROW  key,  then
the  number  of  the  option you want to change.  For example, if
local echo is on (Yes), pressing CTL-1 changes it  to  off  (No).
Pressing CTL-1 again turns local echo back on.

CTL-2 toggles the parity setting between even and none.   Kermit-
CoCo  cannot  communicate  with systems that require other parity
settings.  Although Kermit-CoCo can generate even  parity  output
it  always  ignores  the parity bit of incoming data.  The bit is
not used for either parity checking or 8-bit data values.

CTL-3 toggles local line-feed generation.  When it is set to Yes,
Kermit-CoCo  adds  a line-feed to the display after each carriage
return.  It does not transmit the added line-feed.

After modifying parameters, you can verify the  new  settings  by
pressing CTL-? to display the menu with the new values.

Setting character and line delete codes is similar, but  requires
a  series  of  keystrokes.  These codes, displayed as hexadecimal
values on the menu, are transmitted by the LEFT-ARROW and  SHIFT-
LEFT-ARROW  keys.   To change the settings, press CTL-9, then the
keys for the values to transmit.  For example,

        CTL-9 @ CTL-X

sets the character delete symbol to "@" (hexadecimal 40), and the
line delete symbol to control-X (hexadecimal 18).

You are now ready to use Kermit-CoCo as  a  terminal.   The  fol-
lowing sections describe file transfer.

1.3. KERMIT File Transfers

Kermit file transfers require a copy of Kermit on the remote com-
puter  as  well  as  Kermit-CoCo  on your system.  The remote can
range from another Color Computer to a large mainframe.



03/85                         - 4 -                   Kermit-CoCo










Before beginning a transfer, configure any  necessary  parameters
using the CTL-= command described below.  The default settings of
EOL, SOH, etc. are appropriate for  Kermit-CoCo  and  many  other
systems, but check documentation for the remote Kermit in case it
requires other values.  These must be correct or no communication
can take place.

1.3.1. KERMIT Parameter Settings

Typing DOWN-ARROW followed by an equal sign displays the  current
KERMIT  parameter settings and leaves the cursor under the first.
Pressing ENTER leaves all settings unchanged and returns to  ter-
minal  mode.   Any  other  key  indicates  a  new  value  for the
parameter above the cursor.   To  leave  a  parameter  unchanged,
press  the  space  bar.   Pressing  any  other  key  changes  the
parameter to the ASCII value of that key.  The cursor then  moves
to  the  next  parameter  until  you have responded for each one.
Kermit-CoCo then returns to normal terminal mode.  Note that  for
any  parameter  except  the  first, ENTER is taken as a parameter
setting.

Parameters that can be set are:
    TYPE  COCO File Type: 0=BASIC, 1=TEXT, 2=Machine Code
    MODE  COCO File Mode: 0=Binary, FF=ASCII
    EOL   End-of-line required by the remote system when
          receiving Kermit packets.
    NTRY  Maximum number for transmission attempts for
          each packet.
    SOH   Start of packet character required by the remote
          Kermit.
    DBUG  Debug flag: 0=Off, anything else=On
          When the debug flag is on, each packet sent is
          displayed on lines 9-11 of the screen and each
          packet received is displayed on lines 13-15.

For example, to change the  number  of  retransmission  attempts,
press CTL-=.  Kermit-CoCo displays:

            TYPE MODE  EOL NTRY  SOH DBUG
              00   FF   0D   05   01   00

Press the space bar three times to leave TYPE, MODE, and EOL  un-
changed,  then  type DOWN-ARROW and J to change the retry setting
to 10 (10 is the decimal value of control-J).   Press  the  space
bar  two more times to leave SOH and DBUG unchanged.  The display
now shows:

            TYPE MODE  EOL NTRY  SOH DBUG
              00   FF   0D   05   01   00
              00   FF   0D   0A   01   00

The second line of settings appeared  as  options  were  changed.
Kermit-CoCo is now back in terminal mode.


Kermit-CoCo                   - 5 -                         03/85










To prepare to receive a machine code file, set TYPE to 2  (CTL-B)
and  MODE to 0 (CTL-@).  Type and mode are automatically set when
sending a file.  They must be manually set  for  receiving.   One
reason that the distinction between binary and ASCII files is im-
portant is that the Color Computer indicates end-of-line  with  a
carriage return.  When transmitting ASCII files, Kermit-CoCo adds
a line-feed after each one.  When receiving ASCII files,  Kermit-
CoCo replaces each carriage return followed by a line-feed with a
single return.  It does not insert  or  delete  line  feeds  when
processing  binary  files.   Also,  the operating system requires
certain file types for certain types of processing.   LOADM,  for
example, requires that a file be declared as machine code binary.
Setting the type  and  mode  parameters  permits  Kermit-CoCo  to
create the proper type of file.

In addition to the space bar for leaving  values  unchanged,  and
ASCII  codes  for setting other values, the BREAK key can be used
to set a parameter to hexadecimal FF.

Several Kermit parameter settings are defined internally, with no
provision for change.  These include # for control quoting, & for
8th-bit (binary) quoting, and hexadecimal  0D  (carriage  return)
for end of incoming packet.

1.3.2. Sending A File With KERMIT

Before transmitting a file, the remote KERMIT must  be  ready  to
receive it.  This is done through a RECEIVE command to the remote
KERMIT.  Press CTL-> on your keyboard.  Kermit-CoCo requests  the
name  of  the  file to transmit.  Enter the name, and Kermit-CoCo
begins sending.  As  each packet is sent, the  packet  number  is
shown  as  a  hexadecimal  value.   If  debug mode is active, the
packets are also displayed on the screen.  When the  transfer  is
complete, the message TRANSFER COMPLETE appears on the screen and
the ""bell"  beeps.   If  the  transmission  fails,  the  message
TRANSFER  FAILED appears.  In either case, Kermit-CoCo returns to
terminal mode.

If a "deadlock" occurs-- both KERMITs waiting for a message  from
the  other,  the  packet number will stop changing.  To break the
deadlock and resume transmission, press the  ENTER  key.   Before
doing  this, wait long enough to make sure that a deadlock really
does exist.

1.3.3. Receiving A File With KERMIT

Before attempting to receive a file, make sure that the file mode
and  type parameters are set correctly.  Issue a SEND command for
the remote Kermit, then press CTL-<.  Kermit-CoCo will request  a
name for the incoming file.  Unlike most KERMITs, Kermit-CoCo ig-
nores the name in the incoming transmission, and writes the  data
to the file you specify.



03/85                         - 6 -                   Kermit-CoCo










The display while receiving is similar to that  during  transmis-
sion.   A  hexadecimal  packet number display keeps you posted on
the status of the transmission.  If a deadlock  occurs,  you  can
break  it  by  pressing  ENTER.   Kermit-CoCo  will signal either
TRANSFER COMPLETE or TRANSFER FAILED at the end of the  transfer,
and return to terminal mode.

Some remote Kermits can transmit multiple files.  Do not use this
capability  with  Kermit-CoCo.  It can receive only one file at a
time.

1.4. Journalizing A Session

Kermit-CoCo can use all memory above the high end of the  program
(&H2FFF)  as  a  buffer  to keep a copy of all characters sent or
received.  This facility is used primarily  for  raw  ASCII  file
transfers,  but  can  also be used to journalize (keep a copy of)
your terminal session.

CTL-4 turns on session logging when it is off, turns it off  when
it is on.

CTL-5 prompts for a file name and saves the buffer onto the file.

CTL-8 erases the buffer by resetting the buffer  pointer  to  the
beginning of the buffer.

Note that the buffer cannot be used for both  raw  file  transfer
and session logging at the same time.

1.5. Raw ASCII File Transfer

Kermit transfers are more reliable than raw data transfers.  They
also permit transfer of binary (8-bit) data.  However, since such
transfers require  Kermit  on  both  the  sending  and  receiving
systems, Kermit-CoCo also provides raw ASCII file transfer.

1.5.1. Downloading Files

CTL-R (Hex 12) places the system in download mode.  Actually,  it
turns  on  the  session  logging buffer regardless of its current
state.  It can be entered at the keyboard or transmitted from the
host  system.   Characters  received following it are placed into
the buffer.  This mode ends when CTL-T is received or entered  at
the keyboard or when the buffer is filled.

On a 16K system the buffer holds 4K bytes.  On larger systems  it
hold 20K bytes.

The pointer to the current buffer position can be  reset  by  en-
tering CTL-8 from the keyboard.  This is a local signal only.  It
is not transmitted.   If  multiple  downloads  are  done  without
reseting  the  buffer  pointer,  they  will  be  stored one after
another in the buffer.

Kermit-CoCo                   - 7 -                         03/85










1.5.2. Uploading Files

Entering CTL-7 from  the  keyboard  begins  transmission  of  the
buffer.   As the upload takes place, the text is displayed on the
screen.  To prevent overprinting, you should turn on  local  line
feed (CTL-3), then turn it off after the transfer is complete.

While uploading, all keys except BREAK are  ignored.   The  BREAK
key  can  be  used  to  stop the upload process.  The upload ends
automatically when the portion of the buffer currently in use has
been transmitted.

Before the buffer is transmitted, the  remote  computer  must  be
prepared  to  receive its contents.  To do this, enter the neces-
sary commands (these depend on the remote system) using  terminal
mode before starting the upload.

1.5.3. Reading and Writing the Buffer

CTL-5 writes the contents of the buffer to a  disk  file.   CTL-6
reads  a  file  into the buffer.  For either function Kermit-CoCo
will prompt for a file name.

1.6. Bootstrapping Kermit-CoCo

The easiest way to get Kermit-CoCo is on  a  diskette.   However,
Kermit  is also distributed in other ways which permit ASCII-only
transfer.  To support such transfer  mechanisms,  Kermit-CoCo  is
available  in  Motorola  S-record format, along with a program to
convert S-records to a binary file.   It  is  also  available  in
ASCII source format for input to the EDTASM+ assembler.

1.6.1.  Using the S-record File

To convert the S-record code to  binary,  you  need  to  transfer
files  "CCEXBIN.BAS" and "CCKERMIT.S" to your diskette.  Running
"CCEXBIN" generates file "CCKERMIT.BIN", the executable  version
of Kermit-CoCo.  Each S-record contains checksum information.  If
you did not receive the S-record  file  properly,  CCEXBIN  will
stop  with  an  error message.  Transfer a new copy of CCKERM.S
and try again.

After you have CCKERMIT.BIN, create CCKERMIT.BAS  with  the  fol-
lowing program:

        10 PCLEAR 1:  CLEAR 200,&H1FFF
        20 LOADM"CCKERMIT":  EXEC

You are now ready to run Kermit-CoCo.






03/85                         - 8 -                   Kermit-CoCo










1.6.2.  Assembling the Kermit-CoCo Source

The  source  for  Kermit-CoCo  is  in  two  parts.   The   first,
COCOTERM.ASM,  contains  all  of  the  terminal functions and raw
ASCII file upload and download.  The second,  COCOPROT.ASM,  con-
tains the Kermit protocol source.

The source files were prepared  and  assembled  using  the  Radio
Shack  EDTASM+  ROM  pack  assembler,  modified for disk I/O.  It
should be usable as is with the standard  disk-based  version  of
EDTASM+.   For  other  assemblers minor changes may be necessary.
Comments at the beginning of  each  file  describe  assembly  and
loading.

No linker program is necessary to combine the two  modules.   As-
semble  the files to COCOTERM.BIN and COCOPROT.BIN, respectively.
Load COCOTERM.BIN then load COCOPROT.BIN and SAVEM the code  from
address  &H2000  through the end of COCOPROT.BIN.  This is &H2EFE
as distributed, but may vary with different versions of  the  as-
sembler and with user modifications.

Create CCKERMIT.BAS as described above.

ORG pseudo-ops enable the separately assembled  modules  to  com-
municate;  however,  these  require  some care when modifying the
code.   Note  that  COCOPROT  code  begins  loading  at   &H2800.
Modifications  to  COCOTERM must not make the address of ZZTOP go
beyond &H27FF.  Such modifications would require changing the ORG
statement ahead of KERMR in COCOTERM and the ORG statement at the
beginning of COCOPROT.  Increasing the size of COCOPROT  so  that
address ZZZTOP is greater than &H2FFF would required changing the
EQU statement for TOP in COCOTERM to place the origin of the  raw
data buffer beyond the end of the Kermit packet buffers.






















Kermit-CoCo                   - 9 -                         03/85