Columbia Kermit/kermit.zip/archives/trs80model1and3.zip/trsmitdoc.txt

Text File | 1984-05-28 | 16KB | 319 lines

TRS-80 KERMIT


Program: Stan Barber, Rice University developed from the CP/M-80 version by
Bill Catchings and others.

Language: Z80 Assembler, compatable with M80 and EDAS from Mysosys

Version: 3.5 (adapted from that version of CP/M 80 Kermit)

Date: March 1984

Documentation: Stan Barber, Rice University

                Summary of TRSDOS and TRSDOS-bases Operating Systems

TRSDOS (The Radio Shack Disk Operating System) has a large library of built
in commands dealing with files, directory maintenance, device I/O, etc.
Programs are also used for some functions on some TRSDOS-bases DOS's. Only
those of major interest will be discussed here.

TRSDOS file specifications are of the form FILESPEC/EXT.PASSWORD:D, where:

FILESPEC        is the filename up to eight characters.
EXT            is the file type, up to three characters.
PASSWORD        is the password for that file.
D            is a numerical drive specification (0-9).

Filenames, file types and passwords may contain letters and numbers, but the
first character in each must be a letter. No special characters or spaces are
allowed. All fields are optional except the filespec. Any field added must be
preceeded by its special delimiter (/ for file type, . for passwords and
: for drive specifications). Upper and lower case characters are equivalent.

Wildcard file-group specifications are supported on some of the TRSDOS-based
DOS's but is not a standard feature. Consult your DOS manual for more specific
information. It should be noted that TRSDOS has no concept of a default drive
when no drive specification is given in the file specification. It will search
for an existing file on all available drives before it will open a new file.
Further, it will not open a file on a disk that is already full, instead it
will generate a disk full error (if all disks in the system are full or write
protected).

TRSDOS commands of interest include:

DIR :D [other options] lists the names of all visible files on the specified
drive. If no drive is specified, some DOS's give the directories of all mounted
drives. Some give the directory of the system drive (drive 0).

FREE gives statistics on disk usage.

KILL file removes the file from the directory and frees the space allocated to
the file for reassignment.

LIST file lists the file on the display.

RENAME oldfile newfile changes the name of oldfile to newfile if newfile is a
unique file name on that disk.

To duplicate files and disks, there are a variety of commands available. Which
one is available will depend on the operating system you are using. A sampling
is given below:

COPY file1 file2 will copy file1 and name the copy file2. If file2 exists, it
will be replaced.

BACKUP :D :E will make a copy of the disk in drive D on the the disk in drive
E.  In some DOS's, this is part of the COPY command (e.g. COPY :D :E or
COPY 0 1).

FORMAT :D will format the disk in drive D. It will ready for any normal read or
write operation following successful completion of this operation. This
operation must be performed before use of a blank disk. Reformatting a
previously formatted disk will cause all previously stored information to be
lost. FORMAT is usually a program but on some DOS's, it is a part of the DOS
command library.



               KERMIT-TRS80 Description

This implementation of the Kermit protocol is compatable with all DOS's
available for the TRS80 Model I or Model III (and the Model 4 running in Model
III mode).  It has been checked out under the following DOS's: TRSDOS 2.3
(Model I), TRSDOS 1.3 (Model III), NEWDOS/80 V 2.0, LDOS 5.1.3, DOS+ 3.5 and
VTOS 3.0 (Model I).

Since Kermit-TRS80 runs on a TRS-80, it is always local. The screen is
contantly updated with the filename and the packet number, whether sending or
receiving.  Kermit-TRS80 will also automatically translate file names to
conform with the Kermit standard when sending and the TRSDOS standard when
receiving. (This does not apply to the GET command.)

If despite the timeout capability, the transmission appears to be stuck (and
you can tell that this has happened if the screen fails to change for a while)
you can hit <ENTER> to have the micro do what it would have done on a timeout,
namely NAK the expected packet to cause to foreign host to send it again (or,
if the micro is sending, to retransmit the last packet).  Micro/Micro or
Micro/IBM-mainframe transfers could require this kind of manual intervention.


File transfers may be interrupted in several ways.
[A reminder: Control characters are generated by holding down the Left-shift
and the down arrow keys while striking the alpha key corresponding to the
control character that you wish to generate.]

Control-C       This will return you to Kermit-TRS80 command level immediately,
        so that you can connect back to the remote  system,  or  take
        any other desired action.

