home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Columbia Kermit
/
kermit.zip
/
archives
/
guts.tar.gz
/
guts.tar
/
guts.man
< prev
next >
Wrap
Text File
|
1988-08-16
|
24KB
|
531 lines
1
-
KERMIT-GUTS February 11, 1985
-
1. Introduction
+_______________
0KERMIT 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/GUTS.
0KERMIT 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.
0Written in IBM 370 assembly language to run under MVS/GUTS 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.
0IBM systems talk to their terminals through a communications front
end (IBM 3705, 3725, COMTEN 3805, 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).
0The IBM system under MVS/GUTS is unable to interrupt a read on its
"console". This means that the IBM version of Kermit cannot
timeout. The only way to "timeout" GUTS 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, GUTS Kermit waits twenty seconds
before sending its first packet when sending files from MVS/GUTS.
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.
0Also, MVS/GUTS stores files as records rather byte streams. MVS/GUTS
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.
0You must be using an ASCII terminal to run KERMIT-GUTS.
0KERMIT-GUTS can only work with OS files, not with GUTS files. This
0 - 1 -
1
-
KERMIT-GUTS February 11, 1985
0means that if you want to transfer a GUTS file you will have to copy
it first to an OS file.
The KERMIT-GUTS receives a file from a micro he will store it as an OS
file. You can then after transmission copy the OS file to a GUTS file.
For more information see chapter 5.
-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.
-
-
-
-
-
-
-
-
-
-
-
-
-
- - 2 -
1
-
KERMIT-GUTS February 11, 1985
02. GUTS Command Syntax and Options
+__________________________________
-/KERMIT
0You simply type a carriage return after issuing the KERMIT command.
0Commands:
0 Send
0 Receive
0 Set
0 Show
0 Status
0 Help
0 Exit
0 Quit
0 ?
-2.1. GUTS KERMIT Command Options
+________________________________
0SEND <dataset name>
Send the specified dataset. KERMIT-GUTS will send only one
file per request, no wildcarding is allowed. If the
dataset name is not specified, KERMIT-GUTS will prompt
for one. Note, dataset must be cataloged. Kermit will only
search on the volume(s) specified with the /SET UNIT=
command. Kermit will add your &INDEX prefix to the dataset
name unless you have written a leading and trailing
apostrophy.
0RECEIVE <dataset name>
Receive the file sent from the micro. If the dataset
name is not specified KERMIT-GUTS 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-GUTS does not trap for abends,
and if the file being received excedes the space
allocated KERMIT-GUTS will abnormally terminate.) The
attributes for the dataset will be taken from the RECFM,
LRECL, and BLKSIZE parameters. If a dataset exists
KERMIT-GUTS will prompt to see if you wish to overwrite the
dataset. Note| Kermit will create an OS dataset, not a GUTS
0 - 3 -
1
-
KERMIT-GUTS February 11, 1985
0 file. The OS dataset will be plased on the volume, or one of
the volumes you have specified by the /SET UNIT= command.
0SET <parameter> <value>
Set the parameter to the specified value. Legal Set
commands are:
- 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.
0 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.
0 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.
0 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).
0 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).
0 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).
0 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).
- - 4 -
1
-
KERMIT-GUTS February 11, 1985
0 PAC <d>
Allows the user to specify the packet size the micro
should use when sending to KERMIT-GUTS. The
range is 26-94 (decimal), where 94 is the default.
0 DEBUG <ON | OFF>
Allows the user to specify whether a trace 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".
0 DELAY <d>
Allow the user to specify the length of time in seconds
that KERMIT-GUTS 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.
0STATUS
Returns the status of the previous execution of
KERMIT-GUTS. Therefore, STATUS will either
display the message "Kermit completed
successfully", or the last error encountered prior
to aborting.
0HELP Displays a message that briefly explains KERMIT-GUTS
commands.
0EXIT Exit from KERMIT-GUTS.
0QUIT Same as EXIT.
0? Lists all legal KERMIT-GUTS commands.
-
-
-
-
-
- 5 -
1
-
KERMIT-GUTS February 11, 1985
03. Examples under GUTS
+______________________
0Here is a brief example of how to use the IBM/PC in conjunction with
KERMIT-GUTS to send a file to the IBM-PC.
0 A>kermit
0 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
0 < The micro will act as a regular terminal from now on. >
< Logon here as you normally would, and run KERMIT-GUTS.>
0 /KERMIT
KERMIT-GUTS Version 1.00 at GUC.
0 KERMIT-GUTS>?
Legal Commands are:
Receive, Send, Help, Exit, Quit, Set, Status, Show
KERMIT-GUTS>send finger.database ; Send this file
0 Waiting 20 seconds before sending.
^$C ; Return to the micro
-
0 ; by typing <escape>$C
0 Kermit-86>
Kermit-86>receive ; Micro receives the file
0 <The file is sent .......>
0 Kermit-86>connect
0 <press carriage return to see GUTS's prompt>
0 KERMIT-GUTS>status
Kermit completed successfully
KERMIT-GUTS>ex
_
/OFF
TSC0018I ABCAA logged off at 13.47.10, Monday, February 11, 1985
......
0 ^$C ; Return to the micro
; by typing <escape>C
0 Kermit-86>exit
0 - 6 -
1
-
KERMIT-GUTS February 11, 1985
0 A>
0In 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- 7 -
1
-
KERMIT-GUTS February 11, 1985
04. Additional Information
+_________________________
0 The commands are supplied with a help option, so a question
+1.
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-GUTS will respond and display the
prompt again. For instance, SET ? will list all valid options
for the SET command.
0 When receiving files, if the record format is fixed, any
+2.
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.
0 Before connecting to the IBM mainframe, three flags must be
+3.
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.
0 The current version of KERMIT-GUTS does not support timeouts.
+4.
The user, therefore, should hit the carriage return key after
a long period of inactivity (that is, when the screen display
does not change.)
0 Since the micro does not send an error packet when it aborts,
+5.
KERMIT-GUTS does not know the micro has stopped sending it
information. Therefore, when you connect back to the IBM,
KERMIT-GUTS may still be sending packets (they will appear on
the screen). The user must hit a carriage return until KERMIT-
GUTS 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.
0 The minimum send packet size KERMIT-GUTS will allow is 26.
+6.
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-GUTS will immediately
abort with an error of "Bad send-packet size."
0 During the initialization process with the micro, KERMIT-GUTS
+7.
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-GUTS ignores the data regarding timeouts and
padding; they do not effect the program's execution.
0 - 8 -
1
-
KERMIT-GUTS February 11, 1985
0 Therefore, if the quote and end-of-line characters used are the
defaults, the micro need only send KERMIT-GUTS 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-GUTS will simply
ignore the irrelevant portion.
0 When sending packets to KERMIT-GUTS, the micro must use a
+8.
carriage return as the end-of-line character. GUTS
requires a carriage return to terminate a read from the
terminal; thus, if any other character is used, KERMIT-GUTS will
never get the packets.
0 KERMIT-GUTS translates the data it reads back to ASCII
+9.
(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-GUTS
converts all data back to EBCDIC. The ASCII to EBCDIC
translation table can be found in Appendix V of the Kermit
manual.
-
-
-
-
-
-
-
-
-
-
0 - 9 -
1
-
KERMIT-GUTS February 11, 1985
04.1. Error Messages
+___________________
0KERMIT-GUTS 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-GUTS stops. The same message can be
retrieved via the STATUS command when KERMIT-GUTS returns and displays
the prompt. If KERMIT-GUTS 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-GUTS 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-GUTS gives are as follows :
0 "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-GUTS will accept) or larger than 94, the
maximum. It will also occur if KERMIT-GUTS tries to
send a packet that is larger than the maximum
specified.
0 "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.
0 "Unrecognized State"
If KERMIT-GUTS is in a state not previously
defined by the protocol, it will abort with this
message.
0 "No SOH encountered"
This error arises if KERMIT-GUTS 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.
0 "Bad Checksum"
If the checksum calculated by KERMIT-GUTS does not
match the one sent by the micro, KERMIT-GUTS NAK's the
packet and flags this error.
0 "Bad character count"
This error is set if KERMIT-GUTS receives a packet
whose size is illegal (that is, if the size
parameter was garbled during transmission of the
packet.)
0 "Micro sent a NAK"
Keep track of who rejected the packet.
0 - 10 -
1
-
KERMIT-GUTS February 11, 1985
- "Lost a packet"
When a packet is received and the sequence number is
different from the number KERMIT-GUTS expected, the
packet is NAK'ed.
0 "Micro aborted"
Tells you that the micro aborted unexpectedly.
0 "Invalid RECFM, only fixed or variable supported"
KERMIT-GUTS 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.
0 "BLKSIZE not a multiple of LRECL for RECFM=F"
KERMIT-GUTS 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.
0 "LRECL not less than BLKSIZE-4 for RECFM=V'
KERMIT-GUTS will refuse RECEIVE request and return to
the KERMIT prompt. The LRECL for RECFM=V (variable)
must be four less than the BLKSIZE to include the
block descriptor work (BDW).
0 "Open for dataset failed"
Indicates a problem opening the dataset.
-
-
-
-
-
-
-
- - 11 -
1
-
KERMIT-GUTS February 11, 1985
0 5. Sending and receiving a GUTS file.
+ _____________________________________
- KERMIT-GUTS can only send and receive OS files.
If you want to send a GUTS file you must first copy it
to an OS file. If you want to receive a GUTS file, you
must copy the OS file to a GUTS file. The following
examples will illustrate how to do this:
- Sending a GUTS file to a micro
+ ______________________________
0 /ALLCAT PUB001,TESTFILE -- Allocate and catalog an OS file called --
-- TESTFILE on PUB001. --
(Note. The Volumename must corresponde with the volume or volumes
you have specified with the /SET UNIT= command. See GUTS referense
Manual for further information.)
0 /TSOS DATA,TESTFILE -- Copy the GUTS file "DATA" to the OS file --
-- TESTFILE --
0 /KERMIT -- Start up the KERMIT-GUTS program --
KERMIT-GUTS version 1.00 at GUC.
0 KERMIT-GUTS> SEND TESTFILE
Waiting 20 seconds before sending.
0 (Now go back to your micro and tell it to receive a file)
0 (After successful transmission you connect back to KERMIT-GUTS)
KERMIT-GUTS> EXIT
/SCRUNC TESTFILE -- Scratch and uncatalog the OS file --
-
-
-
-
-
-
-
- 12 -
1
-
KERMIT-GUTS February 11, 1985
0 Receiving a GUTS file from a micro.
+ ___________________________________
0 /KERMIT -- Start the KERMIT-GUTS program --
KERMIT-GUTS version 1.00 at GUC.
0 KERMIT-GUTS> RECEIVE TESTFILE (Tell KERMIT-GUTS to receive a file
from the micro and call the OS file "TESTFILE")
0 (Now go back to your micro and ask it to send your file to GUTS.
After successful transmission go connect back to KERMIT-GUTS.)
0 KERMIT-GUTS> EXIT
0 /OSTS TESTFILE,TEST -- Copy the OS file "TESTFILE" to --
-- a GUTS file and call it "TEST" --
0 /SCRUNC TESTFILE -- Scratch and uncatalog the OS file --
-- called TESTFILE --
-
-
-
-
-
-
-
-
-
-
-
- - 13 -
1
-
KERMIT-GUTS February 11, 1985
0 6. Reference
+ ____________
0 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 at Gothenburg Universities'
Computing centre.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
0 - 14 -