IBM MVS/TSO KERMIT
==================
Programmer: Fritz Buetikofer, Help desk member at the University of
&Documentation: Bern (Switzerland).
Language: PASCAL/VS
Adaptation from the CMS-version of Victor Lee (Queens University)
Version: 2.3
Date: September 1987
TSO Kermit Capabilities At A Glance:
Local operation: No
Remote operation: Yes
Transfers text files: Yes
Transfers binary files: Yes
Wildcard send: Yes
^X/^Y interruption: No
Filename collision avoidance: Yes
Can time out: No
8th-bit prefixing: Yes
Repeat count prefixing: Yes (RECEIVE only)
Alternate block checks: Yes
Terminal emulation: No
Communication settings: No
Transmit BREAK: No
Transaction logging: Yes
Session logging: No
Raw transmit: No
Act as server: Yes
Talk to server: Yes (only from startup file)
Advanced server functions: Yes
Advanced commands for servers: No
Local file management: Yes
Command/init files: Yes
Command macros: No
Handle Attribute Packets: Yes (puts them in the LOG-file)
Extended-length packets: Yes (Maximum size is 1K)
Sliding windows: No
Kermit-TSO is a program that implements the KERMIT file transfer
protocol for IBM 370-series mainframes (System/370, 303x, 308x, etc.)
under the MVS/TSO operating system.
It is written in IBM PASCAL/VS language. This Program runs only over
ASCII (asynchronous) lines attached to a 3705-style front end.
Actually Kermit-TSO is unable to interrupt a read on its "console".
This means that the TSO version of Kermit cannot timeout. The only way
to "timeout" TSO Kermit is from the other side: typing a carriage
return to the local Kermit causing it to retransmit its last packet,
or an automatic timeout as provided by most other Kermits.
The File System under MVS
=========================
The features of the TSO file system of greatest interest to Kermit
users are the format of file specifications and the concept of records.
File Specifications
-------------------
The MVS/TSO file specification is in the form
a) sequential files:
'USERID.FILENAME.FILETYPE'
or NAME.FILETYPE (short form)
a) partitioned files (PDS):
'USERID.FILENAME.FILETYPE(MEMBER)'
or NAME.FILETYPE(MEMBER) (short form)
FILENAME, FILETYPE and MEMBER are at most 8 characters in length each.
The name field is the primary identifier for the file. The type is an
an indicator which, by convention, tells what kind of file we have. For
instance TEST.FORT is the source of a FORTRAN program named TEST. LOAD
is the normal suffix for executable programs. MVS/TSO considers the
FILETYPE parameter optional.
The USERID parameter is the normal userid under which the user logs on
to MVS/TSO. If USERID is omitted from a file specification when sending,
the short form of the file specification is used (that means, the file
is cataloged under the userid of the KERMIT user).
To provide compatibility with most other operating systems, Kermit-TSO
sends only the FILENAME and FILETYPE; for members of a partitioned data-
set, the MEMBERNAME and FILETYPE are sent.
The FILENAME, FILETYPE and MEMBER may contain, in any order, uppercase
letters, digits, and the special characters "$" (dollar sign),
"@" (at sign) and "#" (hash).
File Formats
------------
Several differences exist between MVS/TSO files and those of most other
operating systems. One distinction is that MVS encodes its data using
the EBCDIC character set. The operating system, MVS, translates all
incoming characters from ASCII to EBCDIC. Kermit-TSO then translates the
data it reads back to ASCII (characters not representable in ASCII are
replaced by a null). This is done in order to correctly calculate the
checksum, the method used to guarantee error-free transfer. When
Kermit-TSO sends packets, it converts all data back to EBCDIC. Note that
the translate tables used by Kermit must correspond to the ones used by
the system (MVS/VTAM).
Another difference is that MVS/TSO stores files as records rather than
byte character streams. MVS/TSO Kermit has to worry about assembling
incoming data packets into records and appending carriage return
linefeed to outgoing records.
Program Operation
=================
Kermit-TSO can be invoked at the command line or from a CLIST. Invoke
the program under TSO by typing "KERMIT". When you see the command's
prompt,
KERMIT-TSO>
you may type Kermit commands repeatedly until you are ready to exit the
program, for example:
Welcome to KERMIT under MVS/XA-TSO V2.3
KERMIT-TSO> send foo*.fort
KERMIT-TSO> receive test.spss
KERMIT-TSO> exit
End of Kermit
Kermit-TSO Commands
===================
Here's a brief summary of all TSO KERMIT commands:
DELETE a specific file.
DIR shows user directory.
DISK space occupied by user.
DO execute Kermit commands from a profile member
END stop Kermit-TSO.
EXIT from Kermit-TSO.
FINISH finish server-mode of the micro
HELP about Kermit-TSO.
LOGOUT from Kermit-TSO and system.
MEMBERS displays memberlist of a PDS.
QUIT from Kermit-TSO.
RECEIVE files from other Kermit.
SEND files to other Kermit.
SERVER mode of remote operation.
SET various parameters.
SHOW Kermit settings.
STATUS same as SHOW.
TAKE execute Kermit commands from a file
TSO executes a TSO command.
TYPE a specific file.
WHO is logged on.
Diagramm with KERMIT commands and syntax:
KERMIT ---------------------------------------------------------------------+
| |
|-- DElete --- <local-filespec> -------------------------------------+
| |
|-- DIRectory -------------------------------------------------------+
| |-- <userid> ------------------------------------------+
| |
|-- DISk ------------------------------------------------------------+
| |
|-- DO ------- <membername> -----------------------------------------+
| |
|-- FInish ----------------------------------------------------------+
| |
|-- Help ------------------------------------------------------------+
| |
|-- LOGout ----------------------------------------------------------+
| |
|-- MEmbers -- <local-filespec> -------------------------------------+
| |
|-- QUit or EXit or ENd ---------------------------------------------+
| |
|-- RECeive ---------------------------------------------------------+
| |------------------- <local-filespec> -----------------+
| |
|-- SENd <local-filespec> -------------------------------------------+
| |----<as> ---------- <local-filespec> -----------------+
| |
|-- SERver ----------------------------------------------------------+
| |
|-- SET -------------------------------------------------------------+
| |-- <DEbug> ------- <ON | OR> -------------------------+
| |-- <TExtmode> ---- <ON | OFF> ------------------------+
| |-- <REcfm> ------- <FB | VB> -------------------------+
| |-- <INcomplete> -- <KEEP | DELETE>--------------------+
| | |
| |-- <CHecktype> ---| |
| |-- <EOLchar> -----| |
| |-- <DElay> -------|-- <decimal number> ---------------+
| |-- <PACketsize> --| |
| |-- <SOHchar> -----| |
| | |
| |-- <CNtrlquote> --| |
| |-- <BIt8quote> ---|-- <EBCDIC Char> ------------------+
| |-- <Repchar> -----| |
| | |
| |-- <ATOE> --------| |
| |-- <ETOA> --------|-- <n1> -- <n2> -------------------+
| |
|-- STatus ----------------------------------------------------------+
| |
|-- TAke ----- <local-filespec> -------------------------------------+
| |
|-- TYpe ----- <local-filespec> -------------------------------------+
| |
|-- VErsion ---------------------------------------------------------+
| |
|-- WHo -------------------------------------------------------------+->
THE DELETE COMMAND
Syntax: DELETE filespec
The DELETE command causes a file to be deleted from the catalog of the
user (actually, no wildcards in the filespec are allowed).
THE DIR COMMAND
Syntax: DIR [userid]
The DIR command causes a list of all cataloged files of a specific user
to be displayed at the screen.
THE DISK COMMAND
Syntax: DISK
The DISK command displays the actual size of disk-space occupied by
the user.
THE DO COMMAND
Syntax: DO membername
Execute Kermit commands from the file KERMIT.PROFILE, where membername
should be an existing member. The command file should not include
other DO or TAKE commands!
THE END, EXIT and QUIT COMMAND
Syntax: END or EXIT or QUIT
These commands stop the Kermit-TSO program, the user returns back to
the TSO prompt 'READY' to proceed work.
THE FINISH COMMAND
Syntax: FINISH
The FINISH command sends a FINISH-packet to the server of the micro.
This command has only an effect if used from within a startup-file.
THE LOGOUT COMMAND
Syntax: LOGOUT
The LOGOUT command stops the Kermit-TSO program. Additionnaly the user
is logged off from the host.
THE MEMBERS COMMAND
Syntax: MEMBERS filespec
The MEMBERS command displays the memberlist of a partitionned file.
THE RECEIVE COMMAND
Syntax: RECEIVE [filespec]
The RECEIVE command tells Kermit-TSO to receive a file or file group
from the other system. You should then issue a SEND command to the
remote Kermit.
If the optional filespec is not included, Kermit-TSO will use the
name(s) provided by the other Kermit. If that name is not a legal TSO
file name, Kermit-TSO will try to write the incoming data to the file
KERMIT.TEMP.
If the optional filespec is provided, but more than one file arrives,
the first file will be stored under the given filespec, and the
remainder will be stored under their own names (sent by the other
Kermit).
When receiving files, any record longer than the logical record length
will be split up to as many records as necessary.
Actually the following two record formats are supported:
1) Fixed format records, with a record length of 80. This format is
used for language sources and OS job control.
2) Variable records, with a record length of 255 bytes. This format
is the default, and is used for normal text files.
If an error occurs during the file transfer, as much of the file as
was received is saved. If the sending of a file is cancelled by the
user of the remote system, Kermit-TSO will discard whatever had arrived.
If the incoming file has the same name as a file that already exists,
Kermit-TSO will change the incoming name so as not to obliterate the
pre-existing file. It attempts to rename the file by replacing the
last character of the FILENAME or MEMBER (for PDS files) with the
next-following character in the alphabetical order. It continues in this
manner, until a filename for a non-existant file is found.
THE SEND COMMAND
Syntax: SEND filespec [[AS] local-filespec]
The SEND command causes a file or file group to be sent from the TSO
system to the Kermit on the remote system.
In filespec you may put ONE wildcard '*' anywhere in the filename, file-
type or membername if present. Do not put a wildcard in the userid.
Although the file transfer cannot be cancelled from the TSO side,
Kermit-TSO is capable of responding to "cancel file" or "cancel batch"
signals from the local Kermit; these are typically entered by typing
Control-X and Control-Z respectively.
THE SERVER COMMAND
Kermit-TSO is capable of acting as a server. The user connects to the
TSO system once to set various options and to start the server. From
then on, he need not connect to the TSO system again. The current
version of Kermit-TSO can send files (the user on the other end types
the GET command, using the TSO filename conventions), receive files
(the user types SEND), several advanced server functions as user
directory, typing or deleting files and other, and terminate by either
returning to TSO (user types FINISH) or logging the user out
(user types BYE).
To put Kermit-TSO into server mode, first issue any desired SET command
to select various options and then type the SERVER command. Kermit-TSO
will await all further instructions from the user Kermit on the other
end of the connection. For example:
KERMIT-TSO> set debug on
KERMIT-TSO> server
THE SET COMMAND
Syntax: SET parameter value
Establish or modify various parameters for file transfer. You can
examine their values with the SHOW command.
The following SET commands are available in Kermit-TSO:
ATOE Modify ASCII -> EBCDIC translation table
BIT8-QUOTE Character for 8th bit quoting
CHECKTYPE Type of block check to be used
CNTRL-QUOTE Character for control character quoting
DEBUG Log packets sent and received during file transfer
DELAY Delay until first SEND INIT packet is sent
EOLCHAR Packet terminator
ETOA Modify EBCDIC -> ASCII translation table
INCOMPLETE Disposition of file for aborted transfer
PACKETSIZE Maximum receive packet size
RECFM Record format for incoming files
REPEATCHAR Character for compression indication
SOHCHAR Start of Packet character
TEXTMODE Translation for text files
SET ATOE
Syntax: SET ATOE n1 n2
This command allows you to modify the ASCII -> EBCDIC translation table
which is used to determine the resulting character and checksum on the
micro side. The numbers n1 and n2 should lie in the range 0..255.
SET BIT8-QUOTE
Syntax: SET BIT8-QUOTE x
This command allows you to modify the character, which is used for
8th bit quoting. Initially this character is set to '&'. Running in
server mode, Kermit-TSO uses the 8th-bit quoting character of the micro.
SET CHECKTYPE
Syntax: SET CHECKTYPE n
This command allows you to specify the block check type to be used for
ensuring a safe tranfer of the data. The allowed types are:
1 - single character checksum, 2 - two char checksum
or 3 - three char CRC.
SET CNTRL-QUOTE
SYNTAX: SET CNTRL-QUOTE x
Use the indicated printable character for prefixing (quoting) control
characters and other prefix characters. The only reason to change
this would be for sending a very long file that contains very many "#"
characters (the normal control prefix) as data. It must be a single
character in the range: 33-62, 96, 123-126 (decimal).
SET DEBUG
Syntax: SET DEBUG ON / OFF
ON Keep a journal of all packets sent and received in the file
KERMIT.DEBUG. If the file already exists, it is overwritten.
OFF Stop logging the packets.
SET DELAY
Syntax: SET DELAY nn
This command allows you to modify the delay time (in seconds), between
issuing the SEND command on TSO side, and when the first 'SEND-INIT'
packet. 'nn' must be between 5 and 60 (decimal); the default is 6.
SET EOLCHAR
Syntax: SET EOLCHAR nn
If the remote system needs packets to be terminated by anything other
than carriage return, specify the decimal value of the desired ASCII
character. 'nn' must be between 0 and 18 (decimal).
SET ETOA
Syntax: SET ETOA n1 n2
This command allows you to modify the ASCII -> EBCDIC translation table
which is used to determine the resulting character and checksum on the
micro side. The numbers n1 and n2 should lie in the range 0..255.
SET INCOMPLETE
Syntax: SET INCOMPLETE KEEP / DELETE
If the remote system aborts a filetransfer the INCOMPLETE options speci-
fies what should be done with the incomplete file: whether it is kept
or deleted.
SET PACKETSIZE
Syntax: SET PACKETSIZE nn
Use the specified number as the maximum length for incoming packets.
The valid range is 26-94-1000, where 94 is the default. Packets with
a size of greater than 94 are packets according to the extended length
protocol.
SET RECFM
Syntax: SET RECFM FB / VB
Set the record format to use for incoming files. Valid options are "FB"
for fixed format (as used for job control files) or "VB" for variable
format (as used for text or data files). The default is variable.
SET REPEATCHAR
Syntax: SET REPEATCHAR x
This command allows you to modify the character, which is used for
character compression on the micro side. Initially this character is
set to '~' (tilde). Running in server mode, Kermit-TSO uses the
repeat character of the micro.
SET SOHCHAR
Syntax: SET SOHCHAR nn
If the normal start-of-packet character <Ctrl-A> should not get through
the communications line, you may change this character to any other
suitable character. Specify the decimal value of the desired ASCII
character. 'nn' must be between 0 and 18 (decimal).
SET TEXTMODE
Syntax: SET TEXTMODE ON / OFF
ON Tells TSO Kermit that the file is plain text. ASCII-to-EBCDIC and
EBCDIC-to-ASCII translation is performed on the data. Carriage
return-linefeed are appended to outgoing records and are used to
determine the end of incoming records.
OFF Tells TSO Kermit to treat each character as a string of bits and
not to perform translation on the data. Also, no carriage-return
is added to the end of outgoing records.
THE SHOW COMMAND
Syntax: SHOW
Use to display the values of all parameters that can be changed with
the SET command.
THE STATUS COMMAND
Syntax: STATUS
Returns the status of the previous command. The response will either
display the message "Kermit completed successfully", or the last error
encountered.
THE TAKE COMMAND
Syntax: TAKE filespec
Execute Kermit commands from the specified file, where filespec has
the normal TSO filename conventions. The command file should not
include other TAKE or DO commands.
THE TSO COMMAND
Syntax: TSO commandstring
Although Kermit-TSO does provide only few commands for managing local
files (list directory, type and delete files), it is possible to
interact with the operating system. You can issue any TSO command.
At this time, though, you cannot run another program or clist from
within Kermit-TSO.
THE TYPE COMMAND
Syntax: TYPE filespec
The TYPE command causes a file or file group to be sent from the TSO
system to the Kermit on the remote system and typed there on the screen.
(actually no wildcards in the filespec are allowed )
Although the file transfer cannot be cancelled from the TSO side,
Kermit-TSO is capable of responding to "cancel file" or "cancel batch"
signals from the local Kermit; these are typically entered by typing
Control-X and Control-Z respectively.
THE WHO COMMAND
Syntax: WHO
The WHO command displays a list of the actual users logged on at the
host system.
The KERMIT startup file
=======================
When starting KERMIT, the file called 'KERMIT.SETUP' is executed if
it exists. The KERMIT clist checks for the presence of the command
file. If he finds it, he passes an additional argument to the program,
which causes KERMIT to execute all commands in this startup file.
When sending more than one file from within the startup-file, you have
to set the micro-Kermit into server mode.
Example:
+-KERMIT.SETUP--------------------+
| SEND FILE1.TEXT |
| SEND KERMIT.INSTALL(*) |
| FINISH |
+---------------------------------+
Before Connecting to the Mainframe
==================================
When connecting to the TSO system as a TTY device ("line at a time"
mode) several flags must first be set on the micro version of Kermit.
You should set the LOCAL-ECHO flag to OFF (this is used to indicate
full-duplex).
HANDSHAKE should be set to XON and FLOW-CONTROL should be set to NONE.
The parity should be set according to the system's specifications.
Set the baud rate to correspond to the line speed and set the parity
as needed for the used line.