OS-9/68000 Kermit Installation Manual:

Program by:    Roberto Bagnara, University of Bologna, Italy
               Steve Williams, University of Texas at Austin, USA
Language:      68000 Assembler
Documentation: Roberto Bagnara -- Kermit68K User's Manual
               Steve Williams  -- Kermit68K/OS9 Installation Manual
Version:       1.0.00
Date:          July, 1987

Introduction:

OS-9/68000 Kermit (hereafter to be known as Kermit68K/OS9) is an implementation
of Kermit68K for microcomputer systems using the OS-9/68000 operating system
from Microware.  Kermit68K is patterned after UNIX C-Kermit, however it is
written completely in Motorola 68000 assembly language to allow easy
portability to 68000 based systems without C compilers.

Kermit68K/OS9 was written to fulfill a need for reliable file transfer between
the OS-9 operating system running on an Atari 520ST and several other systems
in a laboratory environment.  While there is a Kermit implementation currently
available for OS-9 systems, it is lacking in functionality.  Also, since I do
not have access to the Microware C compiler, I needed a version of Kermit
written in the native assembly language of the 68000.

The bulk of the program was written between May 1986 and June 1987 by Roberto
Bagnara of the Physics Department at the University of Bologna, Italy.  He is
responsible for the overall user-interface routines, as well as the Kermit
protocol routines.  Kermit68K is written in a modular fashion quite similar to
the UNIX C-Kermit after which it is patterned, to ease portability to various
operating systems running on 68000 based microcomputers.  The OS-9 system
specific modifications were performed by Steve Williams of the Electrical and
Computer Engineering Department at the University of Texas at Austin.

This document discusses only the differences between generic Kermit68K and
Kermit68K/OS9, as well as installation procedure for Kermit68K/OS9. The
complete users guide for Kermit68K (and Kermit68K/OS9) is available as
K6GMAN.DOC.


Kermit68K/OS9 Capabilities At A Glance:

  Local operation:                   Yes
  Remote operation:                  Yes
  Login scripts:                     No
  Transfer text files:               Yes
  Transfer binary files:             Yes
  Wildcard send:                     Yes
  File transfer interruption:        Yes
  Filename collision avoidance:      Yes
  Can time out:                      Yes
  8th-bit prefixing:                 Yes
  Repeat count prefixing:            Yes
  Alternate block checks:            Yes
  Terminal emulation:                None
  Communication settings:            Yes
  Transmit BREAK:                    Yes (depending on serial driver)
  Support for dialout modems:        No
  IBM mainframe communication:       No
  Transaction logging:               No
  Session logging:                   No
  Debug logging:                     No
  Packet logging:                    No
  Act as server:                     No
  Talk to server:                    Yes
  Advanced server functions:         No
  Local file management:             Yes
  Command/Init files:                Yes
  File attributes packets:           No
  Command macros:                    Yes
  Raw file transmit:                 No


Installing Kermit68K on an OS-9/68000 system:

What follows is a discussion of how to get Kermit68K/OS9 installed on your
system. In order to run Kermit, your OS-9 system will require the following:

  1.  A console device and driver (hereafter referred to as /term)
  2.  A serial port and driver (hereafter referred to as /t1)
  3.  Diskspace.  About 80K of free space to install Kermit.  However, if
      you want to work with the source code, you will need at least 600K of
      free space (and this is very tight)

The Kermit68K/OS9 executable file is approximately 20K, and the program needs
about 8K of variable and stack space.  It is not an extremely memory hungry
program, and if the standard input and output paths are redirected, it can be
run in the background to transfer files while you do other work.

The Kermit68K/OS9 distribution contains the following files:

Kermit68K and Kermit68K/OS9 documentation files:

  File name         Contents
  ---------         --------
  k6aaaa.hlp        A general guide to the file naming conventions used.
  k6aaaa.bwr        Report of known bugs and restriction in Kermit68K
  k6gman.doc        The user's manual for Kermit68K
  k6oaaa.hlp        This file
  k6oaaa.bwr        A companion file describing known problems/limitations of
                    Kermit68K/OS9.
  k6oimg.sre        The Kermit68K/OS9 executable (BINEX format)
                    (see the warning below)

