1
   This dataset is named 'STORET.HELP.info.lib(kermit)'
   and is paraphrased from another, more general help file called
   'JUSD.KERMIT.DATA(TSODOC)' which is also kept on-line.


  ****   EXCEPTIONS
  **
  **
  **                     SDC User Support
  **                     (800)424-9067
  **
  **
  **
  **   Item 1 -
  **   --------
  **      We have found that use of LRECL(80) on the TSO SERVER
  **   command results in transmission of extraneous lines
  **   from the PC to the NCC HOST whenever a data line in the
  **   PC file contains a non-blank character in column 80.
  **      To avoid this, we are now recommending that you upload
  **   80-column card image data using SERVER operands as follows:
  **
  **     SERVER RECFM(VB) LRECL(255) BLKSIZE(6090) <enter>
  **
  **      These are the defaults, and issuing the SERVER command
  **   with no operands at all is just as good, and quicker.
  **
  **     SERVER <enter>
  **
  **      Remember that once TSO has been placed in SERVER mode,
  **   only the FIN command (from KERMIT-MS) can stop it.
  **
  **   Item 2 -
  **   --------
  **      The dataset which arrives at the STORET/TSO end will have
  **   attributes which are incompatible with STORET (and other)
  **   software, and must be converted to a FIXED BLOCKED dataset
  **   before use.  This is accomplished under STORET/TSO by
  **   issuing:
  **
  **     %FIXLEN   data-set-name   nn  <enter>
  **
  **   where
  **     data-set-name   is the name of the dataset which needs
  **                     to be "fixed",
  **                nn   is the required LRECL.  Use 88 for "nn"
  **                     when the data will be input to STORET
  **                     storage procedures, and 80 for other
  **                     intended uses, such as retrieval run-streams.
  **
  **   Item 3 -
  **   --------
  **      KERMIT-TSO cannot deal with files uploaded without a
  **   MS-DOS suffix.  The data-set-name assigned at the TSO
  **   library level ends up with invalid character sequences
  **   in it, and an error (unable to open dataset) results.
  **   If you create a PC file whose name has no suffix, just
  **   rename it using one of the generic three-character suffixes
  **   used in MS-DOS (like ".DAT").
  **
  **      For example, if you own a PC dataset named
  **
  **                  STORET
  **
  **      then you should enter (from the DOS prompt)
  **
  **           > rename a:storet a:storet.dat
  **
  **      before attempting to upload it to TSO via SEND.
  **
  ****  End of current exceptions

