home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / ibmtsochicago / tsokerdoc.txt < prev    next >
Text File  |  2020-01-01  |  19KB  |  456 lines
  1. 107/10/84                                                             KERMIT-TSO
  2.  
  3.  
  4.  
  5.  1. Introduction
  6.  
  7.  KERMIT  is  a set of programs that transfer files between computers over normal
  8.  terminal communication lines.  It implements the  "KL10  Error-Free  Reciprocol
  9.  Microcomputer  Interchange over TTY-Lines" protocol.  Originally designed to be
  10.  used between a microcomputer and the DEC-20, the protocol  will  also  transfer
  11.  files  to  and  from  a  microcomputer  and IBM mainframe systems running under
  12.  MVS/TSO.
  13.  
  14.  KERMIT transfers data by creating packets with information regarding  the  type
  15.  of packet being sent, it's length, a packet number, and a checksum to determine
  16.  whether the data has been modified during transmission.  If a packet is lost or
  17.  garbled, KERMIT will attempt to resend it.
  18.  
  19.  Written  in  IBM  370  assembly language to run under MVS/TSO on IBM 370-series
  20.  mainframes (System/370, 303x, 43xx, 308x, ...). These are half duplex  systems;
  21.  the  communication  line  must "turn around" before any data can be sent to it.
  22.  The fact that a packet has been received from the IBM system  is  no  guarantee
  23.  that it is ready for a reply.  Thus any Kermit talking to this system must wait
  24.  for the line turnaround character (XON) before transmitting the next character.
  25.  
  26.  IBM  systems  talk  to  their terminals through a communications front end (IBM
  27.  3705, 3725, COMTEN 3670, etc).  These front ends generally insist on using  the
  28.  8th  bit  of  each  character  for parity.  This means that binary files (files
  29.  con-taining other than ordinary letters, digits, punctuation, carriage returns,
  30.  tabs, and so forth) can not be correctly sent or received by these systems with
  31.  Kermit (protocol version 1).
  32.  
  33.  The IBM system under MVS/TSO is unable to interrupt a read  on  its  "console".
  34.  This  means  that  the  IBM  version of Kermit cannot timeout.  The only way to
  35.  "timeout" TSO Kermit is from the other side -- typing a carriage return to  the
  36.  micro's  Kermit  causing  it  to  retransmit  its  last packet, or an automatic
  37.  timeout as provided by Kermit-20.  For this reason,  TSO  Kermit  waits  thirty
  38.  seconds  before sending its first packet when sending files from MVS/TSO.  This
  39.  gives the user sufficient time to return to the  local  Kermit  and  issue  the
  40.  Receive  command.   Otherwise, a protocol deadlock would arise requiring manual
  41.  intervention by the user.
  42.  
  43.  Also, MVS/TSO stores files as records rather byte streams.  MVS/TSO Kermit  has
  44.  to  worry  about  assembling  incoming  data packets into records and stripping
  45.  CRLFs from incoming lines, and also appending CRLFs to - and stripping trailing
  46.  blanks from -- outgoing records.
  47.  
  48.  You must be using an ASCII terminal to run KERMIT-TSO.
  49.  
  50.  KERMIT-TSO must be installed as a Command Processor (CP) on your system.
  51.  
  52.  Please note that this document should be used in conjunction  with  the  Kermit
  53.  manual,  and  assumes  you  have  read  the  sections  pertaining to the IBM/PC
  54.  microcomputer.  For more information regarding the manual,  see  the  Reference
  55.  section at the end of this report.
  56. -
  57. 0
  58.                                       -1-
  59. 107/10/84                                                             KERMIT-TSO
  60.  
  61.  
  62.  
  63.  2. TSO Command Syntax and Options
  64.  
  65.  
  66.  KERMIT
  67.  
  68.  
  69.  You simply type a carriage return after issuing the
  70.  KERMIT command.
  71.  
  72.  Commands:
  73.  
  74.            Send
  75.  
  76.            Receive
  77.  
  78.            Set
  79.  
  80.            Show
  81.  
  82.            Status
  83.  
  84.            Help
  85.  
  86.            Exit
  87.  
  88.            Quit
  89.  
  90.            ?
  91.  
  92.  2.1. TSO KERMIT Command Options
  93.  
  94.  SEND [dataset name]
  95.                 Send the specified dataset.  KERMIT-TSO will send
  96.                 only  one  file  per  request,  no wildcarding is
  97.                 allowed.  If the dataset name is  not  specified,
  98.                 KERMIT-TSO  will  prompt  for one.  Note, dataset
  99.                 must be cataloged.
  100.  
  101.  RECEIVE [dataset name]
  102.                 Receive the file sent from  the  micro.   If  the
  103.                 dataset  name  is  not  specified KERMIT-TSO will
  104.                 prompt for one.  If no dataset previously  exists
  105.                 with  this  name a file will be created using the
  106.                 value of the SPACE  parameter.   (NOTE,  at  this
  107.                 time  KERMIT-TSO does not trap for abends, and if
  108.                 the  file  being  received  excedes   the   space
  109.                 allocated  KERMIT-TSO will abnormally terminate.)
  110.                 The attributes for the dataset will be taken from
  111.                 the RECFM, LRECL, and BLKSIZE parameters.   If  a
  112.                 dataset  exists  KERMIT-TSO will prompt to see if
  113.                 you wish to overwrite the dataset.
  114.  
  115.  SET <parameter> <value>
  116.                 Set the parameter to the specified value.   Legal
  117.                 Set commands are:
  118.  
  119.                                       -2-
  120. 107/10/84                                                             KERMIT-TSO
  121.  
  122.  
  123.  
  124.                 SPACE <d>
  125.                      Specifies   the   number  of  tracks  to  be
  126.                      allocated to the dataset.  The default is  5
  127.                      tracks.   Both  the  primary  and  secondary
  128.                      allocation are set to the value specified.
  129.  
  130.                 RECFM <c>
  131.                      Denotes the record format to  be  used  when
  132.                      creating   the   dataset.   Only  fixed  and
  133.                      variable length records are  allowed,  where
  134.                      variable   is  the  default.   Indicate  the
  135.                      desired record format by either an F or a V.
  136.  
  137.                 BLKSIZE <d>
  138.                      Indicates the block size  for  creating  the
  139.                      dataset.   The default is 80 and the maximum
  140.                      is 32767.  If the RECFM is F  the  blocksize
  141.                      must be a multiple of the value specified in
  142.                      the LRECL parameter.  If RECFM is F then the
  143.                      BLOCKSIZE must be at least LRECL + 4.
  144.  
  145.                 LRECL <d>
  146.                      Indicates  the  logical  record  length  for
  147.                      creating the dataset.  The default is set to
  148.                      80, and the maximum allowed is 255.  If  the
  149.                      RECFM  is  V  the  value  must include the 4
  150.                      bytes for the record descriptor word (RDW).
  151.  
  152.                 QUOTE <c>
  153.                      The quote character you wish to use in place
  154.                      of the default (#).  It must  be  a  single,
  155.                      printable    character    from   among   the
  156.                      following:  33-62, 96, or 123-126 (decimal).
  157.  
  158.                 START <d>
  159.                      Indicates  the   start-of-header   character
  160.                      which  you  choose to send and receive.  The
  161.                      default is a CNTL-A (ASCII 01), but  can  be
  162.                      set  to  any two digit number between 00 and
  163.                      31 (dec).
  164.  
  165.                 END <d>
  166.                      Indicates  the  end-of-line  character   you
  167.                      choose  to send.  The default is a CR (ASCII
  168.                      13), but can be set to any two digit  number
  169.                      between 00 and 31 (dec).
  170.  
  171.                 PAC <d>
  172.                      Allows  the  user to specify the packet size
  173.                      the  micro  should  use  when   sending   to
  174.                      KERMIT-TSO.   The  range is 26-94 (decimal),
  175.                      where 94 is the default.
  176.  
  177.                 DEBUG [ON | OFF]
  178.                      Allows the user to specify whether  a  trace
  179.  
  180.                                       -3-
  181. 107/10/84                                                             KERMIT-TSO
  182.  
  183.  
  184.  
  185.                      of  packet  information  will be writen to a
  186.                      dataset.  Before using this option the  user
  187.                      must  have  allocated a dataset to file name
  188.                      (ddname) "DEBUG".
  189.  
  190.                 DELAY <d>
  191.                      Allow the user to specify the length of time
  192.                      in seconds that KERMIT-TSO will  wait  after
  193.                      the  user  issues a SEND.  The default is 20
  194.                      seconds.  This will give the  user  time  to
  195.                      escape  back  to  his micro KERMIT and issue
  196.                      the neccesary commands.
  197.  
  198.  SHOW STATUS
  199.                 Displays the current value of all variables  that
  200.                 can be changed via the SET command.
  201.  STATUS
  202.                 Returns  the  status of the previous execution of
  203.                 KERMIT-TSO.   Therefore,   STATUS   will   either
  204.                 display    the    message    "Kermit    completed
  205.                 successfully",  or  the  last  error  encountered
  206.                 prior to aborting.
  207.  
  208.  HELP           Displays a message that briefly explains KERMIT-TSO commands.
  209.  
  210.  EXIT           from KERMIT-TSO.
  211.  
  212.  QUIT           Same as EXIT.
  213.  
  214.  ?              Lists all legal KERMIT-TSO commands.
  215.  
  216.  
  217.  3. Examples under TSO
  218.  
  219.  Here is a brief example of how to use the IBM/PC in conjunction with KERMIT-TSO
  220.  to send a file to the IBM-PC.
  221.  
  222.      A>kermit
  223.  
  224.      Kermit-86>set loc on            ; Indicate half duplex
  225.      Kermit-86>set ibm on            ; Cause line turn around wait
  226.      Kermit-86>set baud 1200         ; Set the baud rate
  227.      Kermit-80>connect
  228.  
  229.         [ The micro will act as a regular terminal from now on.]
  230.         [ Login here as you normally would, and run KERMIT-TSO.]
  231.  
  232.      kermit
  233.      KERMIT-TSO>?
  234.      Legal Commands are:
  235.      Receive, Send, Help, Exit, Quit, Set, Status, Show
  236.      KERMIT-TSO>send finger.database         ; Send this file
  237.  
  238.      Waiting    20 seconds before sending.
  239.      ^]C                                     ; Return to the micro
  240.  
  241.                                       -4-
  242. 107/10/84                                                             KERMIT-TSO
  243.  
  244.  
  245.  
  246.                                              ; by typing <escape>]C
  247.  
  248.      Kermit-86>
  249.      Kermit-86>receive                       ; Micro receives the file
  250.  
  251.          [the file is sent .......]
  252.  
  253.      Kermit-86>connect
  254.  
  255.          [press carriage return to see TSO's prompt]
  256.  
  257.      KERMIT-TSO>status
  258.      Kermit completed successfully
  259.      KERMIT-TSO>ex
  260.      READY
  261.      logoff
  262.      CONNECT TIME -  2:30.95
  263.      SYSRONR Logged off TSO at 15:34:25 on July 6, 1984
  264.  
  265.      ^]C                         ; Return to the micro
  266.                                  ; by typing <escape>C
  267.  
  268.      Kermit-86>exit
  269.      A>
  270.  
  271.  In  order  to send a file from the IBM/PC to the IBM mainframe repeat the above
  272.  procedure swapping the command SEND with RECEIVE and vice versa.
  273.  
  274.  
  275.  4. Additional Information
  276.  
  277.     1. The  commands  are supplied with a help option, so a question mark can be
  278.        typed to get the appropriate format or a list of options.   The  question
  279.        mark,  however,  must  be  followed by a carriage return; KERMIT-TSO will
  280.        respond and display the prompt again.  For instance, SET ?  will list all
  281.        valid options for the SET command.
  282.  
  283.     2. When receiving files, if the record format is fixed,  any  record  longer
  284.        than  the logical record length will be truncated.  The record length can
  285.        be as high as 255.  For receiving files, the  maximum  record  length  is
  286.        255.
  287.  
  288.     3. Before  connecting  to  the  IBM mainframe, three flags must be set.  You
  289.        should set the IBM flag on, set the LOCAL-ECHO flag on (used to  indicate
  290.        half  duplex),  and  specify  the baud rate you will be using.  To turn a
  291.        flag on, type to the micro's prompt "Set XXX On" where XXX  is  the  flag
  292.        name.  Indicate the baud rate by typing "Set baud", and choose from among
  293.        a list the IBM-PC supplies.  These flags will remain in effect as long as
  294.        you do not exit from the micro's version of Kermit.  See the example of a
  295.        session for further clarification.
  296.  
  297.     4. The  current  version of KERMIT-TSO does not support timeouts.  The user,
  298.        therefore, should hit the carriage return key  after  a  long  period  of
  299.        inactivity (that is, when the screen display does not change.)
  300.  
  301.  
  302.                                       -5-
  303. 107/10/84                                                             KERMIT-TSO
  304.  
  305.  
  306.  
  307.     5. Since  the micro does not send an error packet when it aborts, KERMIT-TSO
  308.        does not know the micro has stopped sending it  information.   Therefore,
  309.        when you connect back to the IBM, KERMIT-TSO may still be sending packets
  310.        (they  will  appear  on the screen).  The user must hit a carriage return
  311.        until KERMIT-TSO has sent the  maximum  number  of  packets  allowed  and
  312.        aborts.  The error message, however, will not indicate that communication
  313.        stopped  because  the  micro  aborted, but rather that no start of header
  314.        character was found.
  315.  
  316.     6. The minimum send packet size  KERMIT-TSO  will  allow  is  26.   This  is
  317.        necessary  to  avoid  an  error  while  sending  the filename or an error
  318.        packet.  If the micro tries  to  set  the  value  to  be  less  than  26,
  319.        KERMIT-TSO  will  immediately  abort  with  an  error of "Bad send-packet
  320.        size."
  321.  
  322.     7. During the initialization process with the micro,  KERMIT-TSO  sends  all
  323.        six  pieces of information (that is, the receive packet size, the timeout
  324.        data, the number of padding characters, the character used  for  padding,
  325.        the  line  terminator, and the quote character.) When receiving this data
  326.        from the micro,  KERMIT-TSO  ignores  the  data  regarding  timeouts  and
  327.        padding;  they  do not effect the program's execution.  Therefore, if the
  328.        quote and end-of-line characters used are the defaults,  the  micro  need
  329.        only  send KERMIT-TSO its buffer size.  Only if the defaults are not used
  330.        must  ALL  the  information  be  sent  (since  the  data   is   organized
  331.        positionally).   If,  however,  the  micro sends all the information even
  332.        when not required, KERMIT-TSO will simply ignore the irrelevant portion.
  333.  
  334.     8. When sending packets to KERMIT-TSO, the micro must use a carriage  return
  335.        as  the  end-of-line  character.   TSO  requires  a  carriage  return  to
  336.        terminate a read from the terminal; thus, if any other character is used,
  337.        KERMIT-TSO will never get the packets.
  338.  
  339.     9. KERMIT-TSO translates the data it reads back  to  ASCII  (characters  not
  340.        representable in ASCII are replaced by a null).  Not only is it easier to
  341.        work   with  ASCII  characters,  but  it  makes  things  more  consistent
  342.        throughout the many versions of Kermit.  When the packets are sent to the
  343.        micro, KERMIT-TSO converts all data back to EBCDIC.  The ASCII to  EBCDIC
  344.        translation table can be found in Appendix V of the Kermit manual.
  345.  
  346.  4.1. Error Messages
  347.  
  348.  KERMIT-TSO  supplies  the  micro and the user with numerous error messages.  If
  349.  the execution must be aborted, an error packet is  sent  to  the  micro  before
  350.  KERMIT-TSO  stops.   The  same  message can be retrieved via the STATUS command
  351.  when KERMIT-TSO returns and displays the prompt.  If KERMIT-TSO aborted because
  352.  the maximum amount of retries was exceeded (20 on initialization packets and  5
  353.  on  others),  the  error message will display the most recent error (i.e. - the
  354.  last NAK  KERMIT-TSO  encountered).   If  execution  stops  because  the  micro
  355.  aborted,  the error message will convey that to the user, but it is the micro's
  356.  responsibility to pinpoint the error.  The messages  KERMIT-TSO  gives  are  as
  357.  follows :
  358.  
  359.        "Bad send-packet size"
  360.                Sent  when the micro attempts to set its receive buffer size to a
  361.                value that is less than 26  (the  minimum  that  KERMIT-TSO  will
  362.  
  363.                                       -6-
  364. 107/10/84                                                             KERMIT-TSO
  365.  
  366.  
  367.  
  368.                accept)  or  larger  than 94, the maximum.  It will also occur if
  369.                KERMIT-TSO tries to send a packet that is larger than the maximum
  370.                specified.
  371.  
  372.        "Bad message number"
  373.                If the packet number is less than zero or  greater  than  63  (at
  374.                which point it should "wrap around" back to zero).
  375.  
  376.  
  377.                This message is returned if the packet type does not fall between
  378.                A-Z.
  379.  
  380.        "Unrecognized State"
  381.                If  KERMIT-TSO  is  in  a  state  not  previously  defined by the
  382.                protocol, it will abort with this message.
  383.  
  384.        "No SOH encountered"
  385.                This error arises if KERMIT-TSO reads the entire  packet  without
  386.                encountering an SOH character.  The result is that it sends a NAK
  387.                to the micro, and marks this error as the most recent one.
  388.  
  389.        "Bad Checksum"
  390.                If  the  checksum calculated by KERMIT-TSO does not match the one
  391.                sent by the micro, KERMIT-TSO NAK's the  packet  and  flags  this
  392.                error.
  393.  
  394.        "Bad character count"
  395.                This  error  is set if KERMIT-TSO receives a packet whose size is
  396.                illegal (that is,  if  the  size  parameter  was  garbled  during
  397.                transmission of the packet.)
  398.  
  399.        "Micro sent a NAK"
  400.                Keep track of who rejected the packet.
  401.  
  402.        "Lost a packet"
  403.                When  a  packet  is received and the sequence number is different
  404.                from the number KERMIT-TSO expected, the packet is NAK'ed.
  405.  
  406.        "Micro aborted"
  407.                Tells you that the micro aborted unexpectedly.
  408.  
  409.        "Invalid RECFM, only fixed or variable supported"
  410.                KERMIT-TSO will abort on any file-system error it encounters when
  411.                reading from the file it is to send.  It can only send files with
  412.                variable or fixed length record formats, therefore,  Wylbur  Edit
  413.                or Packed format files will cause an error.
  414.  
  415.        "BLKSIZE not a multiple of LRECL for RECFM=F"
  416.                KERMIT-TSO  will  refuse RECEIVE request and return to the KERMIT
  417.                prompt.  The BLOCKSIZE is not an integral multiple of  the  LRECL
  418.                when RECFM F (fixed) is specified.
  419.  
  420.        "LRECL not less than BLKSIZE-4 for RECFM=V'
  421.                KERMIT-TSO  will  refuse RECEIVE request and return to the KERMIT
  422.                prompt.  The LRECL for RECFM=V (variable) must be four less  than
  423.  
  424.                                       -7-
  425. 107/10/84                                                             KERMIT-TSO
  426.  
  427.  
  428.  
  429.                the BLKSIZE to include the block descriptor work (BDW).
  430.  
  431.        "Open for dataset failed"
  432.                Indicates a problem opening the dataset.
  433.  
  434.  5. Reference
  435.  
  436.  For  a more detailed explanation of Kermit or information regarding the IBM-PC,
  437.  consult the Kermit manual, Kermit Users Guide and Specification.  The manual is
  438.  available in the Reference Library at USITE.
  439. -
  440. -
  441. -
  442. -
  443. -
  444. -
  445. -
  446. -
  447. -
  448. -
  449. -
  450. -
  451. -
  452. -
  453. -
  454.  
  455.                                       -8-
  456.