Kermit68K/OS9 Source Code files:

  File name         Contents
  ---------         --------
  k6ocmd.asm        The interactive command line interpreter
  k6ocm2.asm        SET commands module
  k6ocm3.asm        REMOTE and SHOW commands
  k6ocm4.asm        Command line options handler
  k6octb.asm        The command tables
  k6odef.asm        Variable definitions
  k6oiof.asm        High-level I/O subroutines
  k6omai.asm        The main program
  k6omak.bld        The makefile (will be renamed 'makefile' by the renamer)
  k6opro.asm        The Kermit protocol switcher
  k6opsf.asm        Command parser subroutines
  k6optf.asm        Protocol functions
  k6opt2.asm        Low-level protocol functions
  k6ostr.asm        Message strings
  k6osys.asm        OS-9/68000 operating system interface routines.
  k6outf.asm        Utility subroutines
  k6oren.com        A shell script for renaming all of the source files to
                    be compatible with the makefile.

1.  Installing the Kermit68K/OS9 Executable file:

For ease of installation of Kermit, there is a BINEX format file containing the
executable module available as k6oimg.sre.  The BINEX format is a straight text
file which encodes each byte as two printable characters.  This is the only file
that need be downloaded to the OS-9 system in order to install Kermit, after
which Kermit itself can be used to download the rest of the files.

                    *** WARNING ***   *** WARNING ***

The k6oimg.sre file was built from sources not completely up to date, so
if you use it remember that the address of the Kermit68K main author
(Roberto Bagnara) reported by the command SHOW VERSION is NOT correct.
The correct address is Bagnara@Iboinfn over Bitnet.

                    *** WARNING ***   *** WARNING ***

Anyone attempting to install Kermit will need to have some means of downloading
a raw text file onto the OS-9 system.  The k9 utility provided with the
Microware OS-9/68000 Port-Pack is one way to accomplish this.  Another
possibility is to use another microcomputer as a terminal to your OS-9 system
and use the BUILD utility of OS-9.  Here is a possible sequence of commands to
download the kermit.os9 file to an OS-9 system from another system:

  os9> build k6oimg.sre </t1 >/t1
  os9> exbin k6oimg.sre Kermit
  os9> attr -peewr Kermit
  os9> copy kermit /d0/cmds/Kermit

The first command will re-direct the input and output of the build utility to
the external terminal line, which should be connected to the other system.  At
this point, you should instruct the other (non OS-9) system to list the file to
the serial port.  Many terminal emulation programs have this capability.

The EXBIN command converts the S-Record file to raw binary, and the ATTR command
makes the program executable.  You should substitute the name of your execution
directory for the '/d0/cmds'

If your system is like mine and your extra serial port is named '/t1', then the
command 'kermit' will start up Kermit68K/OS9 in the interactive mode.  If your
serial port has a different name, you will have to use the command 'kermit -l
/device' where '/device' is the name of your serial port.  As an alternative,
you can make a kermit.ini file which contains the command 'SET LINE /device'
which will also accomplish the desired effect.  A third alternative is to
download the source code and modify the default line name in the k68str module.

If you do not wish to work with the Kermit source code, you are finished.  See
the k6gman.doc file for complete user instructions.


2.  Acquiring the OS-9/68000 Kermit source code.

All of the OS-9/68000 Kermit source code is compatible with the standard OS-9
assembler, 'R68'.  The only software needed to build OS-9/68000 Kermit is the
standard R68 assembler and L68 linker.  The MAKE utility provided by Microware
is also helpful, and a makefile is included with the source code.  The Kermit
source files will require approximately 500 K-bytes of disk space.  This means
that single-sided disks are out, and double-sided disks are tight.  My system
has double-sided 3.5" disks each holding 650 Kbytes.  The sources take up
almost all of this space.

Create a subdirectory called 'Kermit' and change to it with the chd command.
Also, make another subdirectory 'Kermit/Rels' to hold the assembler
relocatables.  Then, using Kermit, download all the source files listed above
into the Kermit directory.