1

  1. Introduction
  -------------------

  KERMIT is an ASCII file transfer protocol designed for reliable
  transfer of text or binary files between two computers using ordinary
  serial phone lines.  All that is required is that each computer have a
  working version of KERMIT and a modem.  KERMIT includes error checking
  algorithms to ensure accurate transfer of files.

  KERMIT transfers data by encapsulating it in 'packets' with control
  information.  Packets include a synchronization marker, a packet
  number to allow detection of lost packets, a length indicator, and a
  'checksum' to allow verification of the data.  Lost or corrupt packets
  are detected, and retransmission is requested.  Duplicate packets are
  discarded.  In addition, special control packets allow cooperating
  KERMITs to connect and disconnect from each other, and to exchange
  various types of information.  Very few assumptions are made about the
  capabilities of either computer, so the KERMIT protocol can work
  between many different kinds of computer systems.

  KERMIT is not necessarily better than many other terminal-oriented
  file transfer protocols but it is FREE, it is well documented, and it
  has been implemented on a wide variety of microcomputers and
  mainframes.  KERMIT was designed at the Columbia University Center for
  Computing Activities in 1981-82.  KERMIT was presented to user group
  meetings and described in various publications.  As a result, some
  sites wrote their own implementations or adapted one of the Columbia
  versions to run on additional systems.  These new versions were sent
  back to Columbia so that they could share them with others.  In this
  way, KERMIT has grown to support about 50 different systems; it has
  been sent by Columbia to hundreds of sites in dozens of countries, and
  has reached hundreds or thousands more through various user groups and
  networks.

  KERMIT is free and available to all.  Columbia University charges a
  modest distribution fee for sites that request a magnetic tape.  Sites
  are free to redistribute KERMIT on their own terms, and are encouraged
  to do so, with the following stipulations : KERMIT should not be sold
  for profit; credit should be given where it is due; and new material
  should be sent back to Columbia so that they can maintain a definitive
  and comprehensive set of KERMIT implementations for further
  distribution.


  2. Environment
  ----------------

  KERMIT-TSO is designed to support the IBM 370-series mainframes (370,
  303x, 43xx, 308x, 309x, ...) using the MVS/TSO operating environment.
  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 line
  turnaround before transmitting the next character.

  The IBM system under MVS/TSO is unable to interrupt a read.  This
  means that the TSO version of Kermit cannot timeout.  The only way to
  "timeout" TSO Kermit is from the other side, ie, typing a carriage
  return to the micro's Kermit causing it to retransmit its last packet,
  or an automatic timeout as provided by the DEC 20 and Tektronix 4170
  versions of Kermit.

  MVS/TSO stores files as records rather than as byte streams.  TSO
  Kermit has to assemble incoming data packets into records and strip
  CRLFs from incoming lines.  Outgoing records must have trailing blanks
  removed and CRLFs appended.

  Please note that this document should be used in conjunction with the
  Kermit User's Guide, and assumes you have read the sections pertaining
  to the IBM/PC microcomputer.

  The relevant section of the Kermit User's Guide is found (in ready-
  to-print format) on the KERMIT disk distributed by STORET User
  Assistance.  If you do not have this disk, you can obtain a copy
  at no charge from STORET.


  3. Restrictions
  -----------------

   - You must be using an ASCII terminal to run KERMIT-TSO.
      KERMIT is a protocol for transferring files between ASCII devices.
      IBM 3270 communications protocol is NOT ASCII, and is NOT
      compatible with TSO KERMIT.
      Executing KERMIT from a 3270 session may cause your terminal (PC)
      to become inoperative, and unable to respond to the RESET or PA1
      keys.


  4. References
  ---------------


       KERMIT User Guide, Fifth Edition, July 1984, Columbia University
           Center for Computing Activities
       Da Cruz,F., and W. Catchings. "KERMIT: A File-Transfer Protocol
           for Universities, Part 1."  Byte Magazine, June, 1984, page
           255.
       Da Cruz,F., and W. Catchings. "KERMIT, Part 2."  Byte Magazine,
           July 1984, page 143.

1

  5. TSO Command Syntax and Options
  ----------------------------------


  ***************
  * SERVER MODE *
  ***************

  The easiest, and prefered, way to run TSO KERMIT is to put it into
  'server' mode.  The server mode (also available on the IBM PC version
  of KERMIT) simplifies the KERMIT file transfer considerably.  When
  KERMIT- TSO is in server mode it gets all of its instructions from the
  other KERMIT program, instead of from the local keyboard.  You do not
  type commands to a KERMIT server, you merely start it at the TSO end
  of the connection, and then type all further commands from the PC
  side.

  To invoke TSO KERMIT in server mode enter the following:

                 SERVER options

            where "options" can be any of the allowable options in the
                  options(keyword) syntax, for example:

                 ASCII(ON)
                 RECFM(FB)
                 LRECL(80)
                 BLOCK(3120)
                 XON(ON)

  Since the default SERVER options for RECFM, LRECL, and BLOCK are less
  than desirable, the following SERVER calls are recommended:


   for sending/receiving card images (records desired to have
   80 columns) which contain only printable keyboard characters,
   use:

      SERVER ASCII(ON) RECFM(FB) LRECL(80) BLOCK(3120) XON(ON)


   for sending/receiving STORET storage transactions (either
   stations or data, in any STORET format), where it is desirable
   to use a TSO record-length of 88 for ease in line-numbering,
   use:

      SERVER ASCII(ON) RECFM(FB) LRECL(88) BLOCK(3432) XON(ON)



   for sending/receiving BINARY and EBCDIC (GDDM) graphics files,
   which must contain binary/hexadecimal codes not to be printed,
   use:

      SERVER ASCII(OFF) RECFM(FB) LRECL(80) BLOCK(3120) XON(ON)

