home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Columbia Kermit
/
kermit.zip
/
archives
/
ibmtsochicago.zip
/
tsokerdoc.txt
< prev
next >
Wrap
Text File
|
1984-07-18
|
20KB
|
456 lines
107/10/84 KERMIT-TSO
1. Introduction
KERMIT is a set of programs that transfer files between computers over normal
terminal communication lines. It implements the "KL10 Error-Free Reciprocol
Microcomputer Interchange over TTY-Lines" protocol. Originally designed to be
used between a microcomputer and the DEC-20, the protocol will also transfer
files to and from a microcomputer and IBM mainframe systems running under
MVS/TSO.
KERMIT transfers data by creating packets with information regarding the type
of packet being sent, it's length, a packet number, and a checksum to determine
whether the data has been modified during transmission. If a packet is lost or
garbled, KERMIT will attempt to resend it.
Written in IBM 370 assembly language to run under MVS/TSO on IBM 370-series
mainframes (System/370, 303x, 43xx, 308x, ...). These are half duplex systems;
the communication line must "turn around" before any data can be sent to it.
The fact that a packet has been received from the IBM system is no guarantee
that it is ready for a reply. Thus any Kermit talking to this system must wait
for the line turnaround character (XON) before transmitting the next character.
IBM systems talk to their terminals through a communications front end (IBM
3705, 3725, COMTEN 3670, etc). These front ends generally insist on using the
8th bit of each character for parity. This means that binary files (files
con-taining other than ordinary letters, digits, punctuation, carriage returns,
tabs, and so forth) can not be correctly sent or received by these systems with
Kermit (protocol version 1).
The IBM system under MVS/TSO is unable to interrupt a read on its "console".
This means that the IBM version of Kermit cannot timeout. The only way to
"timeout" TSO Kermit is from the other side -- typing a carriage return to the
micro's Kermit causing it to retransmit its last packet, or an automatic
timeout as provided by Kermit-20. For this reason, TSO Kermit waits thirty
seconds before sending its first packet when sending files from MVS/TSO. This
gives the user sufficient time to return to the local Kermit and issue the
Receive command. Otherwise, a protocol deadlock would arise requiring manual
intervention by the user.
Also, MVS/TSO stores files as records rather byte streams. MVS/TSO Kermit has
to worry about assembling incoming data packets into records and stripping
CRLFs from incoming lines, and also appending CRLFs to - and stripping trailing
blanks from -- outgoing records.
You must be using an ASCII terminal to run KERMIT-TSO.
KERMIT-TSO must be installed as a Command Processor (CP) on your system.
Please note that this document should be used in conjunction with the Kermit
manual, and assumes you have read the sections pertaining to the IBM/PC
microcomputer. For more information regarding the manual, see the Reference
section at the end of this report.
-
0
-1-
107/10/84 KERMIT-TSO
2. TSO Command Syntax and Options
KERMIT
You simply type a carriage return after issuing the
KERMIT command.
Commands:
Send
Receive
Set
Show
Status
Help
Exit
Quit
?
2.1. TSO KERMIT Command Options
SEND [dataset name]
Send the specified dataset. KERMIT-TSO will send
only one file per request, no wildcarding is
allowed. If the dataset name is not specified,
KERMIT-TSO will prompt for one. Note, dataset
must be cataloged.
RECEIVE [dataset name]
Receive the file sent from the micro. If the
dataset name is not specified KERMIT-TSO will
prompt for one. If no dataset previously exists
with this name a file will be created using the
value of the SPACE parameter. (NOTE, at this
time KERMIT-TSO does not trap for abends, and if
the file being received excedes the space
allocated KERMIT-TSO will abnormally terminate.)
The attributes for the dataset will be taken from
the RECFM, LRECL, and BLKSIZE parameters. If a
dataset exists KERMIT-TSO will prompt to see if
you wish to overwrite the dataset.
SET <parameter> <value>
Set the parameter to the specified value. Legal
Set commands are:
-2-
107/10/84 KERMIT-TSO
SPACE <d>
Specifies the number of tracks to be
allocated to the dataset. The default is 5
tracks. Both the primary and secondary
allocation are set to the value specified.
RECFM <c>
Denotes the record format to be used when
creating the dataset. Only fixed and
variable length records are allowed, where
variable is the default. Indicate the
desired record format by either an F or a V.
BLKSIZE <d>
Indicates the block size for creating the
dataset. The default is 80 and the maximum
is 32767. If the RECFM is F the blocksize
must be a multiple of the value specified in
the LRECL parameter. If RECFM is F then the
BLOCKSIZE must be at least LRECL + 4.
LRECL <d>
Indicates the logical record length for
creating the dataset. The default is set to
80, and the maximum allowed is 255. If the
RECFM is V the value must include the 4
bytes for the record descriptor word (RDW).
QUOTE <c>
The quote character you wish to use in place
of the default (#). It must be a single,
printable character from among the
following: 33-62, 96, or 123-126 (decimal).
START <d>
Indicates the start-of-header character
which you choose to send and receive. The
default is a CNTL-A (ASCII 01), but can be
set to any two digit number between 00 and
31 (dec).
END <d>
Indicates the end-of-line character you
choose to send. The default is a CR (ASCII
13), but can be set to any two digit number
between 00 and 31 (dec).
PAC <d>
Allows the user to specify the packet size
the micro should use when sending to
KERMIT-TSO. The range is 26-94 (decimal),
where 94 is the default.
DEBUG [ON | OFF]
Allows the user to specify whether a trace
-3-
107/10/84 KERMIT-TSO
of packet information will be writen to a
dataset. Before using this option the user
must have allocated a dataset to file name
(ddname) "DEBUG".
DELAY <d>
Allow the user to specify the length of time
in seconds that KERMIT-TSO will wait after
the user issues a SEND. The default is 20
seconds. This will give the user time to
escape back to his micro KERMIT and issue
the neccesary commands.
SHOW STATUS
Displays the current value of all variables that
can be changed via the SET command.
STATUS
Returns the status of the previous execution of
KERMIT-TSO. Therefore, STATUS will either
display the message "Kermit completed
successfully", or the last error encountered
prior to aborting.
HELP Displays a message that briefly explains KERMIT-TSO commands.
EXIT from KERMIT-TSO.
QUIT Same as EXIT.
? Lists all legal KERMIT-TSO commands.
3. Examples under TSO
Here is a brief example of how to use the IBM/PC in conjunction with KERMIT-TSO
to send a file to the IBM-PC.
A>kermit
Kermit-86>set loc on ; Indicate half duplex
Kermit-86>set ibm on ; Cause line turn around wait
Kermit-86>set baud 1200 ; Set the baud rate
Kermit-80>connect
[ The micro will act as a regular terminal from now on.]
[ Login here as you normally would, and run KERMIT-TSO.]
kermit
KERMIT-TSO>?
Legal Commands are:
Receive, Send, Help, Exit, Quit, Set, Status, Show
KERMIT-TSO>send finger.database ; Send this file
Waiting 20 seconds before sending.
^]C ; Return to the micro
-4-
107/10/84 KERMIT-TSO
; by typing <escape>]C
Kermit-86>
Kermit-86>receive ; Micro receives the file
[the file is sent .......]
Kermit-86>connect
[press carriage return to see TSO's prompt]
KERMIT-TSO>status
Kermit completed successfully
KERMIT-TSO>ex
READY
logoff
CONNECT TIME - 2:30.95
SYSRONR Logged off TSO at 15:34:25 on July 6, 1984
^]C ; Return to the micro
; by typing <escape>C
Kermit-86>exit
A>
In order to send a file from the IBM/PC to the IBM mainframe repeat the above
procedure swapping the command SEND with RECEIVE and vice versa.
4. Additional Information
1. The commands are supplied with a help option, so a question mark can be
typed to get the appropriate format or a list of options. The question
mark, however, must be followed by a carriage return; KERMIT-TSO will
respond and display the prompt again. For instance, SET ? will list all
valid options for the SET command.
2. When receiving files, if the record format is fixed, any record longer
than the logical record length will be truncated. The record length can
be as high as 255. For receiving files, the maximum record length is
255.
3. Before connecting to the IBM mainframe, three flags must be set. You
should set the IBM flag on, set the LOCAL-ECHO flag on (used to indicate
half duplex), and specify the baud rate you will be using. To turn a
flag on, type to the micro's prompt "Set XXX On" where XXX is the flag
name. Indicate the baud rate by typing "Set baud", and choose from among
a list the IBM-PC supplies. These flags will remain in effect as long as
you do not exit from the micro's version of Kermit. See the example of a
session for further clarification.
4. The current version of KERMIT-TSO does not support timeouts. The user,
therefore, should hit the carriage return key after a long period of
inactivity (that is, when the screen display does not change.)
-5-
107/10/84 KERMIT-TSO
5. Since the micro does not send an error packet when it aborts, KERMIT-TSO
does not know the micro has stopped sending it information. Therefore,
when you connect back to the IBM, KERMIT-TSO may still be sending packets
(they will appear on the screen). The user must hit a carriage return
until KERMIT-TSO has sent the maximum number of packets allowed and
aborts. The error message, however, will not indicate that communication
stopped because the micro aborted, but rather that no start of header
character was found.
6. The minimum send packet size KERMIT-TSO will allow is 26. This is
necessary to avoid an error while sending the filename or an error
packet. If the micro tries to set the value to be less than 26,
KERMIT-TSO will immediately abort with an error of "Bad send-packet
size."
7. During the initialization process with the micro, KERMIT-TSO sends all
six pieces of information (that is, the receive packet size, the timeout
data, the number of padding characters, the character used for padding,
the line terminator, and the quote character.) When receiving this data
from the micro, KERMIT-TSO ignores the data regarding timeouts and
padding; they do not effect the program's execution. Therefore, if the
quote and end-of-line characters used are the defaults, the micro need
only send KERMIT-TSO its buffer size. Only if the defaults are not used
must ALL the information be sent (since the data is organized
positionally). If, however, the micro sends all the information even
when not required, KERMIT-TSO will simply ignore the irrelevant portion.
8. When sending packets to KERMIT-TSO, the micro must use a carriage return
as the end-of-line character. TSO requires a carriage return to
terminate a read from the terminal; thus, if any other character is used,
KERMIT-TSO will never get the packets.
9. KERMIT-TSO translates the data it reads back to ASCII (characters not
representable in ASCII are replaced by a null). Not only is it easier to
work with ASCII characters, but it makes things more consistent
throughout the many versions of Kermit. When the packets are sent to the
micro, KERMIT-TSO converts all data back to EBCDIC. The ASCII to EBCDIC
translation table can be found in Appendix V of the Kermit manual.
4.1. Error Messages
KERMIT-TSO supplies the micro and the user with numerous error messages. If
the execution must be aborted, an error packet is sent to the micro before
KERMIT-TSO stops. The same message can be retrieved via the STATUS command
when KERMIT-TSO returns and displays the prompt. If KERMIT-TSO aborted because
the maximum amount of retries was exceeded (20 on initialization packets and 5
on others), the error message will display the most recent error (i.e. - the
last NAK KERMIT-TSO encountered). If execution stops because the micro
aborted, the error message will convey that to the user, but it is the micro's
responsibility to pinpoint the error. The messages KERMIT-TSO gives are as
follows :
"Bad send-packet size"
Sent when the micro attempts to set its receive buffer size to a
value that is less than 26 (the minimum that KERMIT-TSO will
-6-
107/10/84 KERMIT-TSO
accept) or larger than 94, the maximum. It will also occur if
KERMIT-TSO tries to send a packet that is larger than the maximum
specified.
"Bad message number"
If the packet number is less than zero or greater than 63 (at
which point it should "wrap around" back to zero).
This message is returned if the packet type does not fall between
A-Z.
"Unrecognized State"
If KERMIT-TSO is in a state not previously defined by the
protocol, it will abort with this message.
"No SOH encountered"
This error arises if KERMIT-TSO reads the entire packet without
encountering an SOH character. The result is that it sends a NAK
to the micro, and marks this error as the most recent one.
"Bad Checksum"
If the checksum calculated by KERMIT-TSO does not match the one
sent by the micro, KERMIT-TSO NAK's the packet and flags this
error.
"Bad character count"
This error is set if KERMIT-TSO receives a packet whose size is
illegal (that is, if the size parameter was garbled during
transmission of the packet.)
"Micro sent a NAK"
Keep track of who rejected the packet.
"Lost a packet"
When a packet is received and the sequence number is different
from the number KERMIT-TSO expected, the packet is NAK'ed.
"Micro aborted"
Tells you that the micro aborted unexpectedly.
"Invalid RECFM, only fixed or variable supported"
KERMIT-TSO will abort on any file-system error it encounters when
reading from the file it is to send. It can only send files with
variable or fixed length record formats, therefore, Wylbur Edit
or Packed format files will cause an error.
"BLKSIZE not a multiple of LRECL for RECFM=F"
KERMIT-TSO will refuse RECEIVE request and return to the KERMIT
prompt. The BLOCKSIZE is not an integral multiple of the LRECL
when RECFM F (fixed) is specified.
"LRECL not less than BLKSIZE-4 for RECFM=V'
KERMIT-TSO will refuse RECEIVE request and return to the KERMIT
prompt. The LRECL for RECFM=V (variable) must be four less than
-7-
107/10/84 KERMIT-TSO
the BLKSIZE to include the block descriptor work (BDW).
"Open for dataset failed"
Indicates a problem opening the dataset.
5. Reference
For a more detailed explanation of Kermit or information regarding the IBM-PC,
consult the Kermit manual, Kermit Users Guide and Specification. The manual is
available in the Reference Library at USITE.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-8-