The 'k6oren.com' file is a Shell script (for OS-9) that will rename all of the
source files to make them compatible with the makefile.  You should only run
this file once.  Once you have downloaded all of the source files listed above
and renamed them, you should have the following in your kermit directory:

  Rels      k68cmd.a  k68cm2.a  k68cm3.a  k68cm4.a  k68ctb.a
  k68def.a  k68iof.a  k68mai.a  k68pro.a  k68psf.a  k68ptf.a
  k68pt2.a  k68str.a  k68sys.a  k68utf.a  makefile

To build Kermit from the sources, you need to edit the makefile to change the
definitions of the macros SDIR, RDIR, and LFLAGS to reflect the
configuration of your system.  The one supplied assumes that the system files
are on floppy disk /d0.  SDIR is the directory in which to find the sources
(usually '.').  RDIR is the directory in which to place the relocatable
'.r' files (usually Rels).  LFLAGS locates the system link library.  The
Kermit executable file will be left in your current execution directory.

Also, you need to make a DefsFile that looks like the following:

          ifp1
          use       /d0/Defs/oskdefs.d
          use       /d0/Defs/systype.d
          endc

Again, supply the correct pathnames to these two files for your system.
Once this is accomplished, just type 'MAKE' to build Kermit from the sources.
On my system with two floppy disk drives, this takes about 15 minutes.

Please report all problems and suggestions for improvement of the OS9 version
to Steve Williams.
My addresses are:

Usenet, Arpanet:  {seismo|gatech|ihnp4}!ut-sally!stevew

U.S. Snail:       1071 Clayton Lane #106
                  Austin, TX  78723

GEnie:            SPWilliams

Problems and suggestions concerning all the versions of Kermit68K should
be addressed to Roberto Bagnara (Bagnara@Iboinfn over Bitnet).

(End of K6OAAA.HLP)
15-Jul-87 02:50:47-EDT,11268;000000000001
Return-Path: <BAGNARA%IBOINFN.BITNET@CUVMA.COLUMBIA.EDU>
Received: from CUVMA.COLUMBIA.EDU by CU20B.COLUMBIA.EDU with TCP; Wed 15 Jul 87 02:50:43-EDT
Received: from IBOINFN.BITNET (BAGNARA) by CUVMA.COLUMBIA.EDU (Mailer X1.24)
 with BSMTP id 3262; Wed, 15 Jul 87 02:49:51 EDT
Date:     Wed, 15 Jul 87 08:47 N
From:     <BAGNARA@IBOINFN.BITNET> (Roberto Bagnara)
Subject:  Kermit68K release 1.0, file K6OAAA.HLP
To:       sy.fdc@cu20b.columbia.edu
X-Original-To:  FRANK

OS-9/68000 Kermit Installation Manual:

Program by:    Roberto Bagnara, University of Bologna, Italy
               Steve Williams, University of Texas at Austin, USA
Language:      68000 Assembler
Documentation: Roberto Bagnara -- Kermit68K User's Manual
               Steve Williams  -- Kermit68K/OS9 Installation Manual
Version:       1.0.00
Date:          July, 1987

Introduction:

OS-9/68000 Kermit (hereafter to be known as Kermit68K/OS9) is an implementation
of Kermit68K for microcomputer systems using the OS-9/68000 operating system
from Microware.  Kermit68K is patterned after UNIX C-Kermit, however it is
written completely in Motorola 68000 assembly language to allow easy
portability to 68000 based systems without C compilers.

Kermit68K/OS9 was written to fulfill a need for reliable file transfer between
the OS-9 operating system running on an Atari 520ST and several other systems
in a laboratory environment.  While there is a Kermit implementation currently
available for OS-9 systems, it is lacking in functionality.  Also, since I do
not have access to the Microware C compiler, I needed a version of Kermit
written in the native assembly language of the 68000.

The bulk of the program was written between May 1986 and June 1987 by Roberto
Bagnara of the Physics Department at the University of Bologna, Italy.  He is
responsible for the overall user-interface routines, as well as the Kermit
protocol routines.  Kermit68K is written in a modular fashion quite similar to
the UNIX C-Kermit after which it is patterned, to ease portability to various
operating systems running on 68000 based microcomputers.  The OS-9 system
specific modifications were performed by Steve Williams of the Electrical and
Computer Engineering Department at the University of Texas at Austin.

