Columbia Kermit/kermit.zip/cmsoriginal/cmsv2doc.txt

Text File | 2020-01-01 | 27KB | 674 lines

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.