Control-X       When  sending  a  file,  this will terminate the sending of the
                current file with a signal to the KERMIT on the other  side  to
                discard  what  it  got  so  far.  If there are more files to be
                sent, KERMIT-TRS80 will go on to the next one.  When
        receiving a file, KERMIT-TRS80 will send a signal to the remote
        KERMIT to stop sending  this file.  If the remote KERMIT
        understands this signal (not all implementations of KERMIT
        do), it will comply, otherwise the file will keep coming.  In
        any case, the remote KERMIT will go on to the next file in the
        group, if any.

Control-Z       Like  Control-X,  except  if a file group is being transmitted,
                this will stop the transmission of the entire group.  If only a
                single file is being transmitted, it is exactly like Control-X.

<ENTER>s
                If you type <ENTER> repeatedly Kermit-TRS80 will retry the
                current packet up to its retry limit (something like 16  times)
                and  then,  if  no  valid  response  was  received,  return  to
                Kermit-TRS80 command level.


                              KERMIT-TRS80 COMMANDS

KERMIT-TRS80 uses the DECSYSTEM-20 keyword style command language.  Each
keyword may be abbreviated to its minimum unique length.  "?" may be typed to
request a menu of the available options for the current field at any point in a
command.  This must be followed by an <ENTER>. If sufficient characters have
not been typed to identify the current field uniquely, KERMIT-TRS80 will
reprompt and allow you to continue from that point.

CONNECT Establish a "virtual terminal" connection to any host that may be  con-
        nected  to the serial port, i.e. pass all typein to the serial port and
        display all input from the serial port on the screen.  Also, emulate  a
        DEC   VT52   to   allow  cursor  control,  screen  clearing,  etc.,  if
        VT52-EMULATION is ON (see below), in which case  you  should  also  set
        your  terminal type on the remote host to VT52.  The escape character
        defaults to CTRL-underbar (which is generated by <CLEAR> on the
        keyboard).  When you issue the CONNECT command, the micro will print a
    message telling you how to get back.   The escape sequence is
    generally an uncommonly-used control character, like CTRL-underbar or
        CTRL-uparrow, followed by a single letter "command".

        C   Close Connection, return to Kermit-TRS80> command level.
        S   Display Status of connection, but maintain remote connection.
        ?   List available single-character commands.
        0   (zero) Send a null (0) character.
        ^_  (or whatever - a second copy of the escape character) Send the  es-
            cape character itself to the remote host.

SEND filespec
        Send  file specified by filespec to the remote Kermit.  The filespec
        may not contain wildcards.

RECEIVE Receive file(s) from the remote Kermit.  Store  them  under  the  names
        provided in the file headers supplied by the remote host.  If the names
        aren't  legal,  use  as many legal characters from the name as possible
        (see the description of SET FILE-WARNING below).   If  there's  a  con-
        flict,  and FILE-WARNING is ON, warn the user and try to build a unique
        name for the file.

GET filespec
        When Kermit-TRS80 is talking to a Kermit Server on the host, you  may
    include a file wildcard IF the host supports wildcards. The filespec
    must be in a legal form for the HOST system.

LOG filespec
        When CONNECTed to a foreign host as a terminal, log the  terminal  ses-
        sion  to  the  specified  diskette file.  This functionality depends to
        some extent on the remote host's ability to do XON/XOFF  flow  control,
        and  does  not  guarantee a complete transcript (after all, that's what
        the KERMIT protocol is for).  The log file is closed when  the
        connection is closed by typing the escape character followed by the
        single-character command "C".

BYE     When talking to a remote Kermit Server, this  command  shuts  down  the
        server  and  logs it out, and also exits from Kermit-TRS80 to DOS
    command level.

LOGOUT  Like BYE, but leaves you at Kermit-TRS80 command level.

FINISH  Like LOGOUT, but shuts down the remote server without logging  it  out.
        Leaves you at Kermit-TRS80 command level; subsequent CONNECT commands
    will put you back at host system command level.