This document discusses only the differences between generic Kermit68K and
Kermit68K/OS9, as well as installation procedure for Kermit68K/OS9. The
complete users guide for Kermit68K (and Kermit68K/OS9) is available as
K6GMAN.DOC.


Kermit68K/OS9 Capabilities At A Glance:

  Local operation:                   Yes
  Remote operation:                  Yes
  Login scripts:                     No
  Transfer text files:               Yes
  Transfer binary files:             Yes
  Wildcard send:                     Yes
  File transfer interruption:        Yes
  Filename collision avoidance:      Yes
  Can time out:                      Yes
  8th-bit prefixing:                 Yes
  Repeat count prefixing:            Yes
  Alternate block checks:            Yes
  Terminal emulation:                None
  Communication settings:            Yes
  Transmit BREAK:                    Yes (depending on serial driver)
  Support for dialout modems:        No
  IBM mainframe communication:       No
  Transaction logging:               No
  Session logging:                   No
  Debug logging:                     No
  Packet logging:                    No
  Act as server:                     No
  Talk to server:                    Yes
  Advanced server functions:         No
  Local file management:             Yes
  Command/Init files:                Yes
  File attributes packets:           No
  Command macros:                    Yes
  Raw file transmit:                 No


Installing Kermit68K on an OS-9/68000 system:

What follows is a discussion of how to get Kermit68K/OS9 installed on your
system. In order to run Kermit, your OS-9 system will require the following:

  1.  A console device and driver (hereafter referred to as /term)
  2.  A serial port and driver (hereafter referred to as /t1)
  3.  Diskspace.  About 80K of free space to install Kermit.  However, if
      you want to work with the source code, you will need at least 600K of
      free space (and this is very tight)

The Kermit68K/OS9 executable file is approximately 20K, and the program needs
about 8K of variable and stack space.  It is not an extremely memory hungry
program, and if the standard input and output paths are redirected, it can be
run in the background to transfer files while you do other work.

The Kermit68K/OS9 distribution contains the following files:

Kermit68K and Kermit68K/OS9 documentation files:

  File name         Contents
  ---------         --------
  k6aaaa.hlp        A general guide to the file naming conventions used.
  k6aaaa.bwr        Report of known bugs and restriction in Kermit68K
  k6gman.doc        The user's manual for Kermit68K
  k6oaaa.hlp        This file
  k6oaaa.bwr        A companion file describing known problems/limitations of
                    Kermit68K/OS9.
  k6oimg.sre        The Kermit68K/OS9 executable (BINEX format)

Kermit68K/OS9 Source Code files:

  File name         Contents
  ---------         --------
  k6ocmd.asm        The interactive command line interpreter
  k6ocm2.asm        SET commands module
  k6ocm3.asm        REMOTE and SHOW commands
  k6ocm4.asm        Command line options handler
  k6octb.asm        The command tables
  k6odef.asm        Variable definitions
  k6oiof.asm        High-level I/O subroutines
  k6omai.asm        The main program
  k6omak.bld        The makefile (will be renamed 'makefile' by the renamer)
  k6opro.asm        The Kermit protocol switcher
  k6opsf.asm        Command parser subroutines
  k6optf.asm        Protocol functions
  k6opt2.asm        Low-level protocol functions
  k6ostr.asm        Message strings
  k6osys.asm        OS-9/68000 operating system interface routines.
  k6outf.asm        Utility subroutines
  k6oren.com        A shell script for renaming all of the source files to
                    be compatible with the makefile.

1.  Installing the Kermit68K/OS9 Executable file:

For ease of installation of Kermit, there is a BINEX format file containing the
executable module available as k6oimg.sre.  The BINEX format is a straight text
file which encodes each byte as two printable characters.  This is the only file
that need be downloaded to the OS-9 system in order to install Kermit, after
which Kermit itself can be used to download the rest of the files.