1

  ****************
  * COMMAND MODE *
  ****************

  As explained above, server mode is preferred, but if you must invoke
  TSO KERMIT in command mode, enter the following :

               KERMIT

  TSO will respond:

               KERMIT-TSO


  Once KERMIT has been called in command mode, the following commands
  are allowed:

          Send
          Receive
          Show
          Set
          Help
          Take
          Exit
          End
          Quit
          Push
          Debug




  SEND dataset name
                 Send the specified dataset from the IBM/TSO Host
                 to the attached PC.
                 In command mode, KERMIT-TSO will send only one file per
                 request, no wild-carding is allowed.  The dataset name
                 must be specified, KERMIT-TSO will NOT prompt for one.
                 Note, the TSO dataset must be cataloged.

  RECEIVE dataset name
                 Receive the file sent from the PC to the IBM/TSO Host.
                 The dataset name must be specified, KERMIT-TSO will NOT
                 prompt for one.  If the dataset is not a cataloged TSO
                 dataset, one will be cataloged.  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 automatically
                 overwrite the dataset, without asking, possibly
                 changing its RECFM, LRECL, or BLKSIZE attributes.

  SHOW           Displays the current value of variables that can be
                 changed via the SET command.

  SET parameter(value)
                 Set the parameter to the specified value.  KERMIT-TSO
                 uses parentheses to set values, not equals signs or
                 spaces as in other Kermit implementations.  Legal Set
                 parameters are:

               ASCII (ON | OFF)
                    Specifies that the file being sent or received
                    contains only legal ASCII characters.  ASCII is a
                    7-bit code, so legal ASCII characters must be in the
                    range from 1 - 127 decimal.  ASCII(ON) should be
                    used when exchanging text files.  It may also be
                    used to exchange ASCII graphics files.  ASCII(OFF)
                    should be used to transfer files containing binary
                    or EBCDIC graphics (GDDM) files.  The default is
                    ASCII(ON).

               RECFM (c)
                    Denotes the record format to be used when creating
                    the dataset.  Variable blocked (VB) is the default.
                    Indicate the desired record format by F, FB, V, VB,
                    etc.  Users are encouraged to use fixed block (FB)
                    whenever possible, other RECFM values have been
                    known to cause problems.

               LRECL (d)
                    Indicates the logical record length for creating the
                    dataset.  The default is set to 255, and the maximum
                    allowed is 255.  If the RECFM is V the value must
                    include the 4 bytes for the record descriptor word
                    (RDW).  Users are encouraged to use RECFM (FB),
                    LRECL(80), and BLOCK (3120) for text files.

               BLOCK (d)     or BLKSIZE (d)
                    Indicates the block size for creating the dataset.
                    The default is 6080 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 V then the BLOCKSIZE must be at least LRECL
                    + 4.  Users are encouraged to user RECFM (FB), LRECL
                    (80), and BLOCK (3120) for text files.

               NONUM | NUM | SNUM
                    Controls KERMIT-TSO's handling of line numbers on
                    text files.
                       NONUM means that no special line number
                             processing is used.
                       NUM indicates that line numbers should be added
                             to each line of files received from the
                             remote (PC) Kermit.
                       SNUM specifies that line numbers will be stripped
                             from files sent to the remote (PC) Kermit.

                    Note that the NONUM, NUM, and SNUM parameters are
                    mutually exclusive, ie, only one will be in effect.
                    The default is NONUM.

               RETRY (d)
                    Specifies the number of time that KERMIT-TSO will
                    retry a packet found to be in error.  The default is
                    10, which should be adequate for most users.  There
                    may be occasions, such as excessively noisy
                    communications lines, when a larger RETRY count
                    should be used.  Users are advised not to set this
                    count too high, since you may find it difficult to
                    abort a file transfer.

               QUOTE (c)
                    The quote character you wish to use in place of the
                    default (#), for quoting of control characters.  It
                    must be a single, printable character from among the
                    following: 33-62, 96, or 123-126 (decimal).  Users
                    are advised not to change the default.

               BINARY (d)
                    Specifies the character that you wish to use for
                    binary (8-bit quoting) file transfers.  The default
                    is &.  Users should not change this parameter.

               MARKER (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).  Users should not change
                    this parameter.

               MAXL (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.  Users
                    should not change this parameter.

               CHECK (d)
                    Specifies the type of checksum to be used in Kermit
                    packets.  A value of 1 indicates that a 1 byte (6-
                    bit) checksum will be used. A value of 2 indicates
                    that a 2 byte (12-bit checksum) should be used.  The
                    default is 1 and users should not change it.  Not
                    all Kermit implementations can generate or process
                    the alternate checksums.

               DELIMIT (CRLF | CR | LF)
                    Specifies the line delimiter to be used when KERMIT-
                    TSO is sending files to the remote (PC) Kermit.  The
                    default is CRLF and user should not change it.

               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 a file named 'prefix.logfile.text'.  The
                    default is DEBUG (OFF).  Users will seldom need to
                    enable DEBUG mode.

               PAUSE (d)
                    Allow the user to specify the length of time in
                    seconds that KERMIT-TSO will wait before issuing its
                    first packet when the user specified SEND.  This
                    will give the user time to escape back to the micro
                    KERMIT and issue the neccesary commands.  The
                    default is 9 seconds, and it is generally
                    satisfactory.

  HELP           Displays a message that lists the KERMIT-TSO commands,
                 and how to obtain more detailed Help information.  Like
                 most TSO commands KERMIT-TSO has significant online
                 HELP information available, organized by command name,
                 e.g.  HELP SEND, HELP SET, etc.

  TAKE ccc       Executes a series of commands from a member of YOUR
                 CLIST file, ie, 'prefix.clist(ccc)'.  This command is
                 similar to the IBM PC Kermit command.  It is useful for
                 setting up a standard KERMIT-TSO environment without
                 having to type in the individual commands.  TAKE
                 memebers could be created to set standard parameters
                 and values for sending ASCII files, for sending binary
                 files, for receiving ASCII files, etc.  Once these TAKE
                 members have been debugged and verified, they may be
                 easily be used in subsequent sessions, or by other
                 users.

  EXIT           from KERMIT-TSO, back to TSO.

  END            Same as EXIT.

  QUIT           Same as EXIT.

  PUSH           Allows users to submit TSO commands while in
                 KERMIT-TSO.  The sequence is as follows :

                   KERMIT-TSO> push
                   KERMIT-TSO> tso command ,eg, free ds(abcdef.xyz)
                   READY
                   KERMIT-TSO> alloc ds(abcdef.xyz) new like(old.file)
                   READY

  DEBUG          The DEBUG command closes the KERMIT-TSO logfile and
                 prints its contents.  Note the distinction between the
                 SET DEBUG and the DEBUG commands.  SET DEBUG (ON | OFF)
                 either enables or disables collection of debugging
                 information in the logfile.  The DEBUG command is used
                 to view the collected information.

1



  6. KERMIT-TSO Examples
  ----------------------




        TEXT file transfer  -  from IBM 3090 HOST under TSO to IBM PC.
     -----------------------------------------------------------------

  On the IBM PC, enter:
  KERMIT                     ; execute IBM PC KERMIT program
  SET BAUD 1200              ; set appropriate baud rate
  SET PARITY EVEN            ; correct parity
  SET LOCAL ON               ; enable local echo of keyboard input
                               chars
  CONNECT                    ; connect to the modem
  D XXX-XXXX                 ; dial the IBM 3090 mainframe
  IBM, TSO, LOGON            ; logon to the IBM under TSO
  PROFILE CHAR(BS)           ; backspace key (ctrl-H) MUST be your
                               TSO character delete function.
  PROFILE NOINTERCOM         ; don't allow messages during
                               data transfer.
  SERVER ASCII(ON)           ; execute TSO KERMIT in server mode,
                               ascii file
  ctl- C                     ; escape back to local (PC) KERMIT
  GET myfile.text            ; specify file(s) to be sent from 3090
                               to PC

        File is transfered without further user intervention.
        Once on the IBM PC, the filename will be 'iiiaaaa.MYF'.
        The first three characters of the TSO filename
        are appended to your TSO LOGON Prefix.  Use STORET
        command %SHOW on TSO if you don't know your prefix.

  BYE                        ; terminate mainframe connection, exit
                               from KERMIT.
             or, alternatively
  FIN                        ; TSO SERVER is terminated, but host
                               session is not logged off.
  CON                        ; KERMIT becomes transparent, commands
                               are again passed to the host TSO session.

1





        Data file transfer  -  from IBM PC to IBM 3090 HOST under TSO.
     -----------------------------------------------------------------

  on the IBM PC, enter:
  KERMIT                     ; execute IBM PC KERMIT program
  SET BAUD 1200              ; set appropriate baud rate
  SET PARITY EVEN            ; correct parity
  SET LOCAL ON               ; enable local echo of keyboard
                               input
                               chars
  CONNECT                    ; connect to the modem
  D XXX-XXXX                 ; dial the IBM 3090 mainframe
  IBM, TSO, LOGON            ; logon to the IBM HOST under TSO.
  READY                        TSO response from HOST.
  PROFILE CHAR(BS)           ; backspace key (ctrl-H) MUST be your
                               TSO character delete function.
  PROFILE NOINTERCOM         ; don't allow messages during
                               data transfer.
  SERVER ASCII(ON) RECFM(FB) LRECL(80) BLOCK(3120)
                             ; Place TSO KERMIT in server mode
  (ctrl-r.bracket)-C         ; escape back to local (PC) KERMIT
  SEND myfile.txt            ; specify file(s) to be sent from IBM
                               PC to IBM MAINFRAME HOST

        File is transfered without further user intervention.
        on the TSO HOST, filename will be 'iiiaaaa.MYFILE.TXT.KERMIT'

  BYE                        ; terminate mainframe connection, exit
                               from KERMIT. You will be logged off.
             or, alternatively
  FIN                        ; TSO SERVER is terminated, but host
                               session is not logged off.
  CON                        ; KERMIT becomes transparent, commands
                               are again passed to the host TSO session.

1


  7. Additional Information
  -------------------------



     1. TSO KERMIT has a help command so that you may obtain information
        on the appropriate command format or options.  Entering HELP
        will return a list of valid TSO KERMIT subcommands.  For more
        information on a particular subcommand, enter HELP subcommand.
        For example, HELP RECEIVE will return RECEIVE subcommand
        information, and HELP SET will give you SET options.

     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.  For most text files, LRECL(80) is
        recommended.

     3. Before connecting to the IBM mainframe, several PC KERMIT values
        must be set.

        You should enter
              SET BAUD 1200        * 300 or 2400 also work, if your
                                     equipment supports these speeds.
              SET PARITY EVEN      * MVS/TSO communications use
                                     even parity at EPA.
              SET LOCAL ON         * Enable local echo.
                                     MVS/TSO is half duplex to ASCII
                                     terminals.

        These flags will remain in effect as long as you do not exit
        from PC 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).  TSO timeouts are fairly common when sending files
        from the PC to the IBM 3090; they are extremely rare when
        receiving files from the 3090.

     5. Since the micro does not send an error packet when it aborts,
        KERMIT-TSO does not know the micro has stopped.  Therefore, if
        you terminate PC Kermit and later reconnect, 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 KERMIT-TSO
        error message, however, will indicate that no start of header
        character was found.  In some cases it may be necessary to abort
        KERMIT-TSO using the attention (break) interrupt.
        KERMIT will transmit a "break" when you enter ESC-B (usually
        CTRL-r.Bracket B <ENTER>)

     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."
1




     7. During the initialization process with the micro, KERMIT-TSO
        ignores the data regarding timeouts and padding; they do not
        effect the program's execution.

     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 EBCDIC
        (characters not representable in EBCDIC are replaced by a
        semicolon).  Not only is it easier to work with EBCDIC
        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 ASCII.


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 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 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 the BLKSIZE to include the block
                descriptor work (BDW).

        "Open for dataset failed"
                Indicates a problem opening the dataset.