SET parameter [value]
        Set the specified parameter to the specified value.  Possible settings:

        WARNING ON (or OFF)
                Warn  user  of  filename  conflicts  when  receiving files from
                remote host, and attempt to generate a unique name by modifying
                the given one.  ON by default.

        VT52-EMULATION ON (or OFF)
                When connected as  a  terminal  to  a  foreign  host,  controls
                whether  the  TRS80  emulates  a VT52 or runs in "native mode".
                VT52 emulation is ON by default.

    DEBUGGING ON (or OFF)
        When transmitting or receiving packets, controls whether the
        packets are displayed on the local screen. Debugging is OFF by
        default.

        LOCAL-ECHO ON (or OFF)
                When you CONNECT to a remote host, you must set  LOCAL-ECHO  ON
                if  the  host  is  half  duplex,  OFF  if  full duplex.  OFF by
                default.

        ESCAPE  Change the escape character for virtual  terminal  connections.
                Kermit-TRS80  will  prompt you for the new escape character,
        which you type in locally.

        BAUD    Change  the baud rate of the communications port.  Type SET
        BAUD followed by a question mark, and follow the directions.

        PARITY  Sets  parity  for  outgoing characters to one of the following:
                NONE, SPACE, MARK, EVEN, or ODD.  On input, if parity is  NONE,
                then  the  8th  bit is kept (as data), otherwise it is stripped
                and ignored.  The parity setting applies to both terminal  con-
                nection and file transfer.

        IBM ON (or OFF)
                Allow  the  transfer of files to and from an IBM mainframe com-
                puter.  This makes Kermit-TRS80 wait for the IBM turnaround
        character (XON), ignore parity on input, add appropriate parity
                to  output, and use local echoing during CONNECT.  If you don't
                give this command, IBM mode is OFF.

        FILE-TYPE (ASCII/BINARY/DEFAULT)
                Tells KERMIT-TRS80 how to deal with the file being
                send/received. IT IS IMPORTANT to tell KERMIT if the
                is in ASCII when sending to a non-TRS80 KERMIT. DEFAULT
                is the same as BINARY in this version.

       BLOCK-CHECK-TYPE
                The options are:

                1-CHARACTER-CHECKSUM
                        Normal, default, standard 6-bit checksum.
                2-CHARACTER-CHECKSUM
                        A 12-bit checksum encoded as two characters.
                3-CHARACTER-CRC-CCITT
                        A 16-bit CCITT-format Cyclic Redundancy Check,  encoded
                        as 3 characters.

                The  2  and  3 character options should only be used under con-
                ditions of extreme line noise.  Many implementations of  KERMIT
                only support the single character checksum.

        PORT    Allows  you  to  switch  between different communication ports.
                This command is not available at this time.

        PRINTER ON or OFF.  Turns copying of CONNECT session to printer on  and
                off.  No attempt is made to do buffering or flow control; it is
                assumed printer can keep up. Printer is OFF by default.

DIR     Provides a directory for the specified drive. If no drive is specified,
    the directory display will be as if you had entered the command from
    DOS command level. See the discussion of DIR above.

KILL    This executes the DOS KILL command on the specified file.

                Installation

Kermit-TRS80 is easily installed. Simply download the program KERMAKE/BAS
(KERMAKE.BAS on the mainframe), enter BASIC, load and run the program.
KERMAKE/BAS is in ASCII format and will keep a running checksum while creating
KERMIT/CMD. If there was some error in the downloading process, you will be
notified by the program when it attempts to make KERMIT/CMD. Once this
process is complete, you will have a running version of Kermit-TRS80.

           Building Kermit-TRS80 from the Source.

The Source for Kermit-TRS80 is in seven modules. KERMIT/SRC is the main source
module. It will call the other source files into the assembly as needed. If any
system calls needed to be changed, they are defined here and all labels for
system calls start with an @. This would be useful for assembling a version for
the Model 4 or a version for a TRS-80 work alike that has some hardware
differences (MAX-80, etc.). All serial I/O routines are in this section as
well.

GET/SRC and SEND/SRC contain the code for the RECEIVE (GET) and SEND commands.
XFER/SRC contains the common code used by RECIEVE and SEND. MORE/SRC contains
code for the other commands (with two exceptions) described above. KILLDIR/SRC
contains the code for the KILL and DIR commands.  This code would have to be
modified for use on the Model 4. KERSTR/SRC contains the strings and storage
area.

It should be noted that KERMIT/CMD loads into RAM at 7000H.  This avoids
conflicts with the DOS overlays that may be called by invoking the DIR command.
Assembly at a lower address is possible if other methods are used to call for a
DIR. I chose this method to be compatable with as many DOS's as possible
without writing code specific to each.

        Getting a binary copy of KERMIT-TRS80

If you wish to have a binary copy of KERMIT-TRS80, you can call the SOBBS
TEST MODE at [phone] to download an binary copy with KERMIT or the
Chistensen (XMODEM) protocol. At the "First Name or User Number?" prompt,
enter KERMIT. At the "Last Name?" prompt, enter KERMIT. At the "Password?"
prompt, enter KERMIT (will not echo). Select G at the "Command>" prompt.
Just follow the instructions given following that.

Stan Barber
May 1984

(thanks to Frank da Cruz for the documentation for Kermit and Stan Hanks
for the encouragement.)