Anyone attempting to install Kermit will need to have some means of downloading
a raw text file onto the OS-9 system.  The k9 utility provided with the
Microware OS-9/68000 Port-Pack is one way to accomplish this.  Another
possibility is to use another microcomputer as a terminal to your OS-9 system
and use the BUILD utility of OS-9.  Here is a possible sequence of commands to
download the kermit.os9 file to an OS-9 system from another system:

  os9> build k6oimg.sre </t1 >/t1
  os9> exbin k6oimg.sre Kermit
  os9> attr -peewr Kermit
  os9> copy kermit /d0/cmds/Kermit

The first command will re-direct the input and output of the build utility to
the external terminal line, which should be connected to the other system.  At
this point, you should instruct the other (non OS-9) system to list the file to
the serial port.  Many terminal emulation programs have this capability.

The EXBIN command converts the S-Record file to raw binary, and the ATTR command
makes the program executable.  You should substitute the name of your execution
directory for the '/d0/cmds'

If your system is like mine and your extra serial port is named '/t1', then the
command 'kermit' will start up Kermit68K/OS9 in the interactive mode.  If your
serial port has a different name, you will have to use the command 'kermit -l
/device' where '/device' is the name of your serial port.  As an alternative,
you can make a kermit.ini file which contains the command 'SET LINE /device'
which will also accomplish the desired effect.  A third alternative is to
download the source code and modify the default line name in the k68str module.

If you do not wish to work with the Kermit source code, you are finished.  See
the k6gman.doc file for complete user instructions.


2.  Acquiring the OS-9/68000 Kermit source code.

All of the OS-9/68000 Kermit source code is compatible with the standard OS-9
assembler, 'R68'.  The only software needed to build OS-9/68000 Kermit is the
standard R68 assembler and L68 linker.  The MAKE utility provided by Microware
is also helpful, and a makefile is included with the source code.  The Kermit
source files will require approximately 500 K-bytes of disk space.  This means
that single-sided disks are out, and double-sided disks are tight.  My system
has double-sided 3.5" disks each holding 650 Kbytes.  The sources take up
almost all of this space.

Create a subdirectory called 'Kermit' and change to it with the chd command.
Also, make another subdirectory 'Kermit/Rels' to hold the assembler
relocatables.  Then, using Kermit, download all the source files listed above
into the Kermit directory.

The 'k6oren.com' file is a Shell script (for OS-9) that will rename all of the
source files to make them compatible with the makefile.  You should only run
this file once.  Once you have downloaded all of the source files listed above
and renamed them, you should have the following in your kermit directory:

  Rels      k68cmd.a  k68cm2.a  k68cm3.a  k68cm4.a  k68ctb.a
  k68def.a  k68iof.a  k68mai.a  k68pro.a  k68psf.a  k68ptf.a
  k68pt2.a  k68str.a  k68sys.a  k68utf.a  makefile

To build Kermit from the sources, you need to edit the makefile to change the
definitions of the macros SDIR, RDIR, and LFLAGS to reflect the
configuration of your system.  The one supplied assumes that the system files
are on floppy disk /d0.  SDIR is the directory in which to find the sources
(usually '.').  RDIR is the directory in which to place the relocatable
'.r' files (usually Rels).  LFLAGS locates the system link library.  The
Kermit executable file will be left in your current execution directory.

Also, you need to make a DefsFile that looks like the following:

          ifp1
          use       /d0/Defs/oskdefs.d
          use       /d0/Defs/systype.d
          endc

Again, supply the correct pathnames to these two files for your system.
Once this is accomplished, just type 'MAKE' to build Kermit from the sources.
On my system with two floppy disk drives, this takes about 15 minutes.

Please report all problems and suggestions for improvement of the OS9 version
to Steve Williams.
My addresses are:

Usenet, Arpanet:  {seismo|gatech|ihnp4}!ut-sally!stevew

U.S. Snail:       1071 Clayton Lane #106
                  Austin, TX  78723

GEnie:            SPWilliams

Problems and suggestions concerning all the versions of Kermit68K should
be addressed to Roberto Bagnara (Bagnara@Iboinfn over Bitnet).

(End of K6OAAA.HLP)
