IBM VM/CMS KERMIT (Chapter from Kermit User Guide) Page 106
8. IBM VM/CMS KERMIT
Program: Daphne Tzoar, Columbia University; contributions from Bob Shields
(U. of Maryland), Victor Lee (Queens U.), Gary Bjerke (U. of Texas
at Austin), Greg Small (UC Berkeley)
Language: CMS Assembler
Documentation:
Daphne Tzoar, Columbia University
Version: 2.01
Date: May 1985
CMS Kermit Capabilities At A Glance:
Local operation: No
Remote operation: Yes
Transfers text files: Yes
Transfers binary files: Yes (fixed format)
Wildcard send: Yes
^X/^Y interruption: Yes
Filename collision avoidance: Yes
Can time out: No
8th-bit prefixing: Yes
Repeat count prefixing: Yes
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: No
Advanced server functions: No
Advanced commands for servers: No
Local file management: Yes
Handle Attribute Packets: No
Command/init files: Yes
Command macros: No
Kermit-CMS is a program that implements the KERMIT file transfer protocol for
IBM 370-series mainframes (System/370, 303x, 43xx, 308x, etc.) under the VM/CMS
operating system. It is written in IBM 370 assembly language. This program
runs only over ASCII (asynchronous) lines attached to a 3705-style front end or
a Series/1 running the Yale ASCII Terminal Communication System. The program
should also work on the IBM 7171 ASCII Device Control Unit and the 4994, al-
though this has not been verified as of this writing. For more details on
this, see the section SET SERIES1.
These systems have several peculiarities that users should be aware of. 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 trans-
mitting the next character. It is up to the user to tell the other Kermit that
it is talking to an IBM mainframe.
IBM VM/CMS KERMIT Page 107
Also, a program running under VM/CMS is unable to interrupt a read on its
"console". This means that the CMS version of Kermit cannot timeout. The only
way to "timeout" CMS 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.
8.1. The VM/CMS File System
The features of the CMS file system of greatest interest to Kermit users are
the format of file specifications and the concept of records.
8.1.1. File Specifications
The VM/CMS file specification is in the form
FILENAME FILETYPE FILEMODE
(often abbreviated FN FT FM). FILENAME and FILETYPE are at most 8 characters
in length each. The name field is the primary identifier for the file. The
type is an indicator which, by convention, tells what kind of file we have.
For instance TEST FORTRAN is the source of a FORTRAN program named TEST.
MODULE is the normal suffix for executable programs. Although some operating
systems consider the FILETYPE optional, VM/CMS requires a valid type. There-
fore, Kermit-CMS supplies a default type of "X" if one is not provided by the
remote system.
The FILEMODE, which consists of a letter and a number, is similar to a device
specification on microcomputer systems: FN FT FM would translate to FM:FN.FT in
CP/M or MS-DOS. If FILEMODE is omitted from a file specification when sending,
a FM of "*" is used. In this case, the users disks are scanned according to
the search order and the first occurrence of the file is the one that is sent.
If FILEMODE is omitted from a file spec when receiving, a default of "A1" is
used.
To provide compatibility with most other operating systems, Kermit-CMS sends
only the FILENAME and FILETYPE. It also converts the intervening blank to a
period.
The FN and FT may contain, in any order, uppercase letters, digits, and the
special characters "$" (dollar sign), "#" (pound sign), "@" (at sign), "+"
(plus), "-" (dash), ":" (colon), and "_" (underscore). Other characters may be
not be included. If an invalid character is found in the FN or FT field, it is
replaced by the letter "X".
VM/CMS allows a group of files to be specified in a single file specification
by including the special "wildcard" characters, "*" and "%". A "*" matches any
string of characters from the current position to the end of the field, includ-
ing no characters at all; a "%" matches any single character. Here are some
examples:
* COBOL A
All files of type COBOL (all COBOL source files) on the A disk.
F* * All files whose names start with F.
IBM VM/CMS KERMIT Page 108
% * B All files on the B disk whose FN is exactly one character long.
8.1.2. File Formats
Several differences exist between VM/CMS files and those of most other operat-
ing systems. One distinction is that CMS encodes its data using the EBCDIC
character set. The operating system, VM, translates all incoming characters
from ASCII to EBCDIC. Kermit-CMS then translates the data it reads back to AS-
CII (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-CMS 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 (VM). The ASCII to EBCDIC translations can be
found in the Appendix.
Another difference is that VM/CMS stores files as records rather than byte
streams. VM/CMS Kermit has to worry about assembling incoming data packets
into records and appending carriage return-linefeed to outgoing records.
8.2. Program Operation
Kermit-CMS can be invoked at the command line or from an exec. Commands con-
sist of one or more fields, separated by spaces. Each field must be eight
characters or less. Fields longer than the maximum length are truncated.
Upon initial startup, the program looks for two special initialization files,
SYSTEM KERMINI and (USERID) KERMINI (that is, the userid of the person running
CMS-Kermit.) These files can be placed on any disk. The purpose of these
files is to allow Kermit to be customized for a particular system and for a
user's specific settings without changing the source code. The file SYSTEM
KERMINI should be placed on a publicly accessible disk by a systems programmer.
The file would contain commands that all users would need to issue in order for
Kermit to run on the system, such as commands to modify the ASCII-to-EBCDIC and
EBCDIC-to-ASCII tables used by Kermit-CMS. The file (USERID) KERMINI would
contain commands that the user generally issues every time Kermit is run.
Kermit-CMS executes any commands found in these files as though they were typed
at the terminal. Here is a sample init file:
* Asterisk in column one is a comment.
set debug on
set warning on
set block 3
Three CP SET parameters MSG, IMSG and WNG are always set OFF during the actual
file transfer (and restored afterwards) to prevent CP from interrupting any I/O
in progress.
IBM VM/CMS KERMIT Page 109
Interactive Operation:
To run Kermit-CMS interactively, invoke the program from CMS by typing
"KERMIT". When you see the command's prompt,
KERMIT-CMS>.
you may type Kermit commands repeatedly until you are ready to exit the
program, for example:
.KERMIT
Kermit CMS Version 2.01
Enter ? for a list of valid commands
KERMIT-CMS>.send foo *
Files with fn FOO are sent
KERMIT-CMS>.receive test spss
File is received and called TEST SPSS A1
KERMIT-CMS>.exit
During interactive mode, you may use the help ("?") feature while typing
Kermit-CMS commands. A question mark typed at almost any point in a command,
followed by a carriage return, produces a brief description of what is expected
or possible at that point.
Command Line Invocation:
Kermit-CMS may also be invoked with command line arguments from CMS. For in-
stance:
.KERMIT send test fortran
or
.KERMIT set debug on # set file binary # server
Kermit will exit and return to CMS after completing the specified command or
commands. Note that several commands may be given on the command line as long
as they are separated by the linend character, which is pound sign in this
case. The command line may contain up to 130 characters.
Exec Operation:
Like other CMS programs, Kermit-CMS may be invoked from a CMS EXEC. Kermit
will not run under CMSBATCH or disconnected since the user does not actually
have a console. Commands can be passed using TAKE files and/or command line
arguments. For example, to start up Kermit-CMS and have it act as a server,
include the line:
IBM VM/CMS KERMIT Page 110
KERMIT server
To pass more than one command, they must be stacked in the order in which they
are to be executed. To start up a Kermit-CMS server with a three character
CRC, include:
&STACK set block 3
&STACK server
KERMIT
Prompts and messages will still be displayed on the screen.
8.3. Kermit-CMS Commands
Here's a brief summary of CMS Kermit commands:
CMS executes a CMS command.
CP executes a CP command.
EXIT from Kermit-CMS.
HELP about Kermit-CMS.
QUIT from Kermit-CMS
RECEIVE files from other Kermit.
SEND files to other Kermit.
SERVER mode of remote operation.
SET various parameters.
SHOW various parameters.
STATUS inquiry.
TAKE commands from file.
TDUMP dumps the contents of a particular table.
The remainder of this section concentrates on the commands that have special
form or meaning for CMS Kermit.
THE SEND COMMAND
Syntax: SEND filespec
The SEND command causes a file or file group to be sent from the CMS system to
the Kermit on the remote system. filespec takes the form:
filename filetype [filemode]
filespec may contain the wildcard characters "*" or "%". If filespec contains
wildcard characters then all matching files will be sent. If, however, a file
exists by the same name on more than one disk, only the first one CMS Kermit
encounters, according to the disk search order, is sent.
Although the file transfer cannot be cancelled from the CMS side, Kermit-CMS 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 respec-
tively.
IBM VM/CMS KERMIT Page 111
THE RECEIVE COMMAND
Syntax: RECEIVE [filespec]
The RECEIVE command tells Kermit-CMS to receive a file or file group from the
other system. You should then issue a SEND command to the remote Kermit.
The format of the filespec is:
filename filetype [filemode]
If the optional filespec is not included, Kermit-CMS will use the name(s)
provided by the other Kermit. If that name is not a legal CMS file name,
Kermit-CMS will delete excessive characters from it, and will change illegal
characters to the letter X.
Use the file specification to indicate that the incoming file should be stored
under a different name. The filespec may include a filemode to designate the
destination disk. If none is provided, the file will be saved with fm A1. If
you want to use the same name but a different filemode, specify = = FM.
Wildcards may not be used in any field.
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 on the A disk. If, however, = = FM is used, all files
will be placed onto the specified disk.
When receiving files, if the record format is fixed, any record longer than the
logical record length will be split up to as many records as necessary. If the
record format is variable, the record length can be as high as 64K. For send-
ing files, the maximum record length is 64K. See the SET LRECL and SET RECFM
commands.
If an error occurs during the file transfer, as much of the file as was
received is saved on disk. If the sending of a file is cancelled by the user
of the remote system, Kermit-CMS will discard whatever had arrived.
If the incoming file has the same name as a file that already exists, and WARN-
ING is OFF, the original file will be overwritten. If WARNING is set ON,
Kermit-CMS will change the incoming name so as not to obliterate the pre-exist-
ing file. It attempts to rename the file by replacing the first character with
a dollar sign ($). If a file by that name exists, it also replaces the second
character with a dollar sign. It continues in this manner for all characters
of the filename and filetype. If the file cannot be renamed, the transfer
fails.
THE TAKE COMMAND
Syntax: TAKE filespec
Execute Kermit commands from the specified file, where filespec has the format
fn ft [fm]. The command file may include TAKE commands.
IBM VM/CMS KERMIT Page 112
THE SERVER COMMAND
Kermit-CMS is capable of acting as a server. The user connects to the CMS sys-
tem once to set various options and to start the server. From then on, he need
not connect to the CMS system again. The current version of Kermit-CMS can
send files (the user on the other end types the GET command, using either a
space or a period as the delimiter between filename, filetype, and filemode),
receive files (the user types SEND), and terminate by either returning to CMS
(user types FINISH) or logging the user out (user types BYE).
To put Kermit-CMS into server mode, first issue any desired SET commands to
select various options and then type the SERVER command. Kermit-CMS will await
all further instructions from the user Kermit on the other end of the connec-
tion. For example:
KERMIT-CMS>.set warning on
KERMIT-CMS>.set debug on
KERMIT-CMS>.set block 3
KERMIT-CMS>.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-CMS:
ATOE Modify ASCII-to-EBCDIC table used by Kermit-CMS
BLOCK Level of error checking for file transfer
DEBUG Log packets sent and received during file transfer
END-OF-LINE Packet terminator
ETOA Modify EBCDIC-to-ASCII table used by Kermit-CMS
FILE Type of incoming or outgoing file
LRECL Logical Record length for incoming file
PACKET-SIZE Maximum receive packet size
QUOTE Use to quote outgoing control characters
RECFM Record format for incoming files
SERIES1 Indicate if coming in via a Series/1
WARNING Specify how to handle filename collisions
SET ATOE
Syntax: SET ATOE num1 num2
This command allows you to modify the ASCII-to-EBCDIC translate table used by
Kermit-CMS to conform to your system. Specify the offset of the ASCII value
within the table and the new value for that location. Both num1 and num2
should be between 0 and 255 (decimal). Note that the table is twice as long as
necessary because the translate instruction expects a table that contains 256
characters.
IBM VM/CMS KERMIT Page 113
SET BLOCK
SYNTAX: SET BLOCK number
Determine the type of block check used during file transfer. Valid options for
number are: 1 (for a one character checksum), 2 (for a two character checksum)
and 3 (for a three character CRC).
SET DEBUG
Syntax: SET DEBUG ON or OFF
ON Keep a journal of all packets sent and received in the file KER LOG A1.
If the file already exists, it is overwritten.
OFF Stop logging the packets.
SET END-OF-LINE
Syntax: SET END-OF-LINE number
If the remote system needs packets to be terminated by anything other than car-
riage return, specify the decimal value of the desired ASCII character. number
must be between 0 and 31 (decimal).
SET ETOA
Syntax: SET ETOA num1 num2
This command allows you to modify the EBCDIC-to-ASCII translate table used by
Kermit-CMS to conform to your system. Specify the offset of the EBCDIC value
within the table and the new ASCII value for that location. Both num1 and num2
should be between 0 and 255 (decimal).
SET FILE
Syntax: SET FILE BINARY or TEXT
BINARY Tells CMS 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. Incoming bytes are added to the end of
the current record which is written out when the specified LRECL is
reached.
TEXT Tells CMS 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 deter-
mine the end of incoming records.
IBM VM/CMS KERMIT Page 114
SET LRECL
Syntax: SET LRECL number
Set the logical record length for incoming files to a number from 1 to 65536
(64K). This variable is used only for fixed format files. The default is 80.
SET PACKET-SIZE
Syntax: SET PACKET-SIZE number
Use the specified number as the maximum length for incoming packets. The valid
range is 26-94, where 94 is the default.
SET QUOTE
Syntax: SET QUOTE char
Use the indicated printable character for prefixing (quoting) control charac-
ters 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, or 123-126 (decimal).
SET RECFM
Syntax: SET RECFM option
Set the record format to use for incoming files. Valid options are "F" for
fixed format or "V" for variable format. The default is variable.
SET SERIES1
Syntax: SET SERIES1 ON or OFF
Kermit-CMS automatically determines whether you are connected via a Series/1
emulation controller or a TTY line. This command is provided though so you can
override Kermit-CMS. When you SET SERIES1 ON, Kermit disables the 3270
protocol conversion function by putting the Series/1 into "transparent mode";
this allows Kermit packets to pass through the Series/1 intact.
SET WARNING
Syntax: SET WARNING ON or OFF
ON If an incoming file has the same name as an existing file on the
specified disk, Kermit will attempt to rename the incoming file so as
not to destroy (overwrite) the pre-existing one.
OFF Upon a filename collision, the existing file will be replaced by the
incoming file.
IBM VM/CMS KERMIT Page 115
THE SHOW COMMAND
Syntax: SHOW option
Use to display the values of all parameters that can be changed with the SET
command, except for ATOE and ETOA (see the TDUMP command). option can be a
particular parameter or the keyword "ALL".
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 TDUMP COMMAND
Syntax: TDUMP table-name
Display the contents of table-name since it can be modified using the SET com-
mand. The ATOE and ETOA tables can presently be 'dumped'.
CP AND CMS COMMANDS
Syntax: CP text of command
CMS text of command
Although Kermit-CMS does not provide explicit commands for managing local files
or interacting with the operating system, it is possible to do so. You can is-
sue any CP or CMS command, though each word will be truncated to eight charac-
ters. You can list, type, rename or delete files, send messages and so on. At
this time, though, you cannot run another program from Kermit-CMS.
8.4. Before Connecting to the Mainframe
When connecting to the CMS 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 ON (this is used to indicate half-duplex). This is the
norm but not true in every case; if each character appears twice, set the
LOCAL-ECHO flag OFF. HANDSHAKE should be set to XON and FLOW-CONTROL should be
set to NONE. The parity should be set according to the system's specifica-
tions. On some micro versions of Kermit, all of the above is done in one step
using the DO IBM macro (or SET IBM ON). Set the baud rate to correspond to the
line speed.
When connecting to the CMS system through the Series/1 terminal emulation con-
troller ("full-screen" mode), certain flags must 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 OFF and FLOW-CONTROL should be set to
XON/XOFF. For most systems, the PARITY should be set to EVEN. Set the baud
rate to correspond to the line speed. Immediately after issuing a SEND,
RECEIVE or SERVER command to Kermit-CMS, the screen will be cleared. This is
IBM VM/CMS KERMIT Page 116
to make sure the terminal is not stuck in a MORE or HOLDING state before pack-
ets are sent via the full-screen I/O operation. After the file transfer is
complete, and you re-connect to Kermit-CMS, you should enter the Series/1
"Master Reset" sequence (probably "CTRL-G") so that the screen is refreshed.
8.5. How to build an executable version of Kermit-CMS
Kermit-CMS is composed of three assembly language source files that are as-
sembled separately and then linked together. They are: KERMIT, NEXTFST, and
WILD. To create a runnable version:
1. GLOBAL the necessary MACLIBs. For SP, the MACLIBs used are DMSSP,
CMSLIB and TSOMAC.
2. Make sure the source files are named as listed above and are saved
on disk in fixed format with a logical record length of 80.
3. Assemble the three source files.
4. Load the files into memory via: LOAD KERMIT
5. Create a runnable version called KERMIT MODULE via: GENMOD KERMIT
6. If your site's ASCII/EBCDIC translation table does not conform to
the one listed in the appendix (which in turn conforms to the one
given in the IBM System/370 Reference Summary), then enter the ap-
propriate SET ATOE/ETOA commands in the SYSTEM KERMINI file. Note
that if the ASCII/EBCDIC translation is not invertible, Kermit will
not and cannot work.
To run CMS Kermit, simply type "KERMIT" to the CMS system prompt.
8.6. What's New
Below is a list of the more important additions in Version 2.01 of CMS Kermit:
1. Add prefixing of the "8th bit". This allows CMS Kermit to send or
receive fixed format binary data, such as microcomputer binary
files.
2. The maximum record length allowed has been increased to 64K for both
incoming and outgoing files.
3. Repeat count prefixing has been added to speed up transmission. In
addition, Kermit-CMS now packs as much data as possible into an out-
going packet rather than one packet per record (it makes a big
difference).
4. Support for two character checksum and three character CRC.
5. If filetype is not supplied by the remote Kermit, use a default of
"X" rather than failing. Also allow the option to rename an incom-
ing file upon filename collision.
IBM VM/CMS KERMIT Page 117
6. Add debugging mode to log packets and to acknowledge the attention
if the user types a BREAK. Add a SHOW ALL command.
7. Allow input to command parser from command line. Multiple commands
should be separated by the linend character. After execution of
these commands, Kermit returns control to CMS.
8. Add support for Series/1 front end.
9. Add server support.
10. Upon startup, read commands from two init files: SYSTEM KERMINI and
(USERID) KERMINI (that is the userid of the person running Kermit).
Lines with an asterisk as the first character are comments. Add the
TAKE command. The LRECL for these files must be 130 or less.
11. Implement skip file or file group when sending or receiving (in this
case, discard incoming file).
12. Allow system manager to change ASCII/EBCDIC translation tables to
conform to the various specifications of different systems. Also,
bypass user translate tables when sending and receiving data.
8.7. What's Missing
Work on Kermit-CMS will continue. Features that need to be improved or added
include:
- Allow timeouts so CMS Kermit does not wait forever if a packet does
not arrive in a timely fashion.
- Allow any binary file to be sent and received properly, not only
fixed format binary files.
- Better keyword parsing, which is rather crude at this time.
- Support of the more advanced server functions.
- Addition of a RUN command.
- Ability to SET LINE, so that Kermit-CMS can be used as a local Ker-
mit, connecting to a remote host over another communication port.