MODCOMP MAXIV
KERMIT USER'S MANUAL
by
Richard D. Burke
Robert A. Borgeson
of
SETPOINT Inc.
10245 Brecksville Rd.
Brecksville, Ohio 44141
KERMIT is a copyrighted protocol of Columbia Univ. The authors of
this version hereby grant permission to copy this document
provided that it is not used for any explicitly commercial
purpose and that proper credit be given. SETPOINT Inc. makes no
warranty whatsoever regarding the accuracy of this document or
the software described within and will assume no liability
resulting from its use.
TABLE OF CONTENTS
________
Page No.
Introduction .......................... I.1
Overview .......................... II.1
KERMIT commands .......................... III.1
HELP .......................... III.1
STATUS .......................... III.1
SET .......................... III.1
DELAY .......................... III.2
EOL .......................... III.2
ESCAPE .......................... III.2
MYQUOTE .......................... III.2
PACKET .......................... III.2
SOH .......................... III.2
USL .......................... III.3
QUIT / EXIT .......................... III.3
SEND .......................... III.3
RECEIVE .......................... III.3
Technical
Appendix .......................... A.1
I.1
A. INTRODUCTION
KERMIT provides an easy, reliable way to transfer text files
between a MODCOMP Classic running under MAXIV and other machines
which have a KERMIT implementation on them. KERMIT is a
packet-oriented telecommunications protocol copyright by Columbia
University. Documentation available from them thoroughly covers
the formal details of the protocol.(1) The purpose of this manual
is to detail the specific features of this implementation and to
provide instruction on how to use KERMIT on a MODCOMP. This
manual assumes that the reader has a general knowledge of a
MODCOMP running under MAXIV. A Technical Appendix follows which
details how to allocate resources and install KERMIT on your
machine.
MAXIV KERMIT is adapted from a version written by John Lee
of RCA Labs for an HP-1000. It is implemented in Fortran IV
except for one subroutine in assembler.
(1) KERMIT Distribution
Columbia University Center for Computing Activities
Seventh Floor, Watson Laboratory
612 West 115th Street
New York, N.Y. 10025
II.1
II. OVERVIEW
MAXIV KERMIT is run by activating a job control procedure
which makes the necessary logical assignments and then, executes
the program. Each site will probably wish to create their own job
control for this, taking into account the requirements addressed
in the Technical Appendix. The original MAXIV KERMIT distribution
contains a simple command file which may be used as a guide. The
file's name is KERMIV. The syntax for activating this procedure
is:
$KERMIV co,oc
where co - logical assignment for file transfer output
(Default = CO)
oc - logical assignment for file transfer input
(Default = OC )
Operator input is always from OC and informational output is to
CO. Therefore, if no parameters are specified, KERMIT will expect
operator input and file transfer to occur at the same ports.
MAXIV KERMIT may be run in either remote or local mode. In
remote mode, the data transfer occurs at the same terminal port
which is controlling the program. Presumably, the user is
accessing the MODCOMP from some computer which has the ability to
emulate a terminal as part of a communications package. Local
mode implies that KERMIT is controlled by a terminal which is on
an I/O port different from the port assigned to the data
transfer. This is most likely to be used when neither machine has
a communications software package. When MAXIV KERMIT is initially
run, it senses the current logical assignments and chooses the
appropriate mode automatically. In the initial release ( Version
1.0 ), it is not possible to alter the file transfer port or the
local/remote mode once KERMIT is invoked.
MAXIV KERMIT is designed with a command structure that
reflects MAXIV's division of files into libraries. KERMIT is
always logically assigned to a directorized source library. (by
default, USL) If the user does not intervene, all files to be
sent must be cataloged in USL. All received files will by default
be cataloged to USL. The methods to modify these defaults are
discussed later.
KERMIT's choice of <CTL-A> (ASCII 01) as the start-of-packet
character presents special problems under MAXIV since this is the
standard break character for getting the TMP prompt. Short of
requiring that the break character be redefined in the SYSGEN,
there is no bulletproof way to always pass the <CTL-A> through to
KERMIT without waking up TMP.
II.2
The user must be aware that all input including the <CTL-A>s
will be passed through into a 132 byte buffer. This is sufficient
for at least one packet. However, if the other KERMIT sends a
number of unexpected packets it could fill up the buffer. One
possible scenario that could cause this is when the other KERMIT
begins to send initialization packets before MAXIV KERMIT is told
to receive. If this buffer is ever filled up an outstanding read
request is terminated and the next <CTL-A> received will be
interpreted as the break character. In this case, the user has no
choice other than to exit KERMIT and start over. In local mode,
the buffer is activated immediately upon execution but, no check
for incoming packet data is made until MAXIV KERMIT is told to
SEND or RECEIVE. In remote mode, it is activated as soon as the
SEND or RECEIVE command is entered. Once the initial connection
is made, the buffer is checked periodically for packet data and
refreshed after each packet so that it should not overflow. It is
important to remember that this checking only occurs in SEND and
RECEIVE mode. At other times the user must exercise discretion
regarding sending unexpected packets.
The conclusion is that MAXIV KERMIT is more sensitive to the
initial connection sequence than many other KERMITs. The
following general principles may be helpful:
Local mode
Invoke MAXIV KERMIT first. In the case of MODCOMP to
MODCOMP transfer start the receiving KERMIT first.
Remote mode
Issue the command to the remote machine first.
III.1
III. MAXIV KERMIT COMMANDS
After executing KERMIT, the prompt "MAXIV KERMIT>" will
appear. The user may enter the following commands:
HELP
STATUS
SET
EXIT / QUIT
SEND
RECEIVE
CONNECT
These commands may or may not require additional parameters. In
all cases, the parameters must be separated by spaces. The
commands and parameters may be abbreviated so long as they may be
uniquely identified. For example, HELP may be shortened to H, but
SEND can only be shortened to SEN so that it may be distinguished
from SET. The CONNECT command is recognized but the function is
not supported in Version 1.0 . The other commands are discussed
below.
HELP
The command HELP prints out a description of each
available command to the terminal.
STATUS
The command STATUS prints out the current values for a
number of user-definable parameters.
SET
The command SET allows the user to change various
parameters according to your current needs. The syntax
of the command is:
SET option value
III.2
The options and their applicable values are:
SET DELAY x
This command controls how long KERMIT waits before
sending an initialization packet. The values 1 -
60 seconds are acceptable. The default is 10
seconds.
SET EOL x
This command sets the end-of-line character which
this KERMIT is expecting to terminate each
received packet. This value does not have to match
the EOL expected by the other KERMIT. The values
1 - 31 are acceptable with the default being 13
(<CR> ).
SET ESCAPE x
This command sets the character which terminates
CONNECT mode. Since CONNECT is not currently
supported, this command has no operational effect.
SET MYQUOTE x
This command sets the value for the character
which prefixes all ASCII translated control
characters. The valid values are 33 - 126. The
default is 35 (<#>).
SET PACKET x
This command sets the maximum packet length we
want to receive. The valid values are 31 - 94
characters. The default is 90.
SET SOH x
This command sets the start-of-packet character.
The acceptable values are 1 - 31. The default
value is 1 (<CTL-A>). This is not a parameter
which is adjusted by the initial exchange.
Therefore, both KERMIT's must agree before the
connection is made.
III.3
SET USL usl
This command changes the library which KERMIT is
logically pointed at. This library must be a SED
directorized partition or dataset. The default is
USL.
QUIT / EXIT
Either command will end this KERMIT session. If any files
were received, the user will then be prompted to catalog them
away properly.
SEND
This command has two forms:
SEND file_id
SEND @usl
The first command will send a single file with the specified
name. The file must be cataloged in the current USL. (see the SET
USL command) The second command will send every file in the
specified library. This library is not required to be the same as
the current source library. It may be a library in a scratch
partition. This allows the operator to create a directorized
library in scratch and catalog files from several libraries to be
sent as a group.
RECEIVE
When the command RECEIVE is issued, MAXIV KERMIT will
receive as many files as are sent until the sender KERMIT issues
an end-of-transmission. The files are placed in a scratch
partition to be cataloged at the end of the session. When MAXIV
KERMIT is EXITed, the user is prompted to name and catalog the
received files. The answers to these questions are used to create
a Job Control procedure which places the files in the desired
libraries. The default file name is the received file name
truncated to 8 characters with any non-cancodeable characters
replaced by "$". The user may elect to accept all the default
names. In this case, you will be asked whether all the files
should be CATaloged or RECATaloged to the current source library.
If all the defaults are not accepted, you will be prompted to
name each file, specify the library to use, and whether to CAT or
RECAT. When the questions have all been answered, the command
procedure is automatically invoked to perform the desired file
operations.
III.4
In the event that a file name conflict causes the cataloging
operation to fail, all is not lost! The command procedure is in
KE9 under the name "STORE" and can be edited to correct the
problem. Then reinvoke the procedure to complete the operation.
Care must be exercised to preserve the received text while the
procedure is being modified.
A.1
TECHNICAL APPENDIX
___________________________
A. Building KERMIT from Source
The KERMIT source files are intended to reside in a single,
directorized SED USL library. Procedures are provided to
compile, assemble, and link all modules and to create KERMIT as a
load module overlay. All subroutines should be compiled to a
single, directorized object library. This library will then be
referenced to link the main program. The procedure which builds
KERMIT is called BLDKER and it requires 3 arguments. BLDKER
could be invoked as follows:
$ASSIGN JC=KER,UJC=KER
$BLDKER KER,KUL,BM
where - KER is the source library containing KERMIT
source,
KUL is a directorized object library to contain
object versions of all KERMIT subroutines,
BM is the load module library to contain the
KERMIT overlay.
The fourth argument to BLDKER is an optional switch which
tells whether or not to generate listing output. For example, to
generate hardcopy listings during the build invoke BLDKER as
follows:
$ASSIGN JC=KER,UJC=KER,LO=LP
$BLDKER KER,KUL,BM,LO
__________________________________
B. Logical file assignments and usage
KERMIT requires several logical files which must be assigned
to I/O channels and scratch disk partitions. They are as
follows:
KE1 - Terminal output
KE2 - Terminal input
KE3 - KERMIT data output
KE4 - KERMIT data input
KE5 - List of file names received during the current session
KE8 - Received text files
KE9 - List of file names to be sent to the remote KERMIT,
and Job Control procedure to catalog received files
away
KEH - Directorized source library containing HELPFILE
A.2
One or two full duplex or half duplex asynchronous I/O ports
may be used for KERMIT. If KE2 and KE4 are assigned to the same
device (port) then remote operation is assumed. If they are
assigned to different ports then KERMIT is set up for local
operation.
As files are received, the text is written to the disk
partition to which KE8 is assigned, and the name of the file is
written to KE9. When the user EXITs, several questions are asked
concerning the disposition of the files. The file name list in
KE9 is then used as the basis for creating a Job Control
procedure to catalog all the received files to directorized
libraries.
KE9 is also used to contain a list of file names to be
transmitted to the remote KERMIT. This file will contain either
a single name, specified by the "SEND filename" command or the
names of all the files in a directory if the "SEND @usl" command
is used.
For most applications, the disk resources of a BATxxx task
are adequate for KERMIT. The procedure KERMIV which is provided
as a template uses SCA for keeping received files, SCB for the
received file list, and SC for the sending file list and Job
Control procedure. KERMIV also provides the capability of
designating the logical device(s) to be used for KERMIT file
transfer input and output.
__________________________________________
C. Control-A collision between KERMIT and TMP
Many systems use Control-A as the TMP attention character.
It is also used by KERMIT as the start-of-packet character. This
causes problems if the asynch port used for KERMIT transfers is
on the MAX IV break list.
This is only a problem when KERMIT is operating in local
mode. When KERMIT is invoked in local mode, a non-standard binary
read is immediately issued to intercept any unsolicited packets
which could cause a BREAK. However if the number of unsolicited
characters exceeds the size of the read (132 bytes) the read will
complete and the next control-A will cause a BREAK. To avoid
this anomaly it is necessary to initiate the SEND and RECEIVE
operations at roughly the same time. The user may want to
customize KERMIT by increasing the size of the incoming data
buffers, but must take note that only the first packet in the
buffer is interpreted.
A.3
_______________________________
D. Warning about SEND @usl command
This command causes the specified directory to be read and
the names of all active file entries to be extracted. This logic
will only work correctly for 128 word-per-sector disks. Systems
with sector sizes different from 128 words should avoid this
command.
________________________________________
E. BATxxx task resources required by KERMIT
The number of concurrent I/O operations and the number of
vacant logical file assignments for Batch tasks which will be
running KERMIT may have to be increased. 3 I/O operations and 15
vacant logfiles are adequate for KERMIT's use.
The partitions assigned for scratch use for KERMIT must be
large enough to hold the data that KERMIT will temporarily store
there. The critical file is KE8 which holds the received text
files. Received files are written in compressed format so as to
conserve disk resources, but the user must still make sure that
KE8, or any other disk partitions are not overfilled.
________________________________
F. Communications port conditioning
The configuration (baud rate, frame size, parity, and stop
bits) of the I/O port used for KERMIT file transfers must be set
up to match the parameters of the remote KERMIT before the MAX IV
KERMIT is invoked. Modification of those parameters is not
supported in this release of KERMIT.
___________________
G. Future Enhancements
This version of KERMIT implements only some of the basic
features of a KERMIT program. Time permitting several additions
are planned. Those include:
1) SET LINE and CONNECT commands to allow going from
local to remote operation after KERMIT is invoked
and to support a dumb terminal emulation.
2) SERVER commands to simplify the transfer of files
to KERMIT versions which support server commands.
3) TAKE command which allows command sequences to be
stored in an external disk file and invoked from
inside KERMIT.
4) Use of the SET command to modify the KERMIT I/O
port parameters such as baud rate, parity, frame
size, or stop bits.
A.4
5) A STATISTICS feature which would summarize
information about the current session and the
current transaction, including bytes transferred,
packets transferred, and effective transfer rate.