home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / ibm370 / ikcker.lpt < prev    next >
Text File  |  2020-01-01  |  164KB  |  2,579 lines
  1. 0
  2. 0
  3. 0
  4. 0
  5. 0
  6. 0
  7. 0
  8. 0
  9.                      IBM SYSTEM/370 CMS KERMIT USER'S GUIDE
  10. 0
  11.                                    VERSION 4.3
  12. 0
  13.                                   John Chandler
  14. 0                  Harvard/Smithsonian Center for Astrophysics
  15. 0                              September 30, 1993
  16. 0
  17. 0                            Copyright (C) 1981,1993
  18.              Trustees of Columbia University in the City of New York
  19. 0     Permission is granted to any individual or institution to use, copy,
  20.      or redistribute this document so long as it is not sold for profit, and
  21.                    provided this copyright notice is retained.
  22. 1IBM System/370 Kermit                                                    Page i
  23. 0-------------------------------------------------------------------------------
  24.                                 Table of Contents
  25. 01. IBM 370 KERMIT                                                             1
  26. 0   1.1. Translation Tables                                                    2
  27.     1.2. File Attributes                                                       6
  28.     1.3. Program Operation                                                     8
  29.     1.4. Kermit-370 Subcommands                                                9
  30.     1.5. Before Connecting to the Mainframe                                   32
  31.     1.6. Trouble-shooting Protocol Converters                                 33
  32.     1.7. After Returning from Kermit-370                                      36
  33.     1.8. What's New                                                           36
  34.     1.9. What's Missing                                                       38
  35.     1.10. Further Reading                                                     39
  36. 02. IBM CMS KERMIT                                                            40
  37. 0   2.1. The CMS File System                                                  41
  38.     2.2. Program Operation                                                    42
  39.     2.3. Kermit-CMS Subcommands                                               45
  40.     2.4. How to build an executable Kermit-CMS                                51
  41.     2.5. What's New                                                           52
  42.     2.6. What's Missing                                                       53
  43. 0Index                                                                        54
  44. 1IBM System/370 Kermit                                                   Page ii
  45. 0-------------------------------------------------------------------------------
  46.                                  List of Tables
  47. 0   Table 1-1:   Allowed character set combinations in Kermit-370              4
  48.     Table 1-2:   EBCDIC (hexadecimal) code points for LATIN1                   5
  49.     Table 1-3:   Character graphics for EBCDIC codes                           7
  50.     Table 1-4:   Error messages and codes for Kermit-370                      37
  51. 11. IBM 370 KERMIT                                                        Page 1
  52. 0-------------------------------------------------------------------------------
  53.  1. IBM 370 KERMIT
  54. 0Program:       John  Chandler  (Harvard/Smithsonian  Center  for Astrophysics);
  55.                 contributions from Vace Kundakci and Daphne Tzoar (Columbia  U),
  56.                 Bob  Shields  (U.  Maryland),  Greg  Small  (UC Berkeley), Clark
  57.                 Frazier (Harvard Bus. Sch.), Bob  Bolch  and  Steve  Blankinship
  58.                 (Triangle),  Ron  Rusnak  (U.  Chicago),  Roger  Fajman and Dale
  59.                 Wright (NIH), Andre Pirard (U. Liege),  Pierre  Goyette  (McGill
  60.                 U.)
  61.  Language:      IBM 370 Assembler
  62.  Documentation: John Chandler (CfA)
  63.  Version:       4.3
  64.  Date:          1993 September
  65. 0Kermit-370  is  a  family  of  programs  implementing  the KERMIT file transfer
  66.  protocol for IBM 370-series mainframes (System/370,  303x,  43xx,  308x,  3090,
  67.  etc.)  under  a  variety  of  operating  systems.    Kermit-370  operates  over
  68.  asynchronous ASCII communication lines attached to a 3705-style or protocol en-
  69.  veloping  3708  front  end  ("TTY" or line-mode devices), to a Series/1 or 4994
  70.  running the Yale ASCII Terminal Communication System  or  the  IBM  7171  ASCII
  71.  Device  Control Unit or a 9370 with ASCII subsystem ("SERIES1" devices), to the
  72.  IBM 3174 protocol converter at level B2.0 or  higher  ("AEA"  devices),  or  to
  73.  front-ends with graphics pass-through mode, such as the Datastream/Leedata 8010
  74.  and PCI 1076 ("GRAPHICS" devices).  As of this writing, the  pending  implemen-
  75.  tation  of  full(er)  7171 compatibility in the program product SIM3278 has not
  76.  been completed.    The  non-line-mode  devices  are  often  called  full-screen
  77.  devices.  For more details on front ends, see the section SET CONTROLLER.
  78. 0The  source is coded in IBM 370 assembly language and is compatible with the F,
  79.  VS, and H assemblers.  The code is divided into sections, some generic and some
  80.  specific  to  an individual operating system.  While the details of file-system
  81.  and supervisor interaction vary widely among  the  systems  available  for  IBM
  82.  370's, the basic features are essentially the same.  This chapter describes the
  83.  features common to all variants of Kermit-370, and a separate chapter will deal
  84.  with the system-specific details for each variant.
  85. 0IBM  370 systems have some peculiarities that users should be aware of.  First,
  86.  these systems are essentially half-duplex; the communication  line  must  "turn
  87.  around"  before  any  data  can  be  sent.    The  "TTY"  devices  are strictly
  88.  half-duplex, and even the "SERIES1", "GRAPHICS", and  "AEA"  devices,  although
  89.  they  maintain  full-duplex  communication  with  the terminal, must transmit a
  90.  block at a time to the mainframe.  The fact that a  packet  has  been  received
  91.  from the IBM system through a "TTY" device is no guarantee that it is ready for
  92.  a reply; generally, the true indicator of  readiness  is  the  line  turnaround
  93.  character  (XON), which the operating system sends immediately before issuing a
  94.  read request.  On some systems, however, it is possible for Kermit to  do  away
  95.  with  the  system-supplied  turnaround  and  schedule read requests immediately
  96.  after the corresponding writes.  It is up to the user to tell the other  Kermit
  97.  how it must conform to the requirements of the IBM mainframe.
  98. 0A  second distinction is that disk files are encoded using the EBCDIC character
  99.  set.  Consequently, there are three layers of character translation on  packets
  100.  exchanged  on  a  "TTY"  device.    For  an incoming packet, the outer layer is
  101.  provided by the operating system, which translates all characters from ASCII to
  102.  EBCDIC.    Kermit-370 must then translate the packets back to ASCII (the middle
  103.  layer) in order to calculate and verify the checksum.  Data arriving through  a
  104. 11. IBM 370 KERMIT                                                        Page 2
  105. 0-------------------------------------------------------------------------------
  106.  "SERIES1",  "GRAPHICS", or "AEA" device are still in ASCII and therefore bypass
  107.  the two outer layers.  In any case, Kermit-370 translates  text  files  finally
  108.  into  EBCDIC (the inner layer) before storing on disk.  When Kermit-370 sends a
  109.  file, the opposite translations occur.  The middle-layer tables used by  Kermit
  110.  must  be  the  inverses  of the corresponding outer-layer ones used by the host
  111.  operating system if file transfers are to work at all.  If necessary, the  sys-
  112.  tem  programmer  should  add the appropriate SET TATOE/TETOA/TTABLE subcommands
  113.  (q.v.)  to the global INIT file.  Indeed, it is usually  a  good  idea  to  set
  114.  TTABLE  ON  in  the  global INIT file to force using different built-in sets of
  115.  tables for the inner and middle layers whenever the system has  "TTY"  devices.
  116.  The standard 7-bit ASCII-to-EBCDIC translations can be found in the Appendix or
  117.  the IBM System/370 Reference Card.  See the section  "Translation  Tables"  for
  118.  more details.
  119. 0Another  distinction  of  IBM  370's  is  that they store and retrieve files as
  120.  records rather than byte streams.  Records may be either fixed-length with some
  121.  sort of padding (as needed) or varying-length with some sort of (generally hid-
  122.  den) delimiters.  Thus, Kermit-370 must assemble  incoming  data  packets  into
  123.  records  by  stripping  off carriage return-linefeed pairs (CRLF's) and padding
  124.  with blanks or truncating as needed and must strip trailing blanks  and  append
  125.  CRLF's to outgoing records.  (See the SET FILE TYPE subcommand.)  Further, disk
  126.  files typically have the records combined into blocks for efficiency.  One con-
  127.  sequence  of  this form of storage is that files have attributes describing the
  128.  component records: maximum record length (LRECL), record  format  (RECFM),  and
  129.  sometimes block size (BLKSIZE).
  130. 0As  mentioned before, Kermit-370 is a family of programs.  At present, only the
  131.  CMS, TSO, MUSIC, ROSCOE, and CICS variants are operational.  Variants for DOS-4
  132.  and MTS have at least reached the "drawing board," but no others have even been
  133.  started as of this writing.  Volunteers are always welcome to  port  Kermit-370
  134.  to  other operating systems or add new features to the existing family.  Anyone
  135.  interested should first get in touch with the Center for  Computing  Activities
  136.  at  Columbia  University  to find out what projects of a similar nature are al-
  137.  ready pending (and thereby prevent unnecessary duplication of effort).    There
  138.  are  supplemental  files in the Kermit distribution with explanations of how to
  139.  go about porting Kermit-370 and how to add support for new terminal  controller
  140.  types.    For  details, refer to the installation guide for the variant of your
  141.  choice.
  142. 0
  143.  1.1. Translation Tables
  144. 0Traditionally, IBM mainframe Kermits have translated 7-bit ASCII characters  to
  145.  8-bit   EBCDIC  characters  and  ignored  the  "parity"  bit  in  the  process.
  146.  Similarly, the 8-bit EBCDIC characters  have  been  mapped  onto  7-bit  ASCII,
  147.  thereby  producing  many  ambiguities  in  translating  the ASCII files back to
  148.  EBCDIC.  These ambiguities fall into  two  categories:  EBCDIC  characters  not
  149.  representable  in ASCII have been rendered as ASCII nulls, and alternate EBCDIC
  150.  representations of characters such as the  ASCII  backslash  have  been  mapped
  151.  together,  but  at  least no two 7-bit ASCII characters are translated into the
  152.  same EBCDIC character.  The ambiguities were tolerable  in  environments  where
  153.  the  traditionally  non-printable  characters never occurred in text files, but
  154.  text processing has increasingly tended to include such  characters  for  math-
  155.  ematical  formulas or for languages other than English.  Ultimately, the trans-
  156.  lation tables must become completely invertible, lest information  be  lost  in
  157.  the  transfer.    There  has long been an option to replace parts of the trans-
  158. 11.1. Translation Tables                                                  Page 3
  159. 0-------------------------------------------------------------------------------
  160.  lation tables via commands from the user (or imbedded in the INIT  files),  but
  161.  such  replacements were always supported locally and were, therefore, basically
  162.  non-standard.
  163. 0The concept of standard translations is currently in a state of flux because of
  164.  the  proliferation  of 8-bit code pages and the countervailing efforts at stan-
  165.  dardization among groups such as the ISO and Kermit developers.  In particular,
  166.  Kermit-370  now  supports  a set of EBCDIC and "extended ASCII" code pages with
  167.  built-in translation tables and automatic identification of the "ASCII"  trans-
  168.  fer  character  set via Attribute packets.  This facility supports files stored
  169.  using numerous IBM Country Extended Code  Pages  and  permits  transfers  using
  170.  character  sets  ASCII,  ARABIC,  CYRILLIC, GREEK, HEBREW, JAPAN-EUC, KATAKANA,
  171.  LATIN1, LATIN2, LATIN3, and THAI.  See Table 1-1 for a display of  the  allowed
  172.  combinations  of  character  sets.   See also file ISOK7.TXT in the Kermit dis-
  173.  tribution for a somewhat  outdated  description  of  the  protocol  extensions.
  174.  Kermit-370   currently   supports   text  files  in  the  following  languages:
  175.  Afrikaans, Albanian, Arabic, Bulgarian, Byelorussian, Catalan, Czech, Croatian,
  176.  Danish, Dutch, English, Esperanto, Faeroese, Finnish, French, Gaelic, Galician,
  177.  German, Greek, Hebrew, Hungarian, Icelandic, Italian,  Japanese  (Katakana  and
  178.  Kanji),  Lao,  Latin,  Macedonian, Maltese, Norwegian, Polish, Portuguese, Que-
  179.  chua, Romanian, Russian, Serbian, Slovak, Slovene, Spanish,  Swahili,  Swedish,
  180.  Thai,  Turkish,  Ukrainian, and Volapuk.  Visual representations of the charac-
  181.  ters sets may be found in the ISO register (for transfer) and  in  various  IBM
  182.  documents, such as S544-3156 "About Type" (for files).
  183. 0Kermit itself normally operates in English, but there are versions with the in-
  184.  teractive messages translated into other languages.   The  currently  available
  185.  languages  are  Czech,  Dutch,  Finnish,  French, German, Italian, Polish, Por-
  186.  tuguese, Russian, and Spanish.  Special thanks to  Petr  Adelsberger,  Mauricio
  187.  Alvarenga,  Lorenzo  Beltrame,  Janusz  Bien,  Jose  Eduardo  de Lucca, Richard
  188.  Gatersleben, Kauko Haumalainen, Jaroslaw Kurowski, Roberto Magana, Alberto Rio,
  189.  Christian  Robert,  Gisbert  Selke,  Karel  Smuk,  Rob  van der Wal, Konstantin
  190.  Vinogradov, and Joachim Wlodarz for preparing these translations.  See the  in-
  191.  stallation  guide for details on the alternate-language versions.  There are no
  192.  translations yet of the help files, nor of this document.
  193. 0As nearly as possible, the tables in Kermit-370 are invertible, but all of  the
  194.  character  sets  reserve many (typically 65) code points for control characters
  195.  and leave them officially undefined and unprintable.  This applies both to  IBM
  196.  code  pages and ISO standard 8-bit character sets.  Although 33 of the controls
  197.  have widely accepted mappings, the others do not, and Kermit-370 currently uses
  198.  those  given  in an appendix of IBM's VS/Fortran Reference Manual.  Needless to
  199.  say, such translations are arbitrary and may be invalidated by future decisions
  200.  at  IBM or ISO.  Still, most of the translations are likely to be stable in the
  201.  long run.  Table 1-2 shows the current translation from LATIN1 to EBCDIC, which
  202.  is likely to be the most often used.  Other translations, including the reverse
  203.  ones, may be displayed using the TDUMP subcommand of Kermit-370.
  204. 0Besides converting files for transmission, Kermit-370 must also  compensate for
  205.  the  EBCDIC/ASCII translation performed by some front ends and must, therefore,
  206.  be able to apply the exact reverse translations on both input and output.  This
  207.  is the "middle layer" of translation described earlier for "TTY" devices.  Con-
  208.  sider the fate of a Left Square Bracket character in an  inbound  packet  on  a
  209.  "TTY"  line.    It  begins  as ASCII code x'5B' (91 decimal), but the front end
  210.  translates it to EBCDIC before presenting it to Kermit-370.  In  this  example,
  211.  suppose it becomes EBCDIC code x'4A' (74 decimal) instead of the standard x'AD'
  212. 11.1. Translation Tables                                                  Page 4
  213. 0-------------------------------------------------------------------------------
  214.  -------------------------------------------------------------------------------
  215. 0
  216.                                Transfer character set
  217. 0  Local  ASCII ARAB. CYR. GREEK HEB. JAPAN KATAK.  L1 L2 L3 THAI
  218. 0 CP037     *                                       **
  219.   CP273                                             **
  220.   CP275                                             **
  221.   CP277                                             **
  222.   CP278                                             **
  223.   CP280                                             **
  224.   CP281                                 *           **
  225.   CP282                                             **
  226.   CP284                                             **
  227.   CP285                                             **
  228.   CP290                                 *     **
  229.   CP297                                             **
  230.   CP420           **
  231.   CP424                           **
  232.   CP500     *                           *           **
  233.   CP838                                                       **
  234.   CP870                                                **
  235.   CP871                                             **
  236.   CP875                      **
  237.   CP880     *          **
  238.   CP905                                                   **
  239.   CZECH                                                 *
  240.   DKOI      *          ***
  241.   EBCDIC    *      *                               ***
  242.   H-EBCD                                *      *
  243.   KANJI                                 *
  244. 0         Table 1-1:  Allowed character set combinations in Kermit-370
  245. 0All  allowed  combinations  are  marked  with  asterisks,  and  the   preferred
  246.  combination in each row or column is the one with the most asterisks.  Whenever
  247.  a character set is specified, either directly or through an  Attribute  packet,
  248.  the other category of character set is checked to see if it makes up an allowed
  249.  combination.  If not, it is forced to the preferred character set.
  250. 0
  251.  -------------------------------------------------------------------------------
  252. 0(173 decimal).  Then, Kermit must be primed with a SET TETOA  74  91  so  that,
  253.  when  reconstructing  the  original  ASCII  packet, the character becomes x'5B'
  254.  again.  Otherwise, the packet checksum will appear invalid.  Kermit comes  with
  255.  a  pair  of  default tables, but it may be necessary to customize them, as this
  256.  example shows.  The following procedure will reveal any changes  needed.    The
  257.  procedure  has  two  stages:  the first is for any line-mode front end, and the
  258.  second only for front ends capable of full 8-bit data transfer.  Note that, al-
  259.  though  the discussion refers to hexadecimal values, the Kermit-370 SET subcom-
  260.  mands require decimal numeric arguments.  Also, note that  this  procedure  as-
  261.  sumes  you  will  run  Kermit  with  TTABLE  set  on;  hence, the references to
  262.  Kermit-370 tables are to TATOE and TETOA.  If you  choose  to  define  Kermit's
  263. 11.1. Translation Tables                                                  Page 5
  264. 0-------------------------------------------------------------------------------
  265.  -------------------------------------------------------------------------------
  266. 0
  267.        -0 -1 -2 -3 -4 -5 -6 -7 -8 -9 -A -B -C -D -E -F
  268. 0  0-  00 01 02 03 37 2D 2E 2F 16 05 25 0B 0C 0D 0E 0F
  269.    1-  10 11 12 13 3C 3D 32 26 18 19 3F 27 1C 1D 1E 1F
  270.    2-  40 5A 7F 7B 5B 6C 50 7D 4D 5D 5C 4E 6B 60 4B 61
  271.    3-  F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 7A 5E 4C 7E 6E 6F
  272.    4-  7C C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6
  273.    5-  D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9 AD E0 BD 5F 6D
  274.    6-  79 81 82 83 84 85 86 87 88 89 91 92 93 94 95 96
  275.    7-  97 98 99 A2 A3 A4 A5 A6 A7 A8 A9 C0 4F D0 A1 07
  276.    8-  20 21 22 23 24 15 06 17 28 29 2A 2B 2C 09 0A 1B
  277.    9-  30 31 1A 33 34 35 36 08 38 39 3A 3B 04 14 3E FF
  278.    A-  41 AA 4A B1 9F B2 6A B5 BB B4 9A 8A B0 CA AF BC
  279.    B-  90 8F EA FA BE A0 B6 B3 9D DA 9B 8B B7 B8 B9 AB
  280.    C-  64 65 62 66 63 67 9E 68 74 71 72 73 78 75 76 77
  281.    D-  AC 69 ED EE EB EF EC BF 80 FD FE FB FC BA AE 59
  282.    E-  44 45 42 46 43 47 9C 48 54 51 52 53 58 55 56 57
  283.    F-  8C 49 CD CE CB CF CC E1 70 DD DE DB DC 8D 8E DF
  284. 0
  285.              Table 1-2:  EBCDIC (hexadecimal) code points for LATIN1
  286. 0This table shows the values of the EBCDIC equivalents for the  code  points  in
  287.  the  LATIN1  character  set.    The  values  are  arranged  in LATIN1 collating
  288.  sequence, and the rows and columns  are  labeled  with  the  first  and  second
  289.  digits,  respectively,  of the LATIN1 code points.  For example, LATIN1 code 41
  290.  (hex) is upper-case "A", and the intersection of row "4-" and column  "-1"  has
  291.  the  value  C1 (hex), which is the EBCDIC code for "A".  Rows "0-", "1-", "8-",
  292.  and "9-" are officially undefined in ISO 8859-1 and so, in principle, could  be
  293.  changed  at  some  future time, especially "8-" and "9-".  Note that this table
  294.  uses a format close to that of the TDUMP subcommand  and  of  the  Kermit  code
  295.  itself,  but character-set tables are often displayed with the rows and columns
  296.  interchanged.
  297. 0
  298.  -------------------------------------------------------------------------------
  299. 0file  translation  to  match that of the front end, you should leave TTABLE set
  300.  off and remove the T's from the SET subcommands described  below.    This  will
  301.  also  turn  off  the automatic switching of translation tables according to the
  302.  Attribute packets received from the other Kermit.  Under CMS, you must issue  a
  303.  CMS SET INPUT and a CMS SET OUTPUT before starting this procedure.
  304. 0   1. Create  a file containing all the non-control EBCDIC characters (hex
  305.        codes 40-FF) and display the file on any  available  ASCII  terminal
  306.        hooked up to the line-mode front end in question.
  307. 0   2. If any printable ASCII character is missing from the display, Kermit
  308.        cannot work through this front end (unless you modify the tables  in
  309.        the front end itself).
  310. 0   3. If any ASCII character appears twice, there is no cause for alarm.
  311. 0   4. If any ASCII character does not appear where it should, according to
  312. 11.1. Translation Tables                                                  Page 6
  313. 0-------------------------------------------------------------------------------
  314.        Table 1-3, a SET TATOE must be added to the system INIT file.    For
  315.        example, if EBCDIC code 5F (Not Sign, according to the Appendix) ap-
  316.        pears as an ASCII Tilde (7E), but EBCDIC A1 (Tilde) does not, a  SET
  317.        TATOE  126  95 is required.  Warning: characters considered unprint-
  318.        able by the front end are likely to be filtered  out  entirely  when
  319.        you display the file; do not expect the display to line up just like
  320.        Table 1-3.
  321. 0   5. Create a file on the mainframe using an ASCII  terminal  for  input,
  322.        and  enter  all 95 printable ASCII characters in collating sequence.
  323.        You  can  presumably  save  time  by  skipping  the  52  upper-  and
  324.        lower-case letters and the 10 digits.
  325. 0   6. Display  the file from the previous step in hexadecimal or other bi-
  326.        nary form.
  327. 0   7. If any duplicates appear among the 95 characters (or 33, if you have
  328.        taken the short cut), Kermit cannot work through this front end (un-
  329.        less you modify the tables in the front end).
  330. 0   8. Compare the hexadecimal codes with rows 2-7 of Table 1-2.  If a dis-
  331.        crepancy appears, a SET TETOA must be added to the system INIT file.
  332.        For example, if ASCII Left Bracket (5B) appears as EBCDIC 4A, a  SET
  333.        TETOA 74 91 is needed.  At this point, the first stage is complete.
  334. 0   9. If 8-bit line-mode file transfer is desired, you must now verify the
  335.        extended character set.  Display the file  of  EBCDIC  codes  again,
  336.        this  time  using a terminal with extended character set display, or
  337.        capture the session with a micro Kermit and  display  the  resulting
  338.        file  in  hexadecimal.   If any code in the range A0-FE does not ap-
  339.        pear, the front end will not  allow  8-bit  Kermit  data  transfers.
  340.        Generate  SET TATOE entries for the entire range, as needed, just as
  341.        in the example given for 7-bit codes.  If  the  front  end's  trans-
  342.        lation  tables  are  documented,  it  may be easier to work from the
  343.        manual, but you must be sure that you have tables  for  all  of  the
  344.        translations that occur on the data path.
  345. 0  10. Create  a file of the 95 extended ASCII codes A0-FE, if possible, by
  346.        using a terminal capable of transmitting those codes or transmitting
  347.        a  pre-made  file "raw".  If necessary, use the appropriate table(s)
  348.        in the manual(s) instead.
  349. 0  11. Again, if any duplicates appear, this  front  end  is  incapable  of
  350.        8-bit  file transfers.  Otherwise, generate SET TETOA entries as be-
  351.        fore.
  352. 0
  353.  1.2. File Attributes
  354. 0Kermit-370 attempts to send and receive file attributes along  with  the  files
  355.  themselves.    Before  Kermit receives a file, it compares the Length attribute
  356.  (if available) with the amount of disk space available (if known) so  that  the
  357.  file can be rejected if it will not fit.  In addition, the Type, Access, Encod-
  358.  ing, Disposition, and Format attributes, if any, are interpreted  in  order  to
  359.  match  the  received file to the original as nearly as possible.  All other at-
  360.  tributes (including Date) are simply ignored.  For Type, Kermit recognizes text
  361. 11.2. File Attributes                                                     Page 7
  362. 0-------------------------------------------------------------------------------
  363.  -------------------------------------------------------------------------------
  364. 0
  365.         0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
  366. 0  4-                                    .  <  (  +  |
  367.    5-   &                             !  $  *  )  ;  ^
  368.    6-   -  /                             ,  %  _  >  ?
  369.    7-                              `  :  #  @  '  =  "
  370.    8-      a  b  c  d  e  f  g  h  i
  371.    9-      j  k  l  m  n  o  p  q  r
  372.    A-      ~  s  t  u  v  w  x  y  z           [
  373.    B-                                          ]
  374.    C-   {  A  B  C  D  E  F  G  H  I
  375.    D-   }  J  K  L  M  N  O  P  Q  R
  376.    E-   \     S  T  U  V  W  X  Y  Z
  377.    F-   0  1  2  3  4  5  6  7  8  9
  378. 0
  379.                  Table 1-3:  Character graphics for EBCDIC codes
  380. 0This table shows the representations of the EBCDIC  codes  arranged  in  EBCDIC
  381.  collating  sequence,  row  by  row.    Codes  that do not correspond to ISO 646
  382.  characters (7-bit ASCII), have been left blank.  One special case is the EBCDIC
  383.  code 5F, which represents a Not Sign in IBM's CP037, but which is traditionally
  384.  mapped to the ASCII Circumflex, as shown here.  WARNING: this manual  may  have
  385.  been  printed  on  a  device  that  maps  characters  differently.  Consult the
  386.  Appendix to verify.
  387. 0
  388.  -------------------------------------------------------------------------------
  389. 0and binary specifications; for Access, it recognizes append, normal, and super-
  390.  sede; for Encoding, it recognizes ASCII, extended, and EBCDIC (which it  treats
  391.  as  binary);  for Disposition, it recognizes mail, print, and job; and for For-
  392.  mat, it recognizes text, D-binary, V-binary, binary,  and  LRECL.    Any  other
  393.  values are rejected.
  394. 0On  sending a file, if the other Kermit is willing to accept Attribute packets,
  395.  Kermit-370 sends the Type, Encoding, Format, Date, and Length  attributes  (un-
  396.  less  some  or  all of them have been disabled -- see the SET ATTRIBUTE subcom-
  397.  mand).
  398. 0Unfortunately, the set of file attributes defined in the Kermit protocol is not
  399.  well  matched  to  the  needs  of  IBM  370  file  systems, so that much of the
  400.  machinery for creating and interpreting of Attribute packets is useless.    For
  401.  example, the "Format" attribute, which should logically specify the record for-
  402.  mat of the received file, gives only the format of the file in transmission and
  403.  cannot  distinguish  between  fixed-length  and varying-length records for text
  404.  files.  This limitation is partly due to the fact that  other  Kermits  do  not
  405.  generally  support the same attributes.  In short, even if the protocol made it
  406.  possible, some of the important attributes would  never  be  specified  anyway.
  407.  Nonetheless,  efforts  are  being  made  to extend the protocol to be more com-
  408.  prehensive.
  409. 11.3. Program Operation                                                   Page 8
  410. 0-------------------------------------------------------------------------------
  411.  1.3. Program Operation
  412. 0Kermit-370 can be invoked directly or from a  command  procedure.    In  either
  413.  case,  it  reads  and executes subcommands sequentially until directed to quit,
  414.  and then returns.   A  subcommand  consists  of  one  or  more  fields  (words)
  415.  separated by spaces or commas.
  416. 0Upon  startup,  the  program looks for two (optional) initialization files, one
  417.  system-wide and a second specific to the user.  Both filespecs are, of  course,
  418.  system-dependent.    The  purpose  of these files is to allow Kermit to be cus-
  419.  tomized for a particular system and for  a  user's  specific  settings  without
  420.  changing  the source code.  The system-wide file, which is maintained by a sys-
  421.  tems programmer, should contain Kermit subcommands that all users would need to
  422.  issue  in  order for Kermit to run on the system, such as subcommands to modify
  423.  the ASCII/EBCDIC tables used by Kermit-370.  The user-specific  file,  if  any,
  424.  should  contain subcommands that the user generally issues every time Kermit is
  425.  run.  Kermit-370 executes any subcommands found in these files as  though  they
  426.  were typed at the terminal.  Here is a sample INIT file:
  427. 0  * Asterisk in column one is a comment.
  428.    set transfer character-set latin1
  429.    set file collision rename
  430.    set block 3
  431. 0During  interactive  execution,  you  may  use  the built-in help feature while
  432.  typing Kermit-370 subcommands.  A question mark ("?") typed at almost any point
  433.  in a subcommand, followed by a carriage return, produces a brief description of
  434.  what is expected or possible at that point.  Moreover, mistyping  a  subcommand
  435.  will generally produce a helpful error message or a list of possible options at
  436.  the  point  of  error.    Keywords  in  such  lists  are  displayed  with   the
  437.  minimum-length  abbreviation  in upper case and the remainder, if any, in lower
  438.  case.  In entering Kermit subcommands, any keyword may be shortened to any sub-
  439.  string that contains the minimum abbreviation.
  440. 0Besides  knowing  the mechanics of entering Kermit subcommands and interpreting
  441.  responses, the user must understand  which  subcommands  are  necessary.    The
  442.  default  values for Kermit-370 options have, in some cases, been constrained by
  443.  a desire for continuity, so that some of the  default  behavior  is  distinctly
  444.  "suboptimal."    An  example of this is the traditional 80-byte default RECEIVE
  445.  packet size, which generally gives much slower transmission than a size of 1000
  446.  or  more.    Such options are flagged in this chapter with a notation that they
  447.  perhaps ought to be set in the INIT files.  Note, however, that  the  interplay
  448.  of Kermit protocol sometimes provides a performance upgrade with no special ac-
  449.  tion required from the Kermit-370 user.    An  example  of  this  is  the  SEND
  450.  packet-size, which is always under the control of the other Kermit.  Kermit-370
  451.  always sends packets as long as the other Kermit allows, unless  the  frequency
  452.  of  transmission  errors indicates that shorter packets would be more efficient
  453.  (see the subcommand SET SPEED).
  454. 0Kermit-370 also attempts to produce optimal results by adapting to the file at-
  455.  tributes sent by the other Kermit along with the files, such as TYPE and LRECL.
  456.  Such attributes, when sent by the other Kermit, temporarily override  the  cur-
  457.  rent  settings  in  Kermit-370  during  the  reception  of the associated file.
  458.  Potentially even more  importantly,  Kermit-370  automatically  recognizes  the
  459.  character  set  used  for  the  file transfer and chooses, if necessary, a com-
  460.  patible character set for file storage.  Table 1-1  shows  the  currently  sup-
  461. 11.3. Program Operation                                                   Page 9
  462. 0-------------------------------------------------------------------------------
  463.  ported  list  of  character  sets.    As with any automatic operation, Kermit's
  464.  honoring of the transmitted attributes may need to be suppressed in part or al-
  465.  together, and the SET ATTRIBUTE subcommand provides this capability.
  466. 0Another  attribute  that  Kermit-370 supports is file disposition, which allows
  467.  files to be received and immediately retransmitted as electronic mail, sent  to
  468.  a  printer,  or  submitted  as  a  batch  job.   These three options are highly
  469.  site-specific and are implemented as a set of three host commands with  similar
  470.  calling  sequences.  In each case, the command is invoked in two different ways
  471.  in the process of processing the file.  It is called without  any  filespec  or
  472.  other  options  as  soon  as  the  corresponding  attribute  is  recognized  by
  473.  Kermit-370.  If the command is not implemented or for  some  reason  returns  a
  474.  non-zero  completion code (such a code should be negative, if at all possible),
  475.  Kermit-370 rejects the file using  the  normal  attribute  exchange  mechanism.
  476.  Otherwise,  the  file is received as usual, and the command is invoked again at
  477.  the end-of-file.  The second time,  the  command  is  given  the  name  of  the
  478.  received  file  and  the  options received from the sending Kermit (such as the
  479.  list of recipients for electronic mail).  The command is then  responsible  for
  480.  disposing  of  the file (and deleting it, if desired).  If, for any reason, the
  481.  file cannot be sent as required, the command should return a  negative  comple-
  482.  tion  code  (or  non-zero, at any rate), and Kermit-370 will send back an error
  483.  message to the sending Kermit.  The command itself should refrain from  issuing
  484.  any  messages  of  its own or permitting commands that it invokes to issue mes-
  485.  sages.  See the beginning of the chapter  on  the  system-specific  variant  of
  486.  Kermit-370  for  the exact command syntax.  Some sample implementations of such
  487.  commands  may  be  available  in  the  Kermit  distribution  --  refer  to  the
  488.  system-specific installation guide for a list of samples.
  489. 0
  490.  1.4. Kermit-370 Subcommands
  491. 0The  following is a summary of Kermit subcommands.  The starred subcommands can
  492.  be issued as remote Kermit commands to Kermit-370 when it is  in  server  mode.
  493.  System-specific subcommands are omitted from this list.
  494. 0          BYE      logs out other Kermit server.
  495.            CWD*     establishes a new working directory.
  496.      DIRECTORY      displays all or part of the disk directory.
  497.           ECHO      a line back to the user.
  498.           EXIT      from Kermit-370.
  499.         FINISH      other Kermit server.
  500.            GET      file(s) from a Kermit server.
  501.           GIVE*     creates a TAKE file snapshot of a table.
  502.           HELP      about Kermit-370.
  503.           HOST*     executes a system command.
  504.         KERMIT*     executes a Kermit subcommand.
  505.           QUIT      from Kermit-370.
  506.        RECEIVE      file(s) from other Kermit.
  507.           SEND      file(s) to other Kermit.
  508.         SERVER      mode of remote operation.
  509.            SET*     various parameters.
  510.           SHOW*     various parameters.
  511.          SPACE*     displays disk storage allocation.
  512.         STATUS*     inquiry.
  513.           STOP      easy escape from protocol mode.
  514.           TAKE*     subcommands from file.
  515. 11.4. Kermit-370 Subcommands                                             Page 10
  516. 0-------------------------------------------------------------------------------
  517.          TDUMP*     dumps the contents of a table.
  518.           TYPE*     a file.
  519.        VERSION*     of Kermit-370.
  520.          XECHO      echoes a line (transparently).
  521.          XTYPE      displays a file (transparently).
  522. 0Although Kermit-370 is generally a remote Kermit, it has the capability of com-
  523.  municating with another  Kermit  in  server  mode.    In  that  situation,  the
  524.  subcommand prefixes REMOTE and LOCAL refer to the Kermit server and Kermit-370,
  525.  respectively, even when Kermit-370 is, strictly speaking,  the  remote  Kermit.
  526.  To  help  avoid  confusion,  this  chapter will often use the term "foreign" to
  527.  apply to the Kermit at the other end from Kermit-370.  All  the  above  subcom-
  528.  mands may be preceded by the LOCAL prefix, but only certain ones are valid with
  529.  REMOTE, including some not shown here.  See the description of the SERVER  sub-
  530.  command  for details.  Any text replies Kermit-370 gets from the foreign Kermit
  531.  server  are  added  to  a  disk   file   (whose   filespec   is,   of   course,
  532.  system-dependent).    Such a transaction can be carried out, for example, under
  533.  control of a TAKE file if Kermit-370 is not operating locally.   If  the  local
  534.  Kermit  has  a "magic" character sequence that switches it from terminal emula-
  535.  tion to server mode, then an  entire  session  could  be  controlled  from  the
  536.  mainframe,  possibly  in  response  to a single command issued by a naive user.
  537.  For example,
  538. 0  .grab
  539. 0       Kermit-370 is invoked and executes the following TAKE file
  540. 0  ECHO Serve Me!        the local Kermit switches to server mode
  541.    GET file.a            the server uploads file.a
  542.    FINISH                the server switches back to terminal mode
  543. 0The remainder of this section describes subcommands with special meaning or use
  544.  in  Kermit-370, except the highly system-dependent ones.  For the latter, refer
  545.  to the appropriate chapter.  Subcommands are listed in alphabetical order.
  546. 0
  547.                          THE ECHO AND XECHO SUBCOMMANDS
  548. 0Syntax: [X]ECHO line
  549. 0These subcommands type the line back at the user.  The line may contain control
  550.  characters  or  any desired text, including upper or lower case.  These subcom-
  551.  mands may be used, for example, to test the ASCII/EBCDIC translate tables or to
  552.  issue coded commands to the user's terminal.  XECHO differs from ECHO primarily
  553.  in that it sends the text as a raw transmission according to the  current  CON-
  554.  TROLLER setting.  Thus, XECHO will, if necessary, break the text into pieces no
  555.  larger than the current SEND PACKET-SIZE and will use transparent mode if  CON-
  556.  TROLLER  is  SERIES1,  GRAPHICS  or  AEA.    It  also  offers  its own brand of
  557.  control-character quoting, using the "^" character to indicate  that  only  the
  558.  five  low-order  bits of the ASCII codes are to be used.  Thus, "^a", "^A", and
  559.  "^!" are all translated to SOH (CTRL-A), while  "^["  becomes  ESC.    However,
  560.  there  must  be one exception for "^" itself: "^>" and "^~" are both translated
  561.  to RS (CTRL-^), but "^^" becomes just "^".  XECHO also decodes 8th-bit quoting,
  562.  just as in Kermit protocol, and this feature can be disabled by setting 8th-bit
  563.  quoting off.  For example, if the 8th-bit quote character is "&", entering  the
  564.  subcommand  "XECHO &A" will transmit a code x'C1', but the same subcommand with
  565. 11.4. Kermit-370 Subcommands                                             Page 11
  566. 0-------------------------------------------------------------------------------
  567.  quoting off will transmit two bytes: x'2641'.
  568. 0
  569.                                THE GET SUBCOMMAND
  570. 0Syntax: GET [foreign-filespec [filespec]]
  571. 0The GET subcommand tells Kermit to request a file or file group from the  other
  572.  system,  which  must  have a Kermit running in server mode.  Provided the other
  573.  Kermit complies, the effect is the same as if SEND  foreign-filespec  had  been
  574.  issued  directly  to the other Kermit and RECEIVE [filespec] to Kermit-370.  If
  575.  this subcommand is issued without any arguments,  Kermit-370  will  prompt  the
  576.  user  for  both  foreign  and  native filespecs (and will insist on getting the
  577.  former, but will do without the latter).  See the respective SEND  and  RECEIVE
  578.  subcommands for a description of the each filespec.
  579. 0
  580.                                THE GIVE SUBCOMMAND
  581. 0Syntax: GIVE table-name filespec
  582. 0This compares the named translation or selection table with its current default
  583.  values and saves the differences in the form of a TAKE file consisting  of  SET
  584.  subcommands that would convert the default into the current arrangement.  ATOE,
  585.  ETOA, TATOE, and TETOA are the available translation tables,  and  CONTROL-CHAR
  586.  is  the selection table.  The details of the filespec are system-dependent, but
  587.  those details will, in general, be the same as for the TAKE subcommand  (q.v.).
  588.  In  the  case of tables ATOE and ETOA, the current defaults are the values from
  589.  the most recent character-set definition, if any, but the  defaults  for  TATOE
  590.  and  TETOA always remain at the initial values.  See the SET FILE CHARACTER-SET
  591.  and SET TRANSFER CHARACTER-SET subcommands for more details.
  592. 0
  593.                               THE HINTS SUBCOMMAND
  594. 0Syntax: HINTS
  595. 0This subcommand produces a screenful of suggestions for Kermit  operation,  in-
  596.  cluding warnings about any current settings that may be undesirable.
  597. 0
  598.                                THE HOST SUBCOMMAND
  599. 0Syntax: HOST text of command
  600. 0This  issues  a  command  to the host operating system from Kermit-370.  When a
  601.  command returns a  non-zero  completion  code,  the  code  will  be  displayed.
  602.  Generally,  the  name of the system (e.g., CMS) is treated as a synonym for the
  603.  HOST subcommand.
  604. 0When Kermit-370 is in (non-local) server mode, you must avoid  sending  it  any
  605.  HOST  commands  that  trigger full-screen terminal I/O, since the server-client
  606.  interface  does  not  provide  any  full-screen  terminal  emulation,  nor   is
  607.  Kermit-370 usually able to intercept such I/O in any case.
  608. 11.4. Kermit-370 Subcommands                                             Page 12
  609. 0-------------------------------------------------------------------------------
  610.                               THE KERMIT SUBCOMMAND
  611. 0Syntax: KERMIT text of subcommand
  612. 0This  is  provided  for  redundancy  as the counterpart of the HOST subcommand.
  613.  Kermit-370 executes the specified text as a Kermit subcommand just  as  if  the
  614.  LOCAL prefix had been entered.  Note, however, that the specified text must not
  615.  begin with a second KERMIT prefix.
  616. 0
  617.                              THE RECEIVE SUBCOMMAND
  618. 0Syntax: RECEIVE [filespec]
  619. 0The RECEIVE subcommand tells Kermit-370 to accept a file or file  group.    The
  620.  user  must  issue  the corresponding SEND subcommand to the other Kermit.  When
  621.  files are received, their names are recorded in a transaction log in memory and
  622.  may be viewed later via the TDUMP NAMES subcommand.  The log contains the names
  623.  along with the file sizes and any relevant error messages.  Another form of log
  624.  may  be provided through an accounting exit routine, which is called at the end
  625.  of every RECEIVE session.  Such an accounting log may contain elapsed time  and
  626.  numbers of bytes sent, received, and transferred to/from disk.  If an error oc-
  627.  curs during the file transfer, as much of the file as was received is saved  on
  628.  disk.    If,  however,  the  sending  of a file is cancelled by the user of the
  629.  foreign system, Kermit-370 will discard whatever had arrived, unless FILE  COL-
  630.  LISION is APPEND or INCOMPLETE is KEEP.
  631. 0Kermit-370  has a context-dependent maximum record length, and received records
  632.  longer than that will be folded or truncated to the proper  length;  when  this
  633.  happens,  Kermit  may  or  may  not  stop,  depending  on the FILE subparameter
  634.  LONGLINE.  If truncation does occur, Kermit will later note the fact as an  er-
  635.  ror (unless something more serious happens in the meantime).  In addition, when
  636.  a fixed record length is specified, received records are padded to the  correct
  637.  length.   The padding character is a blank for text files and a null for binary
  638.  files.  Received binary (but not V-binary or D-binary)  files  are  treated  as
  639.  byte streams and broken up into records all of the logical record length, i.e.,
  640.  folded.  For more details on the RECEIVE subcommand syntax and  operation,  see
  641.  the  chapter  on  the  desired system-specific variant of Kermit-370 under both
  642.  RECEIVE and SET FILE.  See also (in this chapter) the SET FILE LONGLINE subcom-
  643.  mand for details on record truncation and folding.
  644. 0
  645.                                THE SEND SUBCOMMAND
  646. 0Syntax: SEND [filespec[<options>] [foreign-filespec]][, ...]
  647. 0The  SEND subcommand tells Kermit-370 to send a file or file group to the other
  648.  (foreign) Kermit.  If no such file exists, Kermit-370 simply displays an  error
  649.  message  and issues another prompt.  Like RECEIVE, SEND keeps a transaction log
  650.  of all files transferred in a group and calls the accounting  exit  routine  at
  651.  the  end  of  the session.  If this subcommand is issued without any arguments,
  652.  Kermit-370 will prompt the user for both native and foreign filespecs (and will
  653.  insist  on getting the former, but will do without the latter).  Either with or
  654.  without prompting, SEND allows specifying a list of up to  13  files  (or  file
  655.  groups)  separated  by  commas.    (By  ending  the  command line or subsequent
  656.  response with a comma, the user ensures further prompting.)   In  this  syntax,
  657. 11.4. Kermit-370 Subcommands                                             Page 13
  658. 0-------------------------------------------------------------------------------
  659.  the  options  enclosed  in angle brackets may be regarded as part of the native
  660.  filespec.  There must be no intervening blanks.  At present, the only supported
  661.  option  is a range of line numbers within the file to be sent.  The range takes
  662.  the form [n][-[m]], where n is the number of the first line to  send  (counting
  663.  from  1),  and m is the last.  Omitting either number implies the corresponding
  664.  limit is the physical beginning or end of the file.  This  same  option  syntax
  665.  may  be  used  in some commands issued to the foreign Kermit, namely, those in-
  666.  volving filespecs in 370 form.  In particular, GET and REMOTE TYPE can use this
  667.  syntax.    Note  that  a  trailing  ">"  is used by some other Kermits, such as
  668.  MS-Kermit, to indicate redirection of the output from REMOTE commands to  disk.
  669.  In order to transmit the ">" and also prevent the redirection to disk, it would
  670.  be necessary to add an explicit redirection to the terminal, as in
  671. 0  REM TYPE filespec<n-m> > CON
  672. 0Although file transfers cannot be cancelled from the 370  side,  Kermit-370  is
  673.  capable of responding to "cancel file" or "cancel batch" signals from the local
  674.  Kermit; these are typically entered by typing CTRL-X or CTRL-Z, respectively.
  675. 0When Kermit-370 sends files using long packets (longer than 94), the throughput
  676.  is  especially  sensitive to the level of noise on the line because retries are
  677.  so time-consuming.  Therefore, Kermit-370  imposes  an  extra,  heuristic  size
  678.  limit  on  packets  when  retries  have been found necessary.  When that is the
  679.  case, after every 15 packets, Kermit  computes  the  packet  size  for  maximum
  680.  throughput   assuming   that  the  transmission  errors  were  due  to  sparse,
  681.  Poisson-distributed noise bursts.  The result of this calculation is then  used
  682.  as  another  limit on the size of outgoing packets besides the one specified by
  683.  the other Kermit.  If no retries are required, then Kermit-370 assumes the line
  684.  to  be  noiseless  and sends packets of the maximum length the other Kermit al-
  685.  lows.  The algorithm is explained in Kermit News V. 3 #1.  For more details  on
  686.  the  SEND  subcommand  syntax  and  operation,  see  the chapter on the desired
  687.  system-specific variant of Kermit-370.
  688. 0
  689.                               THE SERVER SUBCOMMAND
  690. 0Kermit-370 is capable of acting as a server.  In server  mode,  Kermit-370  can
  691.  send and receive files, execute host commands, execute a restricted set of Ker-
  692.  mit subcommands, and perform a variety of generic Kermit functions.   The  fol-
  693.  lowing list shows the typical local Kermit commands along with the server func-
  694.  tions they elicit.  When Kermit-370 is talking to  another  Kermit  running  in
  695.  server mode, these same subcommands may be used in the other direction.
  696. 0BYE                 log out the Kermit server.
  697.  FINISH              server mode.
  698.  GET                 a file or files from the server.
  699.  REMOTE
  700.    COPY              a file or files.
  701.    CWD               set new working directory.
  702.    DELETE            a file or files.
  703.    DIRECTORY         display file attributes.
  704.    HELP              display a command summary, such as this.
  705.    HOST              execute a system command.
  706.    KERMIT            execute a Kermit-370 subcommand.
  707.    PRINT             send a file to be printed by the server.
  708.    RENAME            a file or files.
  709. 11.4. Kermit-370 Subcommands                                             Page 14
  710. 0-------------------------------------------------------------------------------
  711.    SPACE             display disk space.
  712.    TYPE              a file.
  713.  SEND                a file or files to the server.
  714. 0If  your  local Kermit does not support the REMOTE KERMIT command, you may need
  715.  to issue SET subcommands to select various options  before  typing  the  SERVER
  716.  subcommand.    Once  in server mode, Kermit-370 will await all further instruc-
  717.  tions from the client Kermit on the other end of the connection until a  FINISH
  718.  or BYE command is given.
  719. 0Command  execution  in  server  mode  is different in some respects from normal
  720.  operation.  First of all, some Kermit subcommands are not allowed (see the list
  721.  at  the  beginning of this section).  Moreover, command errors always terminate
  722.  any active TAKE file.  Also, all commands will be run in the  special  environ-
  723.  ment that Kermit sets up during protocol transfers.  Among other things, Kermit
  724.  intercepts all terminal I/O (if possible)  in  this  environment  in  order  to
  725.  transmit the data to the local Kermit as text packets.
  726. 0Note  that  some operations can be requested by several different commands.  If
  727.  for example, the IBM 370 system has a command "PRT" for displaying  a  file,  a
  728.  user  interacting  with a Kermit-370 server can choose to display a file by is-
  729.  suing any of the commands: REMOTE TYPE, REMOTE HOST PRT,  REMOTE  KERMIT  TYPE,
  730.  REMOTE  KERMIT HOST PRT, or (if SYSCMD has been set ON) REMOTE KERMIT PRT.  The
  731.  first form simply transfers the requested file as text, but the  others  invoke
  732.  the  "PRT"  command  with any specified options, intercept the terminal output,
  733.  and return the results to the local Kermit.  The first  form  is  also  distin-
  734.  guished  by the fact that the line range may be specified in the same manner as
  735.  in the SEND subcommand.  The syntax of the others is system-dependent.
  736. 0
  737.                                THE SET SUBCOMMAND
  738. 0Syntax: SET parameter [value]
  739. 0The SET subcommand establishes or modifies various parameters controlling  file
  740.  transfers.    The  values  can,  in turn, be examined with the SHOW subcommand.
  741.  Some parameters have two levels.  In particular, there are two  matching  lists
  742.  of  SEND  and  RECEIVE  sub-parameters corresponding to the values exchanged by
  743.  Kermits in the Send-Init/ACK sequence.  For each of  these  SEND/RECEIVE  pairs
  744.  one  element is encoded in outgoing parameter packets, and the other is decoded
  745.  from incoming ones.  Setting the latter by hand may be needed to establish con-
  746.  tact  and also has the effect of redefining the default value for decoding from
  747.  subsequent parameter packets.  Generally,  the  distinction  between  SEND  and
  748.  RECEIVE  parameters  is  unambiguous,  the only exception being TIMEOUT (q.v.).
  749.  The following SET subcommands are available in Kermit-370:
  750. 0ATOE                Modify the Kermit-370 ASCII-to-EBCDIC table.
  751.  ATTRIBUTE           Determine A-packet generation.
  752.  BLOCK-CHECK         Level of error checking for file transfer.
  753.  CONTROLLER          Indicate type of terminal connection.
  754.  CONTROL-CHAR        Set prefixing state.
  755.  DEBUG               Log packet traffic during file transfer.
  756.  DELAY               Length of pause before a SEND subcommand.
  757.  EOF                 Text file truncation at CTRL-Z.
  758.  ETOA                Modify the Kermit-370 EBCDIC-to-ASCII table.
  759.  FILE                Attributes for incoming or outgoing files...
  760. 11.4. Kermit-370 Subcommands                                             Page 15
  761. 0-------------------------------------------------------------------------------
  762.    CHARACTER-SET     ... for 370 storage.
  763.    COLLISION         ... treatment for duplicate names.
  764.    LONGLINE          ... treatment of too-long records.
  765.    OVERWRITE         ... treatment of attributes.
  766.    TYPE              ... text or binary.
  767.    other             ... system-specific attributes.
  768.  FOREIGN             Strings added to outgoing filespec...
  769.    PREFIX
  770.    SUFFIX
  771.  INCOMPLETE          Determine the action on an aborted file transfer.
  772.  LINE                Specify alternate communication line.
  773.  MARGIN              for sending files...
  774.    LEFT
  775.    RIGHT
  776.  PROMPT              For Kermit-370 subcommands.
  777.  RETRY               Maximum retry count...
  778.    INIT              ... for initial packet exchange.
  779.    PACKET            ... per packet for ongoing transfer.
  780.  SERVER-TIMEOUT      Spacing between server NAK's.
  781.  SPEED               Line speed for packet-size calculations.
  782.  SYSCMD              Try apparently invalid Kermit subcommands on host system.
  783.  TABS-EXPAND         Determine tab-to-space conversion on reception.
  784.  TAKE
  785.    ECHO              Echo subcommands read from TAKE files.
  786.    ERROR-ACTION      Exit from TAKE file on command error.
  787.  TEST                Facilitate testing of Kermit.
  788.  TATOE               Modify the Kermit-370 ASCII-to-EBCDIC table.
  789.  TETOA               Modify the Kermit-370 EBCDIC-to-ASCII table.
  790.  TRANSFER            Options for transmission...
  791.    CHARACTER-SET     ... of text files.
  792.    LOCKING-SHIFT     ... protocol extension.
  793.  TTABLE              Determine which tables undo the terminal translation.
  794.  8-BIT-QUOTE         Determine state of 8th-bit prefixing.
  795.  SEND or RECEIVE
  796.    END-OF-LINE       Packet terminator.
  797.    PACKET-SIZE       Maximum packet size.
  798.    PAD-CHAR          Character to insert before each packet.
  799.    PADDING           Number of pad characters to insert.
  800.    PARITY            Indicate if 7-bit or 8-bit data.
  801.    QUOTE             Use to quote control characters in packets.
  802.    START-OF-PACKET   Packet beginning marker.
  803.    TIMEOUT           Time limit for response.
  804. 0
  805.  SET ATOE etc.
  806. 0Syntax: SET table [num1 num2]
  807. 0This modifies one of the ASCII/EBCDIC translation  tables  used  by  Kermit-370
  808.  (for  example,  to  conform  to  your system).  The valid table names are ATOE,
  809.  ETOA, TATOE, and TETOA.  The arguments are, respectively, the offset within the
  810.  named  table  and the new value for that offset.  If the arguments are omitted,
  811.  the table is restored to its initial arrangement.  Both num1 and num2 should be
  812.  in the range 0-255 (decimal).  For example, in ATOE or TATOE, the offset is the
  813.  ASCII character code, and the new value is the new EBCDIC  result  code.    In-
  814.  itially,  ATOE  and  TATOE each contain two identical copies of the 7-bit ASCII
  815. 11.4. Kermit-370 Subcommands                                             Page 16
  816. 0-------------------------------------------------------------------------------
  817.  character table.  Helpful hint: if you have files that  make  use  of  extended
  818.  (8-bit)  ASCII  codes and wish to upload them via Kermit-370, be sure to define
  819.  unique EBCDIC equivalents of all the needed 8-bit ASCII  codes  or  else  treat
  820.  such  files  as binary data.  Any time you use the SET ATOE or SET ETOA subcom-
  821.  mands, that has a side effect equivalent to SET ATTRIBUTE ENCODING OFF  (q.v.).
  822.  If the extended ASCII character set is one of those supported for file transfer
  823.  in Kermit-370, you need only issue a SET TRANSFER CHARACTER-SET (q.v.).
  824. 0Note: the meaning of the tables depends on the TTABLE setting -- if  TTABLE  is
  825.  OFF, the TATOE and TETOA tables are not used.
  826. 0
  827.  SET ATTRIBUTE
  828. 0Syntax: SET ATTRIBUTE [attribute] ON or OFF
  829. 0The  individual  attributes  are  LENGTH,  TYPE,  DATE, CREATOR, ACCOUNT, AREA,
  830.  PASSWORD, BLOCKSIZE, ACCESS, ENCODING, DISPOSITION,  PROTECT,  ORIGIN,  FORMAT,
  831.  SYS-INFO,  and  BYTE-LENGTH.  Kermit-370 distinguishes between the two forms of
  832.  this subcommand by counting "words".  In order to see the list of supported at-
  833.  tributes, you must enter "SET ATTR ? ?"; if you enter just "SET ATTR ?", Kermit
  834.  will list just the alternatives ON and OFF.
  835. 0ON      The specified attribute is to be processed, or  attribute  packets  are
  836.          generated  for  all outgoing files, provided the other Kermit indicates
  837.          the ability to accept them.  (Default).
  838. 0OFF     The specified attribute is to be ignored  and  not  generated,  or  at-
  839.          tribute packets are never generated.
  840. 0
  841.  SET BLOCK-CHECK
  842. 0Syntax: SET BLOCK-CHECK type
  843. 0This determines the type of block check used during file transfer, provided the
  844.  other Kermit agrees.  Valid options for type are:  1-byte (for a  one-character
  845.  checksum), 2-byte (for a two-character checksum), 3-byte (for a three-character
  846.  CRC), and Blank-free-2 (for a shifted two-character checksum that avoids  using
  847.  blanks.    This  is  one  of  only  two Send-Init parameters that cannot be SET
  848.  separately for SEND and RECEIVE.
  849. 0
  850.  SET CONTROLLER
  851. 0Syntax: SET CONTROLLER type
  852. 0The type may be TTY, SERIES1, GRAPHICS,  AEA,  FULLSCREEN,  VTAMTTY,  or  NONE.
  853.  Kermit-370  automatically  determines  whether you are connected via a Series/1
  854.  (or similar) emulation controller or a TTY line.  In some  circumstances,  such
  855.  as when the connection is through a non-graphics-capable 3174 port, Kermit will
  856.  set CONTROLLER to NONE, which has the effect of disabling file transfers.  This
  857.  subcommand is provided, though, to allow the automatic choice to be superseded,
  858.  and because Kermit may not be able to  distinguish  between  Series/1-type  and
  859.  other  3270-emulation  controllers.   In particular, there is no way to distin-
  860.  guish between FULLSCREEN and GRAPHICS from within Kermit.  When  CONTROLLER  is
  861. 11.4. Kermit-370 Subcommands                                             Page 17
  862. 0-------------------------------------------------------------------------------
  863.  set  to SERIES1, GRAPHICS, or AEA, Kermit disables the 3270 protocol conversion
  864.  function by putting the terminal controller into "transparent mode", which  al-
  865.  lows Kermit packets to pass through intact.  Note: an incorrect CONTROLLER set-
  866.  ting may lock up or wipe out your session when you try to transfer files.
  867. 0Kermit operation is possible through an IBM 3708  front  end,  but  only  in  a
  868.  rather  specific configuration.  See the installation guide for your variant of
  869.  Kermit-370 for the details of that and other hardware-related restrictions  and
  870.  configurations.
  871. 0
  872.  SET CONTROL-CHAR
  873. 0Syntax: SET CONTROL-CHAR mode [number]
  874. 0The mode may be PREFIXED (normal Kermit protocol for control characters) or UN-
  875.  PREFIXED.  In the latter case, the specified  control  character  (given  as  a
  876.  decimal  number  in  the range 0-31 or 128-159) is transmitted "as is".  If the
  877.  number is omitted, then all control characters are set accordingly.  Kermit-370
  878.  automatically  overrides  the  user's  settings for certain characters used for
  879.  Kermit protocol: the start-of-packet,  the  end-of-packet,  the  handshake  (if
  880.  set),  and  XOFF (not really used, but too dangerous to send).  Sending control
  881.  characters without prefixes can speed up transfers of binary files.
  882. 0The status of prefixing is initially "PREFIXED" for all control characters.  It
  883.  can  be  displayed  by  the TDUMP CONTROL subcommand, or saved in the form of a
  884.  TAKE file by the GIVE CONTROL subcommand (q.v.).
  885. 0
  886.  SET DEBUG
  887. 0Syntax: SET DEBUG OFF or ON [RAW] [I/O] [SAVE] [LONG] [TIME]
  888. 0Note: any combination, in any order, of RAW, I/O, SAVE, and TIME may follow  or
  889.  replace ON.  Each of the three implies ON.
  890. 0ON      Keep  a journal of all packets sent and received in a log file on disk.
  891.          If the file already exists, it is erased and overwritten.  The filespec
  892.          of  the log is, of course, system-dependent.  All packets are logged in
  893.          EBCDIC  for  legibility,  even  when  CONTROLLER  is  set  to  SERIES1,
  894.          GRAPHICS, or AEA.
  895. 0RAW     The same as ON, but packets are logged in the form that is passed to or
  896.          from the operating system, i.e., EBCDIC for TTY or  VTAMTTY  terminals,
  897.          and  ASCII  for  SERIES1,  GRAPHICS, and AEA terminals.  This option is
  898.          generally not recommended; I/O is preferable.
  899. 0I/O     The same as ON, but the log includes additional transmission status in-
  900.          formation, such as the AID returned by a full-screen device.  See below
  901.          for a summary of the log formats.
  902. 0SAVE    The same as ON, but the log file is closed after each entry  is  added,
  903.          so  that, if the session is abnormally terminated, the log file will be
  904.          complete and readable.
  905. 0LONG    The same as I/O, but the additional information is not truncated to  36
  906. 11.4. Kermit-370 Subcommands                                             Page 18
  907. 0-------------------------------------------------------------------------------
  908.          bytes.
  909. 0TIME    Used  only  with I/O or LONG.  The lines of hexadecimal dump are tagged
  910.          with the time of day from the  CPU  clock,  truncated  to  the  nearest
  911.          second.
  912. 0OFF     Stop logging packets and close the the log file.  (Default.)
  913. 0Often,  problems  with  Kermit  file transfers or server-mode operations can be
  914.  diagnosed by setting DEBUG on in one or both Kermits, regardless of  where  the
  915.  problems  actually  lie.  For Kermit-370, the maximum amount of information can
  916.  generally be obtained by setting DEBUG to I/O or LONG, but the  format  of  the
  917.  log  depends  somewhat  on which variant of Kermit-370 is involved.  Before ex-
  918.  amining the log, you should set DEBUG OFF either explicitly or by exiting  from
  919.  Kermit-370.
  920. 0There  is  an  optional feature for logging dumps of storage blocks at selected
  921.  points in the execution.  By default, this feature  is  disabled  (at  assembly
  922.  time) by having the variable symbol &KTRACE set to NO and also by virtue of the
  923.  fact that no calls to the dump routine are present in  the  distribution  code.
  924.  Further, the dumps are suppressed unless both DEBUG and TEST (q.v.) are set on.
  925.  To select when and what blocks to dump, it is  necessary  to  insert  calls  to
  926.  KHDMP  at  appropriate  points in the source before assembling.  Each such call
  927.  generates a dump each time it is executed, provided that  DEBUG  and  TEST  are
  928.  set,  and  the contents of all registers are preserved.  The call specifies the
  929.  starting address, the length, and a short title for  the  block.    Only  eight
  930.  characters of the title will be used.  Some examples:
  931. 0            KHDMP ATOE+128,128,'ATOEhigh'
  932.                            Dump the 2nd half of the ATOE table.
  933. 0            KHDMP KHDSAV,20,'R14 - R2'
  934.                            Dump registers 14-2.
  935. 0            KHDMP 32(,13),40,'**R3-R12'
  936.                            Dump registers 3-12.
  937. 0            KHDMP (3),(0),'**QBLOCK'
  938.                            Dump  block  addressed by R3 with length specified in
  939.                            R0.
  940. 0There is another debugging facility that is  enabled  by  the  variable  symbol
  941.  &KTRACE  along  with  the  dump option, namely, an execution trace.  There is a
  942.  circular buffer of trace elements in Kermit's working storage, and a  new  ele-
  943.  ment  is  written each time a Kermit subroutine is called or returns.  The ele-
  944.  ments contain the subroutine name plus (on entry) a  sequence  number  and  the
  945.  contents  of  registers 0 and 1 or (on exit) the character ">" and the contents
  946.  of registers 15 and 1.  There is also a mechanism for tracing extra  events  by
  947.  inserting KTRACE calls into the source.  For example,
  948. 0            KTRACE 0(5),REGS=5
  949.                            Trace eight bytes pointed to by R5 and R5 itself.
  950. 0            KTRACE FOOBAR Trace eight bytes at label FOOBAR.
  951. 0            KTRACE 'Found it',REGS=(1,7)
  952. 11.4. Kermit-370 Subcommands                                             Page 19
  953. 0-------------------------------------------------------------------------------
  954.                            Trace "Found it", R1, and R7.
  955. 0The  trace  table is simply updated in storage, eating its own tail.  It can be
  956.  found in a memory dump by locating the "eye-catcher" that says "KTRACE:", which
  957.  precedes the start, current, and end pointers for the table.  The table is also
  958.  accessible interactively via the TDUMP subcommand (q.v.).
  959. 0Each line in the debug log begins with a one-letter tag and a  colon  and  con-
  960.  tains information according to the tag.  The following tags are defined.
  961. 0S:  The text of a packet sent.  Normally, it will be encoded in EBCDIC for con-
  962.      venience, but if DEBUG is set to RAW, the packet  will  appear  exactly  as
  963.      passed  to or from the system, i.e., in EBCDIC for TTY or VTAMTTY lines and
  964.      in ASCII for full-screen lines.
  965. 0R:  The text of a packet received.  The same encoding applies.
  966. 0A:  The AID and buffer address returned by a full-screen device  along  with  a
  967.      read  operation (three characters in all).  The values should all be print-
  968.      able EBCDIC.  This obsolete tag was used by TSO and MUSIC Kermits  and  ap-
  969.      peared only when DEBUG was set to I/O.
  970. 0*:  Data dumped by the optional KHDMP routine.
  971. 0The  following  tags  appear only when DEBUG is set to I/O or LONG.  All values
  972.  are in hexadecimal.  The meanings differ slightly according  to  the  operating
  973.  system.   For CMS, the I/O parameter list is a channel command; for TSO or ROS-
  974.  COE, the SVC 93  (TPUT/TGET)  parameters;  for  CICS,  an  intermediate  string
  975.  similar  to channel commands.  Similarly, the status data consist of the stored
  976.  CSW plus an attention interrupt indicator for CMS, but the return code from the
  977.  I/O operation for TSO, ROSCOE, CICS, and MUSIC.
  978. 0a:  Channel and device status after an unexpected attention interrupt.
  979. 0b:  I/O parameter list for recovering from a CP break-in on screen.
  980. 0c:  I/O parameter list for resuming normal screen operation.
  981. 0d:  Data transferred on the previously indicated I/O operation.
  982. 0e:  Status data after an I/O command has completed with an error.
  983. 0g:  I/O parameter list for reading from the screen buffer.
  984. 0i:  Status data after an I/O command has completed normally.
  985. 0m:  I/O parameter list for displaying text on the screen.
  986. 0o:  I/O parameter list for initializing the screen for transfers.
  987. 0r:  I/O parameter list for reading from the terminal.
  988. 0w:  I/O parameter list for a transparent write.
  989. 0?:  I/O parameter list for some other operation, such as clearing the screen.
  990. 11.4. Kermit-370 Subcommands                                             Page 20
  991. 0-------------------------------------------------------------------------------
  992.  SET DELAY
  993. 0Syntax: SET DELAY number
  994. 0Normally, Kermit-370 waits 10 seconds after the SEND subcommand before starting
  995.  the transfer, but this delay may be set to any non-negative value.   Two  DELAY
  996.  values have special meaning.  When DELAY is 1, the usual two-line greeting dis-
  997.  played during protocol mode is abbreviated to a short message (the default Ker-
  998.  mit prompt with three dots...), and when DELAY is 0, the greeting is suppressed
  999.  entirely, along with the extra one-second pause for subcommands  like  RECEIVE,
  1000.  SERVER, REMOTE, and the like.
  1001. 0
  1002.  SET EOF
  1003. 0Syntax: SET EOF ON or OFF
  1004. 0ON      Scan each incoming TEXT file for the first occurrence of CTRL-Z and ig-
  1005.          nore the remainder of the file (but continue decoding up to the  actual
  1006.          end of the file).  BINARY files are not affected.
  1007. 0OFF     Accept incoming files in their entirety.  (Default.)
  1008. 0
  1009.  SET FILE CHARACTER-SET
  1010. 0Syntax: SET FILE CHARACTER-SET name
  1011. 0Specifies  the  name  of  the character set used in files stored on disk.  This
  1012.  setting may be superseded by an Attribute packet of an  incoming  file.    Cur-
  1013.  rently,  the  available  names  are  CP037,  CP273, CP275, CP277, CP278, CP280,
  1014.  CP281, CP282, CP284, CP285, CP290, CP297, CP420, CP424,  CP500,  CP838,  CP870,
  1015.  CP871,  CP875,  CP880,  CP905,  CP1047, CZECH, DKOI, EBCDIC, H-EBCDIK-DASH, and
  1016.  KANJI (or FUJITSU-KANJI, HITACHI-KANJI, or IBM-KANJI).    The  names  beginning
  1017.  with  CP  refer  to  IBM  code  pages, while DKOI is the Cyrillic standard GOST
  1018.  19768-87 used in the USSR, CZECH is a character set sometimes used in  Czechos-
  1019.  lovakia,  and  EBCDIC (the default) is the traditional de facto standard EBCDIC
  1020.  character set.  A character set other than the default may be required by local
  1021.  conventions  and,  if so, should be specified in the system or user INIT files.
  1022.  See Table 1-1 for the allowed combinations of transfer and file character sets.
  1023.  Explicitly  setting this option has a side effect equivalent to issuing SET AT-
  1024.  TRIBUTE ENCODING ON (q.v.).
  1025. 0The name KANJI is actually just an alias for the  local  preferred  proprietary
  1026.  Kanji  code  (Fujitsu, Hitachi, or IBM).  The various Kanji character sets have
  1027.  two-byte codes (DBCS), but are used with one-byte code pages  (SBCS)  as  well.
  1028.  It is normally necessary to issue two SET FILE CHARACTER-SET SUBCOMMANDS in or-
  1029.  der to set up for a DBCS: first, selecting  a  compatible  SBCS,  and,  second,
  1030.  selecting  the  DBCS  itself.    If  the  current SBCS is incompatible with the
  1031.  selected DBCS, a default will be chosen.  This default, along with  the  choice
  1032.  of the particular proprietary character set associated with the alias KANJI, is
  1033.  chosen by the installer.
  1034. 11.4. Kermit-370 Subcommands                                             Page 21
  1035. 0-------------------------------------------------------------------------------
  1036.  SET FILE COLLISION
  1037. 0Syntax: SET FILE COLLISION action
  1038. 0Specifies the action to take when an incoming file has the same name as an  ex-
  1039.  isting  one.    Two of the options involve choosing an alternative, unique name
  1040.  similar  to  the  one  in  conflict,  but   the   details   of   choosing   are
  1041.  system-specific.   Typically, the method involves adding digits to the existing
  1042.  name.
  1043. 0APPEND       The new file is appended to the old one.  This option has the  the
  1044.               same effect as the old subcommand SET APPEND ON.
  1045. 0BACKUP       The  existing  file  is  renamed,  and  the  new file is given the
  1046.               desired name as if no conflict had occurred.
  1047. 0DISCARD      The incoming file is rejected by returning a "cancel file" indica-
  1048.               tion on any Data packets.
  1049. 0OVERWRITE    The  existing file is overwritten with the incoming file.  This is
  1050.               the default for the CMS, TSO, ROSCOE, and MUSIC variants.   Chang-
  1051.               ing  this  default  is a good candidate for INIT files.  When COL-
  1052.               LISION is set to OVERWRITE, the attributes of  the  new  file  are
  1053.               determined by the current setting of FILE OVERWRITE (q.v.).
  1054. 0RENAME       The  incoming file is renamed so as not to destroy (overwrite) the
  1055.               pre-existing one, and the new name is returned to the sending Ker-
  1056.               mit for information purposes.  This has the same effect as the old
  1057.               subcommand SET WARNING ON.  This  is  the  default  for  the  CICS
  1058.               variant.
  1059. 0
  1060.  SET FILE LONGLINE
  1061. 0Syntax: SET FILE LONGLINE FOLD or TRUNCATE or HALT
  1062. 0This  specifies the action to take when a received line is longer than the cur-
  1063.  rent maximum record length.  That length is determined  by  the  context  in  a
  1064.  system-specific way.  Refer to the description of the RECEIVE subcommand in the
  1065.  appropriate chapter for details.
  1066. 0FOLD        Specifies that long lines are to be split into two or more  records
  1067.              as  needed,  all but the last being of the maximum length.  No null
  1068.              records are created when the received line is an exact multiple  of
  1069.              the  record length.  BINARY files are always considered, by defini-
  1070.              tion, as a single line and, therefore, are always  folded,  regard-
  1071.              less  of  the  setting  of  this  parameter.  V-BINARY and D-BINARY
  1072.              files, on the other hand, are reconstructed by  folding  at  points
  1073.              determined  by  the context within the received file, and cannot be
  1074.              folded further to fit the current maximum length.  Any such records
  1075.              that are too long will be truncated.
  1076. 0TRUNCATE    Specifies  that  long  lines  are  to  be  truncated at the maximum
  1077.              length.  (Default.)  Kermit-370 takes note of the  number  of  such
  1078.              truncations  performed  on a file and reports it in the STATUS mes-
  1079.              sage and also treats the fact of truncation as an  error  when  the
  1080. 11.4. Kermit-370 Subcommands                                             Page 22
  1081. 0-------------------------------------------------------------------------------
  1082.              file  transfer  is  complete.  The file will have been transferred,
  1083.              but obviously not quite intact.  However, this option can be useful
  1084.              for  some  tasks,  such  as  stripping  sequence  numbers from card
  1085.              images.  The process is similar to that provided by the SET  MARGIN
  1086.              RIGHT subcommand for sending files.
  1087. 0HALT        Specifies that a file transfer is to halt immediately if a received
  1088.              line is too long.  Kermit-370 then issues an error packet and stops
  1089.              the transfer.
  1090. 0
  1091.  SET FILE OVERWRITE
  1092. 0Syntax: SET FILE OVERWRITE DEFAULT or PRESERVE
  1093. 0DEFAULT    Specifies  that  the  current file attribute settings are to be used
  1094.             for the new file.  The result is roughly the  same  as  if  the  old
  1095.             file,  if  any,  were  completely  erased  before  the  new  file is
  1096.             received.  (Default.)
  1097. 0PRESERVE   Specifies that the attributes of the file being overwritten  are  to
  1098.             be  retained  and  used for the new file.  The result is roughly the
  1099.             same as if the old files contents were deleted,  and  the  new  file
  1100.             were appended to the empty stub.
  1101. 0
  1102.  SET FILE TYPE
  1103. 0Syntax: SET FILE TYPE type
  1104. 0Specifies  the type of data comprising files to be sent or received.  This set-
  1105.  ting may be temporarily superseded by the Attribute packets for  a  file  being
  1106.  received.
  1107. 0TEXT       Specifies  ordinary text.  ASCII-to-EBCDIC or EBCDIC-to-ASCII trans-
  1108.             lation is performed on the data.  Trailing blanks are  removed,  and
  1109.             CRLF's  are  appended to outgoing records. CRLF's are used, in turn,
  1110.             to determine the end of incoming  records,  which  are  padded  with
  1111.             blanks  if  necessary  to  fill buffers.  (Default.)  Note: trailing
  1112.             blanks are removed from outgoing,  varying-length  records  only  if
  1113.             they  consist  of a single blank each, or if there is a right margin
  1114.             specified (q.v.).  Further  note:  a  given  file  is  intrinsically
  1115.             categorized  as fixed-length or varying-length (or undefined-length)
  1116.             by the file system and cannot be changed simply by setting the  FILE
  1117.             RECFM  parameter  in  Kermit.    Conversion  between  formats  is  a
  1118.             system-specific function; see the system  documentation  or  consult
  1119.             your local support staff for details on conversion techniques.
  1120. 0BINARY     Specifies  bit-stream  data.  No translation is performed, no CRLF's
  1121.             are added to outgoing records, and  blanks  are  neither  added  nor
  1122.             removed.    Incoming  bytes  are  added  successively to the current
  1123.             record buffer, which is  written  out  when  the  current  LRECL  is
  1124.             reached.  Padding, if necessary, is done with nulls.
  1125. 0V-BINARY   Specifies  varying-length-record binary data.  This type is like BI-
  1126.             NARY, except that a two-byte binary prefix is added to each outgoing
  1127. 11.4. Kermit-370 Subcommands                                             Page 23
  1128. 0-------------------------------------------------------------------------------
  1129.             record giving the number of data bytes, and incoming records are set
  1130.             off by (and stripped of) their prefixes on receipt.
  1131. 0D-BINARY   Is like V-BINARY except  that  the  length  prefixes  are  five-byte
  1132.             ASCII-encoded decimal (right-justified with leading zeroes).
  1133. 0
  1134.  SET FOREIGN
  1135. 0Syntax: SET FOREIGN PREFIX string
  1136. 0This  defines a prefix string to be added to the outgoing filespec generated by
  1137.  the SEND subcommand.  For example, the string might be set to "B:"  to  specify
  1138.  output to the B disk drive on the other Kermit's system.  The default is a null
  1139.  string.  There is also a FOREIGN SUFFIX handled in the same manner.
  1140. 0
  1141.  SET HANDSHAKE
  1142. 0Syntax: SET HANDSHAKE number
  1143. 0This defines the character, if any, that Kermit-370 should send (or cause to be
  1144.  sent)  immediately  before  reading each packet.  The character is given as the
  1145.  decimal of an ASCII control character, or as zero if  no  handshake  is  to  be
  1146.  sent.    The default is 17 (XON), and any value in the range 0-31 is valid, but
  1147.  13 (CR) should not be used because it is generally the end-of-packet character.
  1148.  When  Kermit-370  is  running  through  a  full-duplex  connection  (such  as a
  1149.  "SERIES1"), the traditional IBM handshaking is  not  necessary,  and  HANDSHAKE
  1150.  should be set to 0 (as long as the other Kermit can be instructed not to expect
  1151.  a handshake).  Note the distinction between SET HANDSHAKE in Kermit-370  (where
  1152.  it  defines a character to be sent) and in many micro Kermits (where it defines
  1153.  a character to be expected).
  1154. 0
  1155.  SET INCOMPLETE
  1156. 0Syntax: SET INCOMPLETE DISCARD or KEEP
  1157. 0DISCARD   Specifies that incomplete files (that is, files partially received in
  1158.            a  transfer cancelled by the other Kermit) are to be erased.  This is
  1159.            the default.  Note that when FILE  COLLISION  is  APPEND,  incomplete
  1160.            files are never erased, lest pre-existing data be lost.
  1161. 0KEEP      Specifies that incomplete files are to be kept.
  1162. 0
  1163.  SET LINE
  1164. 0Syntax: SET LINE [name]
  1165. 0This specifies an alternate communication line for file transfers.  If the name
  1166.  is omitted, the default line (the user's terminal) is used.  The format of name
  1167.  is, of course, system-dependent, and some variants of Kermit-370 do not support
  1168.  any alternate lines.  No variant currently allows Kermit-370 to CONNECT over an
  1169.  alternate line.
  1170. 11.4. Kermit-370 Subcommands                                             Page 24
  1171. 0-------------------------------------------------------------------------------
  1172.  SET MARGIN
  1173. 0Syntax: SET MARGIN side column
  1174. 0When  Kermit-370  sends  a text file, each line may be truncated on the left or
  1175.  right (or both) at fixed column numbers.  Only the text from the left margin to
  1176.  the right margin (inclusive) will be sent, and any trailing blanks in the trun-
  1177.  cated lines will be stripped.  A value of zero for either margin disables trun-
  1178.  cation on that side.
  1179. 0
  1180.  SET PROMPT
  1181. 0Syntax: SET PROMPT [string]
  1182. 0This  defines  the  character string that Kermit-370 displays when asking for a
  1183.  subcommand.  The prompt may be any string of up to 20 characters.  The  default
  1184.  is  the  name  of  the  system-specific variant of Kermit-370 followed by a ">"
  1185.  sign, e.g., Kermit-CMS>.  If the string is  omitted,  normal  system  prompting
  1186.  will occur.
  1187. 0
  1188.  SET RETRY
  1189. 0Syntax: SET RETRY INITIAL or PACKETS number
  1190. 0Kermit-370  resends its last packet after receiving a NAK or bad packet, but it
  1191.  eventually gives up after repeated failures on the same packet.  The  limit  on
  1192.  retries  can  be  set  separately for the initial packet exchange (Send-Init or
  1193.  server-mode command) and for ordinary packets.  The default for INITIAL  is  16
  1194.  and for PACKETS, 5.  Either limit can be set to any positive value.
  1195. 0
  1196.  SET SERVER-TIMEOUT
  1197. 0Syntax: SET SERVER-TIMEOUT time
  1198. 0This defines the time in seconds that Kermit-370 in server mode should wait for
  1199.  a command before sending a NAK packet.  The default is 120.  A value of 0 means
  1200.  that  Kermit  should wait indefinitely, not only in the server loop, but in all
  1201.  transfers, regardless of the timeout value specified by the other Kermit.  Some
  1202.  variants  are  unable  to  time  out  in  any case.  Also, timeouts are not im-
  1203.  plemented for any of the full-screen terminal controllers.
  1204. 0
  1205.  SET SPEED
  1206. 0Syntax: SET SPEED number
  1207. 0This determines the communication line speed assumed by Kermit-370 in calculat-
  1208.  ing  the optimum packet size.  If the value is zero, such calculations are sup-
  1209.  pressed.  This option is purely informative and has no effect  on  actual  line
  1210.  speed.  (Default 1200.)
  1211. 11.4. Kermit-370 Subcommands                                             Page 25
  1212. 0-------------------------------------------------------------------------------
  1213.  SET SYSCMD
  1214. 0Syntax: SET SYSCMD ON or OFF
  1215. 0ON      If the user enters a command string which is not a valid Kermit subcom-
  1216.          mand, Kermit-370 will pass the string along to the host operating  sys-
  1217.          tem  for  execution.   If the string is rejected by the system as well,
  1218.          Kermit will report it as an invalid Kermit subcommand.  Otherwise, Ker-
  1219.          mit  will  assume  the  string  was intended as a host command and will
  1220.          simply report the completion code if non-zero.
  1221. 0OFF     Invalid Kermit subcommands are simply rejected as such.    System  com-
  1222.          mands  may  be  executed, of course, but only by specifying the generic
  1223.          prefix "HOST" or the appropriate system-specific prefix, such as CMS or
  1224.          TSO.  (Default.)
  1225. 0
  1226.  SET TABS-EXPAND
  1227. 0Syntax: SET TABS-EXPAND ON [list] or OFF
  1228. 0ON      Tab  characters  in  incoming  TEXT  files  are replaced by one or more
  1229.          blanks to bring the record size up to the next higher multiple of eight
  1230.          for  each  tab.   If tab settings other than columns 1, 9, 17, etc. are
  1231.          desired, they may be specified  explicitly  in  a  list  following  the
  1232.          keyword  "ON".   Items in the list may be separated by spaces or commas
  1233.          and must be in strictly increasing order.
  1234. 0OFF     Incoming tabs are retained.  (Default.)
  1235. 0
  1236.  SET TAKE ECHO
  1237. 0Syntax: SET TAKE ECHO ON or OFF
  1238. 0ON      Subcommands are echoed to the terminal as they are executed from a TAKE
  1239.          file.
  1240. 0OFF     Subcommands from a TAKE file are executed "silently."  (Default.)
  1241. 0
  1242.  SET TAKE ERROR-ACTION
  1243. 0Syntax: SET TAKE ERROR-ACTION CONTINUE or HALT
  1244. 0CONTINUE   Execution  continues  in a TAKE file regardless of illegal commands,
  1245.             except in server mode.  (This is the default.)
  1246. 0HALT       A command error in a TAKE file causes immediate exit to Kermit  sub-
  1247.             command level.
  1248. 11.4. Kermit-370 Subcommands                                             Page 26
  1249. 0-------------------------------------------------------------------------------
  1250.  SET TEST
  1251. 0Syntax: SET TEST ON or OFF
  1252. 0ON      Allow  setting  the START-OF-PACKET and other special characters to any
  1253.          value, and suppress type 1 checksum testing on received packets.
  1254. 0OFF     Normal operation.  (Default.)
  1255. 0
  1256.  SET TRANSFER CHARACTER-SET
  1257. 0Syntax: SET TRANSFER CHARACTER-SET name
  1258. 0Specifies the name of the character set used in  sending  or  receiving  files.
  1259.  This  setting  may  be  superseded  by an Attribute packet of an incoming file.
  1260.  Currently, the available names  are  ASCII  (the  default),  ARABIC,  CYRILLIC,
  1261.  GREEK,  HEBREW,  JAPAN-EUC,  KATAKANA, LATIN1, LATIN2, LATIN3, THAI, and TRANS-
  1262.  PARENT.  There are also special aliases L1, L2, and L3 for  the  LATINx  names.
  1263.  All  but  JAPAN-EUC, TRANSPARENT, and ASCII represent 8-bit codes composed of a
  1264.  pair of 94- or 96-character sets from the ISO  registry  combined  with  normal
  1265.  definitions  for  the  so-called C0 and C1 characters.  JAPAN-EUC is a DBCS for
  1266.  encoding Kanji characters, plus Roman, Greek,  and  Cyrillic.    ASCII  is  the
  1267.  traditional character set supported by Kermit, but one of the newer, 8-bit sets
  1268.  would be preferable for most users.  This option is,  therefore,  a  good  can-
  1269.  didate  for  inclusion  in the system INIT file.  See Table 1-1 for the allowed
  1270.  combinations of transfer and file character sets.  Explicitly setting this  op-
  1271.  tion  has a side effect equivalent to issuing SET ATTRIBUTE ENCODING ON (q.v.).
  1272.  There is one exception,  namely,  TRANSPARENT,  which  sets  ENCODING  OFF  and
  1273.  replaces  both  translation tables with null operations, regardless of the cur-
  1274.  rent nominal file character set.
  1275. 0The biggest drawback of the built-in tables for the various character  sets  is
  1276.  that  neither  the  ISO  registry  nor  IBM  defines any mapping between the C1
  1277.  characters (hex 80-9F in ISO arrangements) and the characters  of  EBCDIC  code
  1278.  pages.  Thus, the mappings in Kermit-370 tables are somewhat arbitrary, and fu-
  1279.  ture pronouncements may suddenly invalidate some or all of those 32 mappings.
  1280. 0
  1281.  SET TRANSFER LOCKING-SHIFT
  1282. 0Syntax: SET TRANSFER LOCKING-SHIFT ON or OFF or FORCED
  1283. 0ON       The Kermit locking-shift protocol is to be used  in  transfers  to  or
  1284.           from cooperating partners, provided that 8th-bit quoting is enabled.
  1285. 0OFF      The Kermit locking-shift protocol is not to be used.
  1286. 0FORCED   The  Kermit  locking-shift  protocol  is to be used, regardless of the
  1287.           cooperation of the other Kermit.  The encoding uses only  the  locking
  1288.           shifts, to the exclusion of 8th-bit quoting.
  1289. 11.4. Kermit-370 Subcommands                                             Page 27
  1290. 0-------------------------------------------------------------------------------
  1291.  SET TTABLE
  1292. 0Syntax: SET TTABLE ON or OFF or KP
  1293. 0ON      The translation that undoes the terminal controller's ASCII/EBCDIC con-
  1294.          version comes from the TATOE and TETOA tables, rather than the ATOE and
  1295.          ETOA tables (which are used only for translating disk files).  This op-
  1296.          tion has no effect when there is no translation  built  into  the  con-
  1297.          troller, i.e., with SERIES1, GRAPHICS, and AEA connections.
  1298. 0OFF     The  ATOE  and ETOA tables are used for all translations by Kermit-370.
  1299.          (Default.)
  1300. 0KP      Same as ON, but also establishes values in the TATOE and  TETOA  tables
  1301.          based  on  IBM's  corporate standard ASCII/EBCDIC translation (distinct
  1302.          from the internationally accepted de facto standard).
  1303. 0
  1304.  SET 8-BIT-QUOTE
  1305. 0Syntax: SET 8-BIT-QUOTE char or ON or OFF
  1306. 0This controls whether eighth-bit prefixing is done and can be used  to  specify
  1307.  the  character  to  be used.  This is one of only two Send-Init parameters that
  1308.  cannot be SET separately for SEND and RECEIVE.
  1309. 0char    Eighth-bit prefixing will be done using char, provided the other Kermit
  1310.          agrees.  The default value is an ampersand.
  1311. 0ON      Eighth-bit prefixing will be done, provided the other Kermit explicitly
  1312.          requests it (and specifies the character).
  1313. 0OFF     Eighth-bit prefixing will not be done.
  1314. 0
  1315.  SET SEND/RECEIVE
  1316. 0The following parameters can be set either as SEND or RECEIVE options.    As  a
  1317.  rule,  in  each  pair,  one  is the operational value, and the other is used to
  1318.  change the default for Send-Init packets received from the other Kermit and  to
  1319.  set  up  parameter values as if the other Kermit had specified them on the pre-
  1320.  vious exchange.  When both values are described, the operational  one  will  be
  1321.  first.  For all parameters besides QUOTE, the operational value is the RECEIVE.
  1322.  After a transfer, the operational values will be unchanged, but the others  (as
  1323.  displayed  by  SHOW) will reflect the parameters specified by the other Kermit.
  1324.  The underlying defaults established by previous SET subcommands will  still  be
  1325.  in effect.  In the syntax descriptions, mode is SEND or RECEIVE.
  1326. 0
  1327.  END-OF-LINE
  1328. 0Syntax: SET mode END-OF-LINE number
  1329. 0RECEIVE should not be changed.
  1330. 0SEND  may be needed to establish contact.  If the other system needs packets to
  1331. 11.4. Kermit-370 Subcommands                                             Page 28
  1332. 0-------------------------------------------------------------------------------
  1333.  be terminated by anything other than carriage return, specify the decimal value
  1334.  of  the  desired  ASCII character.  number must be in the range 0-31 (decimal).
  1335.  The default is 13 (CR).
  1336. 0
  1337.  PACKET-SIZE
  1338. 0Syntax: SET mode PACKET-SIZE number
  1339. 0RECEIVE defines number as the maximum length for incoming packets.   The  valid
  1340.  range  is  26-9024,  but 94 is the limit for normal short-packet protocol.  The
  1341.  default is 80.  Specifying a value greater than 94 is necessary and  sufficient
  1342.  to  enable  the  long-packet protocol for transfers to Kermit-370 (provided the
  1343.  other Kermit is willing).  Kermit-370 will actually accept long packets in  any
  1344.  case,  but  the  protocol  requires  that the other Kermit not send them unless
  1345.  Kermit-370 asks.  Raising this value from the default is a good  candidate  for
  1346.  inclusion  in  INIT  files.    In  practice,  the packet size may be limited by
  1347.  hardware and programming considerations.  See the system-specific chapters  for
  1348.  details.
  1349. 0SEND  might  be  needed  for  sending  files  to  a minimal Kermit that neither
  1350.  specifies a buffer size in the Send-Init sequence nor can  accept  the  default
  1351.  (80).   It may also be used to specify the packet size for a "raw" download via
  1352.  the XTYPE subcommand.  This parameter has no other function and  is  completely
  1353.  irrelevant  to  long  packets.    If  the  other  Kermit asks for long packets,
  1354.  Kermit-370 will always comply.
  1355. 0
  1356.  PAD-CHAR
  1357. 0Syntax: SET mode PAD-CHAR number
  1358. 0RECEIVE defines number as the character to be used by the other Kermit for pad-
  1359.  ding  packets.   The character must be an ASCII control character (in the range
  1360.  0-31).  The default is 0 (NULL).  This option is seldom useful.
  1361. 0SEND may be needed to establish contact if the other Kermit (or  the  transmis-
  1362.  sion line) needs padded packets.
  1363. 0
  1364.  PADDING
  1365. 0Syntax: SET mode PADDING number
  1366. 0RECEIVE  defines  the  number  of pad characters to be used for padding packets
  1367.  from the other Kermit.  This number may be anywhere from 0 to 94.  The  default
  1368.  is 0.  This option is seldom useful.
  1369. 0SEND  may  be needed to establish contact if the other Kermit (or the transmis-
  1370.  sion line) needs padded packets.
  1371. 11.4. Kermit-370 Subcommands                                             Page 29
  1372. 0-------------------------------------------------------------------------------
  1373.  PARITY
  1374. 0Syntax: SET mode PARITY MARK or NONE
  1375. 0RECEIVE specifies the  parity  expected  in  the  transparent-mode  ASCII  data
  1376.  received  by the mainframe from a full-screen device.  Such data will typically
  1377.  have either all Mark parity (seven data bits with the eighth  bit  set)  or  no
  1378.  parity (eight data bits).  This is typically not the same as the parity used in
  1379.  communications between the protocol convertor and  the  terminal.    Kermit-370
  1380.  must  know  which  kind  of  parity  to  expect in order to calculate checksums
  1381.  properly.  Since Kermit-370 does not actually verify parity, the other possible
  1382.  variants  (ODD,  EVEN,  and SPACE) are lumped together with MARK parity for the
  1383.  purpose of this subcommand, which merely chooses between 7-bit and  8-bit  data
  1384.  transfer.  The default is MARK.
  1385. 0SEND  is  also  an  operational value, specifying the parity to be used in con-
  1386.  structing outgoing data packets on full-screen devices.  NONE  is  the  default
  1387.  and  is  generally  preferable, in that it permits binary transfers without the
  1388.  need for eighth-bit prefixing, but MARK may be required in some configurations.
  1389. 0
  1390.  QUOTE
  1391. 0Syntax: SET mode QUOTE char
  1392. 0SEND indicates a printable character for prefixing (quoting) control characters
  1393.  and other prefix characters.  The only good reason to change this would be  for
  1394.  sending a file that contains many "#" characters (the normal control prefix) as
  1395.  data.  It must  be  a  single  character  with  ASCII  value  33-62  or  96-126
  1396.  (decimal).
  1397. 0RECEIVE  would  be  needed  only  for  talking to a crippled Kermit that uses a
  1398.  non-standard quoting character, but does not admit it.
  1399. 0
  1400.  START-OF-PACKET
  1401. 0Syntax: SET mode START-OF-PACKET number
  1402. 0RECEIVE defines number as the character to be expected to  mark  the  start  of
  1403.  packets  from the other Kermit.  The character must be an ASCII control charac-
  1404.  ter (in the range 0-31).  The default is 1 (SOH).  This may need to be  changed
  1405.  to establish contact.
  1406. 0SEND  may  also  need to be changed to establish contact.  It defines number as
  1407.  the character to be used to mark outgoing packets.
  1408. 0
  1409.  TIMEOUT
  1410. 0Syntax: SET mode TIMEOUT time
  1411. 0RECEIVE defines the time in seconds the other Kermit is to wait for a  response
  1412.  from  Kermit-370  before  resending  a packet.  The default is 5.  A value of 0
  1413.  means the other Kermit should wait indefinitely.
  1414. 0SEND may be needed to define the time in seconds Kermit-370 is to  wait  for  a
  1415. 11.4. Kermit-370 Subcommands                                             Page 30
  1416. 0-------------------------------------------------------------------------------
  1417.  response  from  the  other  Kermit in the initial packet exchange, although the
  1418.  default value 0 (indefinite wait) is probably  satisfactory,  especially  since
  1419.  Kermit-370  in  many cases cannot time out anyway.  Specifying a non-zero value
  1420.  will prevent the other Kermit from ever  requesting  infinite  "patience"  from
  1421.  Kermit-370.
  1422. 0
  1423.                                THE SHOW SUBCOMMAND
  1424. 0Syntax: SHOW [option]
  1425. 0The  SHOW  subcommand displays the values of all parameters that can be changed
  1426.  with the SET subcommand, except CONTROL-CHAR, ATOE, ETOA, TATOE, and TETOA (for
  1427.  those,  see  the  TDUMP  subcommand).  If specified, option can be a particular
  1428.  parameter or the keyword "ALL" (the default).  Groups of  parameters,  such  as
  1429.  SEND,   can   be   displayed  by  requesting  the  group  name,  or  individual
  1430.  sub-parameters can be displayed by specifying the complete name.  For example,
  1431. 0  SHOW RECEIVE EOL
  1432. 0will display the decimal value of the packet terminator  that  Kermit-370  cur-
  1433.  rently expects, i.e., 13.  Similarly,
  1434. 0  SHOW FOREIGN
  1435. 0will  display  the  character strings currently in use for prefix and suffix on
  1436.  each outgoing filespec.  When "ALL" is specified  or  implied,  all  parameters
  1437.  other than the attribute switches are displayed.
  1438. 0
  1439.                               THE STATUS SUBCOMMAND
  1440. 0Syntax: STATUS
  1441. 0This  subcommand displays information about the previously executed subcommand.
  1442.  The response will include either the appropriate error message or  the  message
  1443.  "No  errors".    The  initial status is "No file transfers yet".  If the status
  1444.  reflects an error condition, the name of the last  file  used  (excluding  TAKE
  1445.  files)  will be displayed as well.  If the error was detected by the other Ker-
  1446.  mit, the message will be "Micro aborted" followed by the text  from  the  Error
  1447.  packet.    Conversely, if Kermit-370 detected the error, the text of the status
  1448.  message will have constituted the error packet sent out.  In any case,  if  the
  1449.  last  file transfer was cancelled (by virtue of an attribute mismatch or manual
  1450.  intervention), the reason for cancellation is displayed.  Also,  if  the  error
  1451.  occurred in disk I/O, any available explanatory information is displayed.  Nor-
  1452.  mally, the error status is altered only when a  transfer-initiating  subcommand
  1453.  (SEND or RECEIVE) is executed, but there are several exceptions.  If an invalid
  1454.  subcommand is entered, the status becomes "Kermit command error", and the  next
  1455.  subcommand  entered  will reset the status.  Also, in server mode every subcom-
  1456.  mand is received through a transfer from the other Kermit and  may  affect  the
  1457.  status (except the STATUS subcommand itself, of course).
  1458. 0Other  information  is also included.  When Kermit-370 has been forced to trun-
  1459.  cate one or more records in the last RECEIVE operation (because of the  current
  1460.  maximum  record  length),  the  number  of  records truncated is reported.  The
  1461.  status display also includes throughput statistics for the last transfer:  num-
  1462. 11.4. Kermit-370 Subcommands                                             Page 31
  1463. 0-------------------------------------------------------------------------------
  1464.  ber of files sent, duration, number of packets, number of retries, and averages
  1465.  of bytes/packet and bytes/second.  These last  two  quantities  are  calculated
  1466.  separately  for  bytes  sent  and received on the communication line (including
  1467.  padding, if any), and the last quantity is also calculated on the basis of  the
  1468.  number  of bytes read from or written to disk.  Further, if retries were neces-
  1469.  sary, Kermit-370 computes the optimum packet size assuming the retries to  have
  1470.  been  due  to  sparse,  Poisson-distributed  bursts of noise.  This is the same
  1471.  heuristic  optimum  that  Kermit-370  computes  and  uses  as  an   alternative
  1472.  packet-size  limit  when  sending long packets.  If TEST is set on, Kermit also
  1473.  reports the maximum size attained by its storage stack since execution began.
  1474. 0
  1475.                                THE STOP SUBCOMMAND
  1476. 0Syntax: STOP
  1477. 0This is not a subcommand in the usual sense.  Instead, it is a  command  string
  1478.  that  can  be entered on the communication line while Kermit-370 is in protocol
  1479.  mode and will cause protocol mode to cease immediately.  This may be useful  if
  1480.  the  other  Kermit has crashed.  The word "stop" may be entered in either upper
  1481.  or lower case, but it must be the only character  string  in  the  "packet"  in
  1482.  question.    If  you are using a full-screen terminal, and if other information
  1483.  appears on the screen, you must clear that other text from  the  screen  (using
  1484.  CLEAR EOF) before pressing ENTER.
  1485. 0
  1486.                                THE TAKE SUBCOMMAND
  1487. 0Syntax: TAKE filespec
  1488. 0Execute Kermit subcommands from the specified file, usually called a TAKE file.
  1489.  The TAKE file may in turn include TAKE subcommands, and the  nesting  may  con-
  1490.  tinue  to  a  depth  of  ten.    If a TAKE file includes the subcommand SERVER,
  1491.  however, the nesting count is saved and starts over again  in  server  mode  in
  1492.  case  the client Kermit should transmit a REMOTE KERMIT TAKE command.  The user
  1493.  has the option of seeing the subcommands echoed from the TAKE file as they  are
  1494.  executed  and  also the option of automatically exiting from a TAKE file on er-
  1495.  ror.  See the subcommand SET TAKE for details.
  1496. 0
  1497.                               THE TDUMP SUBCOMMAND
  1498. 0Syntax: TDUMP table-name or NAMES or TRACE
  1499. 0This displays the contents of table-name.  The same table can be modified using
  1500.  the  SET  subcommand.   The ATOE, ETOA, TATOE, and TETOA translation tables and
  1501.  the CONTROL-CHAR prefixing selection  table  can  presently  be  displayed  and
  1502.  changed.    The  NAMES table is the transaction log for the last transfer, con-
  1503.  sisting of the filespec of each file sent or received, along with the size  (in
  1504.  Kbytes)  and  any error messages.  If the Kermit TRACE facility is enabled, the
  1505.  TRACE table may be displayed (and destroyed in the process).  This  table  con-
  1506.  tains  entries  for  subroutine calls and returns during program execution, but
  1507.  Kermit normally does not have the facility enabled.  See  SET  DEBUG  for  more
  1508.  details on execution tracing.
  1509. 11.4. Kermit-370 Subcommands                                             Page 32
  1510. 0-------------------------------------------------------------------------------
  1511.                          THE TYPE AND XTYPE SUBCOMMANDS
  1512. 0Syntax: [X]TYPE filespec
  1513. 0These  subcommands  display  the named file.  TYPE is effectively a synonym for
  1514.  (and allows the same options as) the host system command for  displaying  files
  1515.  at  the  terminal,  but  XTYPE performs a raw file transfer on the current com-
  1516.  munication line (which need not be the terminal) according to the current  CON-
  1517.  TROLLER  setting.   Thus, XTYPE uses transparent mode if CONTROLLER is SERIES1,
  1518.  GRAPHICS, or AEA.  Also, it sends the data in bursts no larger than the current
  1519.  SEND  PACKET-SIZE.    Since XTYPE is basically a modified SEND, the options al-
  1520.  lowed on the filespec for SEND are also allowed for XTYPE.
  1521. 0
  1522.                              THE VERSION SUBCOMMAND
  1523. 0Syntax: VERSION
  1524. 0This subcommand displays the program version number and date.
  1525. 0
  1526.  1.5. Before Connecting to the Mainframe
  1527. 0Several options must be set in the micro Kermit before connecting to an IBM 370
  1528.  system  as  a  line-mode  device.  You should set LOCAL-ECHO to ON (to indicate
  1529.  half-duplex).  This is the norm but not true in absolutely every case; if  each
  1530.  character  appears  twice  on  your  terminal  screen,  set  LOCAL-ECHO to OFF.
  1531.  FLOW-CONTROL should be set to NONE, and on some systems HANDSHAKE should be set
  1532.  to XON.  The parity should be set according to the system's specifications.  On
  1533.  some micro Kermits, all of the above is done in one step using the DO IBM macro
  1534.  (or SET IBM ON).  Set the baud rate to correspond to the line speed.
  1535. 0Connecting  through  a full-screen device also requires that certain options be
  1536.  set in the micro Kermit.   You  should  set  LOCAL-ECHO  to  OFF  (to  indicate
  1537.  full-duplex).   FLOW-CONTROL should be set to XON/XOFF, and HANDSHAKE should be
  1538.  set to OFF.  For many systems, the PARITY should be set to EVEN.  Set the  baud
  1539.  rate to correspond to the line speed.
  1540. 0One  exception  to these rules is the case where the micro Kermit is attempting
  1541.  automated  file  transfer,  e.g.,  downloading  several  separate  files   from
  1542.  Kermit-370  running  in server mode.  In fact, under those circumstances, hand-
  1543.  shaking is necessary even with "SERIES1" connections, and the two Kermits  must
  1544.  be  instructed to adopt a common handshake character (e.g., by SET HANDSHAKE 10
  1545.  to Kermit-370 and SET HANDSHAKE LF to the micro).
  1546. 0In any case, you should make sure that either the micro  Kermit  or  Kermit-370
  1547.  will  provide  timeouts  during file transfers (if not both).  Some variants of
  1548.  Kermit-370 (notably CMS) cannot provide timeouts, and you may need to  set  the
  1549.  TIMER to ON in the micro.
  1550. 0When  you are connecting through a protocol convertor, it is useful to know the
  1551.  key sequence that causes the screen image to be repainted from the controller's
  1552.  memory.  In many cases, it is CTRL-V, although CTRL-G and CTRL-C are also some-
  1553.  times used.  In general, this sequence should be typed whenever reconnecting to
  1554.  Kermit-370  after being in Kermit protocol mode (and sometimes after merely es-
  1555.  caping to the local Kermit), since the  local  Kermit  may  have  modified  the
  1556. 11.5. Before Connecting to the Mainframe                                 Page 33
  1557. 0-------------------------------------------------------------------------------
  1558.  screen.
  1559. 0
  1560.  1.6. Trouble-shooting Protocol Converters
  1561. 0Many,  but not all, protocol converters have transparent modes that permit Ker-
  1562.  mit file transfers.  The welter of competing and often incompatible  communica-
  1563.  tions  devices  would  cause  a major headache, except for three circumstances.
  1564.  First, Kermit-370 has routines for automatically detecting which kind of  front
  1565.  end  is  controlling  the  current session; second, the Kermit installer is en-
  1566.  couraged to tailor Kermit to force the correct choice  of  CONTROLLER  whenever
  1567.  those  routines  don't  work  properly; and, third, Kermit offers a last-resort
  1568.  mode of operation that will work with almost any protocol converter.    Because
  1569.  of  the  limitations  in  the  catch-all mode (known as FULLSCREEN mode), it is
  1570.  still best to take advantage of the transparency, if any, in the protocol  con-
  1571.  verter,  and the automatic detection routines still play an important role.  It
  1572.  will be instructive to outline what those routines actually do and how they can
  1573.  go wrong.
  1574. 0
  1575.  Recognizing a Series/1
  1576. 0Although  protocol  converters are advertised as simulating the behavior of IBM
  1577.  3270-type terminals, there generally are differences which  could  be  used  to
  1578.  distinguish  each  type  of device from the others and from real 3270-type ter-
  1579.  minals.  However, all that really matters to Kermit-370 is whether there  is  a
  1580.  transparent  mode  available  such  that file transfers can be carried out.  To
  1581.  date, only three fundamentally different transparent modes have  been  reported
  1582.  to  Columbia,  and  it seems likely that no others have been (or, perhaps, ever
  1583.  will be) implemented.  All are supported by Kermit.
  1584. 0Kermit-370 recognizes these front  ends  automatically  by  making  two  simple
  1585.  tests.    The  first  takes advantage of one of the advanced features first im-
  1586.  plemented in the Yale ASCII system and  subsequently  copied  in  many  of  the
  1587.  devices that adopted the same transparent mode.  This feature is a special 3270
  1588.  data-stream order which requests a status report from the  protocol  converter.
  1589.  Kermit  sends  this  order  and then reads the "3270 screen".  If Kermit sees a
  1590.  valid status report, it sets CONTROLLER to SERIES1 and stops testing.
  1591. 0
  1592.  Two catches
  1593. 0Obviously, the Yale status order is not implemented  in  most  other  kinds  of
  1594.  hardware.  Thus, the order would be rejected by a non-Yale-type controller, and
  1595.  that could have undesirable side effects on the hardware.  However, hardware is
  1596.  generally  designed  to be robust -- the real drawback lies in the side effects
  1597.  on certain communications software (notably VTAM/TSO), which may respond  badly
  1598.  while  trying to protect the robust hardware from illegal orders.  If it proves
  1599.  impossible to make the external software behave properly, the only recourse  is
  1600.  to  modify  Kermit-370  to skip the first test altogether and possibly to force
  1601.  the CONTROLLER setting; this modification is described in the relevant "Beware"
  1602.  file in a note dated 89/2/27.
  1603. 0Catch  Two  is  that  the status order is not implemented in all of the devices
  1604.  that support Yale-ASCII-style transparent mode.  This means that  some  devices
  1605.  "fall  through  the  cracks"  in this procedure.  A site where such devices are
  1606. 11.6. Trouble-shooting Protocol Converters                               Page 34
  1607. 0-------------------------------------------------------------------------------
  1608.  used may find it expedient to modify Kermit (following the same  "Beware"  pat-
  1609.  tern)  to  force the procedure to set CONTROLLER to SERIES1 (assuming there are
  1610.  no other protocol converters also in use that support one of the  other  trans-
  1611.  parent modes).  A list of such devices can be found in a footnote in the Kermit
  1612.  distribution file ik0aaa.hlp.
  1613. 0
  1614.  Recognizing a 3174
  1615. 0The second diagnostic test uses a hardware command (Read Partition Query)  that
  1616.  is  defined  by  IBM, but is not implemented on all 3270-type equipment.  There
  1617.  is, thus, the same danger as in the first test, but the danger  appears  to  be
  1618.  slight.    Indeed,  both  CMS  and  TSO allow a user program to know in advance
  1619.  whether a Query is permitted.  The Query  response  consists  of  one  or  more
  1620.  structured fields, and the 3174 AEA ASCII Graphics system (the only device with
  1621.  the AEA style of transparency) is easily identified by the appearance and  con-
  1622.  tent  of  a particular type of field.  In fact, it is possible to tell from the
  1623.  Query data whether the particular  3174  line  is  allowed  to  use  the  ASCII
  1624.  Graphics  transparency.  Therefore, this test has three possible outcomes: Ker-
  1625.  mit may detect a transparency-enabled 3174 line (and set CONTROLLER to AEA); it
  1626.  may  detect  an  incapable  3174  line  (and set CONTROLLER to NONE); or it may
  1627.  detect "none of the above" (and set CONTROLLER to GRAPHICS).  Thus, aside  from
  1628.  the  exceptions  already noted, GRAPHICS simply means that the front end either
  1629.  supports SAS-style transparency or none at all.
  1630. 0
  1631.  Fallback positions
  1632. 0What should you do when the automatic detection fails?   Obviously,  the  first
  1633.  thing is Be Prepared.  Often, the misbehavior of VTAM can be halted by pressing
  1634.  ENTER or PA1, so you should be sure to know how to generate a PA1  when  trying
  1635.  out  Kermit on an unfamiliar type of protocol converter.  Also, you should know
  1636.  what kind of  transparency  to  expect  for  the  front  end  and  verify  that
  1637.  Kermit-370 has, in fact, set CONTROLLER appropriately.  This means checking the
  1638.  list of devices in the Kermit distribution file ik0aaa.hlp.  If your configura-
  1639.  tion  is  listed  as unsupported, you may be wasting your time, but the list is
  1640.  not necessarily up-to-date.  If your configuration is not listed  at  all,  you
  1641.  have  the opportunity to be a pioneer and report your findings back to Columbia
  1642.  for inclusion in future editions of the list.  There are a few rules  of  thumb
  1643.  for quickly deducing the controller type by reading the manuals for the device;
  1644.  the manuals may not be specific enough, but this is clearly the easiest way  of
  1645.  determining whether Kermit can support a given device and which controller type
  1646.  is applicable.    The  rules  are  as  follows  (in  order  of  simplicity  and
  1647.  likelihood):
  1648. 0   1. GRAPHICS or SERIES1 may be implied when the device has a transparent
  1649.        or graphics mode described as compatible with that  of  a  supported
  1650.        device listed in ik0aaa.hlp.
  1651. 0   2. SERIES1  is  implied when the device runs the "Yale ASCII Communica-
  1652.        tion System" or something with a similar name.
  1653. 0   3. GRAPHICS is implied if the manual mentions the SAS Institute in  the
  1654.        context of ASCII graphics.
  1655. 0   4. GRAPHICS  is implied when output transparent data may be preceded by
  1656. 11.6. Trouble-shooting Protocol Converters                               Page 35
  1657. 0-------------------------------------------------------------------------------
  1658.        a WCC (Write Control Character) and 70 (hex).
  1659. 0   5. SERIES1 is implied when transparent data must be preceded by  a  WCC
  1660.        and either 115D7F110005 (write-read) or 115D7F110000 (write-only).
  1661. 0   6. GRAPHICS  or  SERIES1 may be implied when some of the manufacturer's
  1662.        other products are listed in ik0aaa.hlp, and all are shown as  being
  1663.        of one type.
  1664. 0   7. If  none of the above rules apply, but the manuals describe a trans-
  1665.        parent mode in detail, the device may be a totally new  type.    The
  1666.        distribution  file  ik0con.hlp has hints on implementing Kermit sup-
  1667.        port for the new type.
  1668. 0   8. If nothing else works, you can probably use FULLSCREEN mode, as long
  1669.        as the micro Kermit supports it.
  1670. 0If  Kermit tries to transfer a file with the wrong CONTROLLER value, there is a
  1671.  distressing possibility for the session to lock or, at least, appear  to  lock.
  1672.  When  and  if  this  happens,  be  sure  to connect back to the mainframe, type
  1673.  "STOP", and press ENTER several times (perhaps as  many  as  15  times)  before
  1674.  taking any drastic steps like breaking the connection.  "STOP" is a special es-
  1675.  cape mechanism for getting out of Kermit protocol  mode  quickly.    Kermit-370
  1676.  recognizes such a request in most situations where terminal I/O is not entirely
  1677.  frozen.  Sometimes, apparent lock-ups are due to something as simple as  incor-
  1678.  rect  parity settings in the micro Kermit, so always check the basic communica-
  1679.  tion settings and, if necessary, experiment  before  trying  a  different  CON-
  1680.  TROLLER type.  Also, to avoid unnecessary confusion, check for the existence of
  1681.  a Kermit initialization file (possibly created by the installer) which could be
  1682.  re-setting  CONTROLLER  after  the  automatic  procedure  has finished.  Such a
  1683.  re-setting is a poor idea in an initialization file, even a personal  one,  un-
  1684.  less there is absolutely only one kind of communications equipment on your sys-
  1685.  tem.
  1686. 0If file transfers do not work at first, it is best to do the  following  before
  1687.  trying again:
  1688. 0   1. Reduce the packet size to no more than 80 at both ends.
  1689. 0   2. Enable 8th-bit quoting at both ends.
  1690. 0   3. Set SEND PARITY MARK in Kermit-370.
  1691. 0If  those  changes do not make transfers work, the next remedial action depends
  1692.  on the symptoms of failure.
  1693. 0   - No packets exchanged and session locked up after reconnecting: change
  1694.       packet characters in both directions.
  1695. 0   - No  packets  exchanged,  but  no  lockup: change packet characters or
  1696.       parity.
  1697. 0   - Always multiple retries of third or fourth packet:  reduce  receiving
  1698.       packet size.
  1699. 0   - Multiple  retries  after random number of packets: check hardware and
  1700. 11.6. Trouble-shooting Protocol Converters                               Page 36
  1701. 0-------------------------------------------------------------------------------
  1702.       cables.
  1703. 0   - Multiple retries after file-dependent number of  packets:  check  for
  1704.       equipment  that intercepts one or more printable characters or reduce
  1705.       the packet size.
  1706. 0When all else fails, you should be ready to reset CONTROLLER by  hand  and  try
  1707.  again.    The  change  most likely to be necessary is from GRAPHICS to SERIES1.
  1708.  However, it is conceivable that the installer has modified Kermit-370  at  your
  1709.  location  to  force  the  CONTROLLER setting from the start, in which case, you
  1710.  might need to go the other way.  Normally,  Kermit's  diagnostic  procedure  at
  1711.  start-up takes one or two seconds (because of programmed delays), so you should
  1712.  be suspicious if the Kermit prompt appears  immediately  after  you  start  the
  1713.  program.    The  only  initial CONTROLLER setting that you should not change by
  1714.  hand is NONE, which means that Kermit-370 has recognized a 3174 AEA  line  that
  1715.  is  not configured for file transfer (or else the Kermit installer has a warped
  1716.  sense of humor).
  1717. 0If no amount of experimenting gets a transparent mode to work, it  is  time  to
  1718.  recheck  the list of supported devices and the age of your equipment.  If yours
  1719.  is very old, it may require new microcode or some other  software  or  hardware
  1720.  upgrade.    In any case, if your results (whether positive or negative) are not
  1721.  already shown in ik0aaa.hlp, you should report them to Columbia so that  others
  1722.  may profit by your experience.
  1723. 0
  1724.  1.7. After Returning from Kermit-370
  1725. 0When  Kermit-370  receives a QUIT or EXIT subcommand or finishes the subcommand
  1726.  or subcommands specified in the original command string  that  invoked  Kermit,
  1727.  control is returned to the caller.  Before returning, Kermit-370 closes any ac-
  1728.  tive TAKE files (the EXIT or QUIT subcommand may be issued from a  TAKE  file).
  1729.  On  return,  the completion code is set from the current error status according
  1730.  to the codes in Table 1-4.
  1731. 0The error codes in Table 1-4 bear no relationship to the severity  of  the  as-
  1732.  sociated error conditions, aside from the assignment of code 0.  The underlying
  1733.  rationale is that the only current generic system for the treatment of  comple-
  1734.  tion  codes is to take a non-zero code as an indication of error.  Indeed, Ker-
  1735.  mit returns a completion code of 0 when "error" condition 1 holds.
  1736. 0
  1737.  1.8. What's New
  1738. 0Below is a list of the changes in Version 4.3 of Kermit-370.
  1739. 0   1. Compatibility with the (aging) F-level assembler.
  1740. 0   2. Support for LATIN2, LATIN3, TRANSPARENT, CP870, CP905, and CP880, as
  1741.        well as the aliases L1, L2, and L3.  New alias CP1047 for EBCDIC.
  1742. 0   3. Support for IBM 3174 ASCII Graphics mode.
  1743. 0   4. Improved  controller  detection,  including  local customization op-
  1744.        tions.
  1745. 0   5. Support for new unprefixed transmission of selected control  charac-
  1746. 11.8. What's New                                                         Page 37
  1747. 0-------------------------------------------------------------------------------
  1748.  -------------------------------------------------------------------------------
  1749. 0
  1750.  Code  Symbol  Error Message
  1751.   0    NOE     No errors
  1752.   1    NFT     No file transfers yet
  1753.   2    TRC     Transfer cancelled
  1754.   3    USC     Invalid server command
  1755.   4    TIE     Terminal I/O error
  1756.   5    BPC     Bad packet count or chksum
  1757.   6    IPS     Invalid packet syntax
  1758.   7    IPT     Invalid packet type
  1759.   8    MIS     Lost a packet
  1760.   9    NAK     Micro sent a NAK
  1761.  10    ABO     Micro aborted
  1762.  11    FNE     Invalid file name
  1763.  12    FNF     File not found
  1764.  13    FUL     Disk or file is full
  1765.  14    DIE     Disk I/O error
  1766.  15    MOP     Missing operand
  1767.  16    SYS     Illegal system command
  1768.  17    KCE     Kermit command error
  1769.  18    TIM     No packet received
  1770.  19    RTR     Records truncated
  1771.  20    COM     Bad communication line
  1772.  21    PTY     8th-bit quote not set
  1773.  22    FTS     File too short
  1774.  23    SOH     Missing start-of-packet
  1775.  24    OPT     Option error on filespec
  1776.  25    DSP     Unable to dispose of file
  1777. 0              Table 1-4:  Error messages and codes for Kermit-370
  1778. 0
  1779. 0-------------------------------------------------------------------------------
  1780. 0      ters.
  1781. 0   6. Support for REMOTE PRINT, REMOTE MAIL, and REMOTE SUBMIT.
  1782. 0   7. Improved  error message for bad packet-size, new alias PACKET-LENGTH
  1783.        for PACKET-SIZE.
  1784. 0   8. Correct observance of FILE COLLISION for all files in a group.
  1785. 0   9. Ignoring  spurious  flow-control  "packets"   from   (for   example)
  1786.        MS-Kermit.
  1787. 0  10. Support for new locking-shift Kermit protocol.
  1788. 0  11. Support  for  Japanese  Kanji file transfer and support for the Thai
  1789.        and Arabic character sets.
  1790. 0  12. New versions of Kermit with the interactive  messages  in  languages
  1791.        other than English.
  1792. 11.8. What's New                                                         Page 38
  1793. 0-------------------------------------------------------------------------------
  1794.    13. New FULLSCREEN controller type.
  1795. 0  14. New HINTS subcommand.
  1796. 0  15. More graceful recovery from terminal I/O errors and exceptions.
  1797. 0  16. Support for SNA LU1 3770-type devices and 8-bit, no-parity devices.
  1798. 0  17. Optional  conversion  of  EBCDIC printer carriage control into ASCII
  1799.        control characters.
  1800. 0  18. Support for STOP command on "dumb" 3270 terminals and  PCI  protocol
  1801.        converters.
  1802. 0  19. New efficiency display in STATUS report, based on SPEED setting.
  1803. 0  20. New, uniform messages upon entering protocol mode, in the form "KER-
  1804.        MIT READY TO SEND..." (or RECEIVE or SERVE).
  1805. 0  21. 8-bit XECHO output.
  1806. 0  22. Control prefixing for C1 controls.
  1807. 0  23. New VERSION subcommand.
  1808. 0  24. Improved debugging facilities.
  1809. 0
  1810.  1.9. What's Missing
  1811. 0Work on Kermit-370 will continue.  Features that need to be improved  or  added
  1812.  include:
  1813. 0   - Implement file archiving.
  1814. 0   - Implement file transfer checkpointing.
  1815. 0   - Add SET REPEAT subcommand.
  1816. 0   - Improve Kermit-370 operation as a local Kermit.
  1817. 0   - Implement public server mode.
  1818. 0   - Allow  REMOTE  KERMIT  HELP, REMOTE KERMIT DIR, and REMOTE SET from a
  1819.       micro.
  1820. 0   - Add new SET FILE LONGLINE DISCARD option to allow multi-file transfer
  1821.       to proceed past a truncation problem.
  1822. 0   - System-specific upgrades; see the respective chapters for details.
  1823. 0Anyone interested in working on these or other improvements should first get in
  1824.  touch with the Center for Computing Activities at Columbia University  to  find
  1825.  out if someone else has already begun a similar project (and, if so, who).
  1826. 11.10. Further Reading                                                   Page 39
  1827. 0-------------------------------------------------------------------------------
  1828.  1.10. Further Reading
  1829. 0Below is a list of references for some of the material in this chapter.
  1830. 0   1. About  Type:  IBM's  Technical Reference for 240-Pel Digitized Type,
  1831.        S544-3156-02 (1989).  This manual contains  visual  tables  of  many
  1832.        EBCDIC  code  pages  and a comprehensive list of character names and
  1833.        acronyms.
  1834. 0   2. IBM System/370 Reference Summary, GX20-1850-3 (1976).   This  refer-
  1835.        ence card contains EBCDIC and ASCII character codes.
  1836. 0   3. IBM   VS   Fortran   Application  Programming:  Language  Reference,
  1837.        GC26-3986-1 (1982).  Appendix E contains a table of EBCDIC and ASCII
  1838.        characters with an implied full 256-byte translation table.
  1839. 0   4. IBM  3174  Character  Set Reference, GA27-3831-02 (1990).  Chapter 5
  1840.        contains visual tables of many EBCDIC code pages.
  1841. 0   5. Info-Kermit Digest Vol. 11 #1 (1989).   This  issue  contains  draft
  1842.        specifications of some Kermit protocol extensions.
  1843. 0   6. ISO  International  Register of Coded Character Sets to be used with
  1844.        Escape Sequences (1989).  This (very large)  document  has  complete
  1845.        and  unambiguous  descriptions of standard coded character sets.  It
  1846.        can be obtained from the ECMA.
  1847. 0   7. Kermit, A File Transfer Protocol by Frank  da  Cruz;  Digital  Press
  1848.        (1987).    This  book  contains a thorough description of the Kermit
  1849.        protocol and services with copious examples.
  1850. 0   8. Kermit distribution file ISOK7.TXT (1992).  This  preliminary  draft
  1851.        describes  the  new  transfer  protocol, including the international
  1852.        character-set support.
  1853. 0   9. Kermit News Vol. 3 #1, p.5, "Dynamic Packet  Size  Control"  (1988).
  1854.        This article describes an algorithm for optimizing Kermit throughput
  1855.        in the face of line noise.
  1856. 0  10. Kermit News #4, p.16, "International Character Sets" (1990).    This
  1857.        article discusses the new transfer protocol.
  1858. 0  11. ASCII  and  EBCDIC Character Set and Code Issues in Systems Applica-
  1859.        tions Architecture, SHARE white paper by Edwin Hart  (1989).    This
  1860.        document,  available as file SHARE REQUIRE from LISTSERV@JHUVM, lays
  1861.        out general considerations for character codes and translatability.
  1862. 0  12. Kermit distribution file LSHIFT.TXT (1991).  This file describes the
  1863.        new  protocol  extension  for  better compression of 8th-bit text on
  1864.        7-bit channels.
  1865. 12. IBM CMS KERMIT                                                       Page 40
  1866. 0-------------------------------------------------------------------------------
  1867.  2. IBM CMS KERMIT
  1868. 0Program:       John Chandler  (Harvard/Smithsonian  Center  for  Astrophysics);
  1869.                 contributions  from Vace Kundakci and Daphne Tzoar (Columbia U),
  1870.                 Bob Shields (U.  Maryland),  Greg  Small  (UC  Berkeley),  Clark
  1871.                 Frazier  (Harvard  Bus.  Sch.),  Bob Bolch and Steve Blankinship
  1872.                 (Triangle), Ron Rusnak (U. Chicago), Andre Pirard (U. Liege)
  1873.  Language:      IBM/370 Assembler
  1874.  Documentation: John Chandler (CfA)
  1875.  Version:       4.3.0 (93/9/30)
  1876.  Date:          1993 September
  1877. 0
  1878.  Kermit-CMS Capabilities At A Glance:
  1879. 0  Local operation:                   Yes
  1880.    Remote operation:                  Yes
  1881.    Transfers text files:              Yes
  1882.    Transfers binary files:            Yes
  1883.    Wildcard send:                     Yes
  1884.    ^X/^Z interruption:                Yes (through micro)
  1885.    Filename collision avoidance:      Yes
  1886.    Can time out:                      No
  1887.    8th-bit prefixing:                 Yes
  1888.    Repeat count prefixing:            Yes
  1889.    Alternate block checks:            Yes
  1890.    Terminal emulation:                No
  1891.    Communication settings:            No
  1892.    Transmit BREAK:                    No
  1893.    Packet logging:                    Yes
  1894.    Transaction logging:               Yes
  1895.    Session logging:                   No
  1896.    Raw transmit:                      Yes (no prompts)
  1897.    Sliding window:                    No
  1898.    Long packets:                      Yes
  1899.    Act as server:                     Yes
  1900.    Talk to server:                    Yes
  1901.    Advanced server functions:         Yes
  1902.    Advanced commands for servers:     Yes
  1903.    Local file management:             Yes
  1904.    Handle Attribute Packets:          Yes
  1905.    Command/init files:                Yes
  1906.    Command macros:                    No
  1907. 0
  1908.  CMS Specifics of Kermit-370:
  1909. 0  Global INIT file:                  SYSTEM KERMINI *
  1910.    User INIT file:                    userid KERMINI *
  1911.    Debug packet log:                  KER LOG A1
  1912.    Server reply log:                  KER REPLY A1
  1913.    Mail command:                      EXEC KERMAIL filespec ( users
  1914.    Print command:                     EXEC KERMPRT filespec ( options
  1915.    Submit command:                    EXEC KERMSUB filespec ( options
  1916.    Maximum packet size:               1913 (SERIES1), 2030 (TTY)
  1917.    Maximum disk LRECL:                65535
  1918. 12. IBM CMS KERMIT                                                       Page 41
  1919. 0-------------------------------------------------------------------------------
  1920.  Kermit-CMS is a member of the generic Kermit-370 family and shares most of  the
  1921.  features and capabilities of the group.  As its name implies, Kermit-CMS is the
  1922.  variant of Kermit-370 that runs under the CMS operating system.    The  primary
  1923.  documentation  for  Kermit-CMS  is actually the chapter on Kermit-370 (entitled
  1924.  IBM 370 Kermit), which describes general properties; the  present  chapter  as-
  1925.  sumes  the reader is familiar with that material.  Only the details specific to
  1926.  CMS operation will be discussed here, e.g., command syntax relating to the  CMS
  1927.  file system or commands not offered in general by Kermit-370.
  1928. 0
  1929.  2.1. The CMS File System
  1930. 0The  features  of  the CMS file system of greatest interest to Kermit users are
  1931.  the format of file specifications (or filespecs) and the  concept  of  records.
  1932.  The latter is described in the Kermit-370 chapter.
  1933. 0The CMS filespec takes the form
  1934. 0  filename filetype filemode
  1935. 0(often  abbreviated  FN  FT  FM).    The filename and filetype are one to eight
  1936.  characters each.  The filename is the primary identifier for the file, and  the
  1937.  type  is an indicator which, by convention, tells what kind of file it is.  For
  1938.  instance, TEST FORTRAN is the source of a Fortran program named TEST.    MODULE
  1939.  is  the  filetype  for executable programs (as distinct from object code, which
  1940.  has a filetype of  TEXT!).    Although  some  operating  systems  consider  the
  1941.  filetype  optional,  CMS  requires a type for each file.  Therefore, Kermit-CMS
  1942.  supplies a default type of "$" for any received file if no type is provided  by
  1943.  the  remote  system.   The same default is used for a missing filename.  At the
  1944.  same time, Kermit forces the FN and  FT  to  conform  to  CMS  rules  in  other
  1945.  respects.   The FN and FT may contain, in any order, uppercase letters, digits,
  1946.  and the special characters "$" (dollar sign), "#" (number sign), "@" (at sign),
  1947.  "+" (plus), "-" (hyphen), ":" (colon), and "_" (underscore).  Any other charac-
  1948.  ter, if found in the FN or FT, is replaced by an underscore  (or  converted  to
  1949.  uppercase if it is a lowercase letter).  Also, both FN and FT are truncated, if
  1950.  necessary, to eight characters.
  1951. 0The filemode, which consists of a letter and a number, is similar to  a  device
  1952.  specification on microcomputer systems: FN FT FM would translate to FM:FN.FT in
  1953.  CP/M or MS-DOS if the filemode number is ignored.  Indeed, the filemode  number
  1954.  is  more  properly an attribute of a file than part of its name -- no two files
  1955.  can co-exist with names that match in all but the filemode number.    Even  the
  1956.  filemode  letter is not a fixed part of the filespec because the same mini-disk
  1957.  or Shared File System (SFS) directory could be accessed under a different  mode
  1958.  letter.  In some ways, the filemode letter is like a disk directory designator,
  1959.  even when it refers to a mini-disk, since many such mini-disks  may  reside  on
  1960.  the  same  disk  drive.    For  this reason, the Kermit concept of the "working
  1961.  directory" is equated with a particular disk mode letter under Kermit-CMS.  The
  1962.  current  "working directory" is, thus, the "home" filemode (normally "A", which
  1963.  is the primary user  mini-disk  under  CMS),  and  file  transfers  take  place
  1964.  preferentially  to and from the "home" disk.  If the filemode is omitted from a
  1965.  filespec when sending, the "home" disk is normally used, but there is an option
  1966.  for using a default of "*" instead.  In this case, the user's disks are scanned
  1967.  according to the search order and the first occurrence of the file is  the  one
  1968.  that  is  sent.  If the filemode is omitted from a filespec when receiving, the
  1969.  "home" disk is used with a filemode number of "1".
  1970. 12.1. The CMS File System                                                Page 42
  1971. 0-------------------------------------------------------------------------------
  1972.  To provide compatibility with other operating systems, when Kermit-CMS sends  a
  1973.  file,  it  ordinarily  makes a file header with only the filename and filetype.
  1974.  It also converts the intervening blank to a period.  However, extra information
  1975.  may be added by way of the SET FOREIGN subcommand.
  1976. 0CMS  allows  a group of files to be specified in a single filespec by including
  1977.  the special "wildcard" characters "*" and "%".  A "*"  matches  any  string  of
  1978.  characters  (even  a  null  string) from the current position to the end of the
  1979.  field; a "%" matches any single character.  Here are some examples:
  1980. 0  * COBOL A   All files of type COBOL (all COBOL source files) on the A disk.
  1981. 0  F* * *      All files whose names start with F.
  1982. 0  % * B       All B-disk files with one-character FN's.
  1983. 0CMS files, like those in other IBM 370 systems, are  record-oriented  (see  the
  1984.  introduction  to the Kermit-370 chapter).  In particular, CMS files are charac-
  1985.  terized by record format (RECFM), which may be fixed-length or  varying-length,
  1986.  and  by  record  length  (LRECL).    The  size  of record blocks is irrelevant,
  1987.  however, because CMS performs the blocking and deblocking operations  automati-
  1988.  cally  and  transparently, including the spanning of records across block boun-
  1989.  daries.  An important point to note is that records being written to a RECFM  V
  1990.  file are not limited in length by the LRECL, but only by the CMS maximum (65535
  1991.  bytes).
  1992. 0Another file system feature of occasional interest is the  means  of  reporting
  1993.  errors.    When Kermit-CMS encounters a disk error, it records the function and
  1994.  error code for inclusion in the STATUS report.  The explanations can  be  found
  1995.  in  the  CMS  reference  manual under the FSREAD and FSWRITE macros (which cor-
  1996.  respond to the RDBUF and WRBUF functions).
  1997. 0
  1998.  2.2. Program Operation
  1999. 0At startup time, Kermit-CMS looks for two initialization  files,  "SYSTEM  KER-
  2000.  MINI" and "userid KERMINI" (where userid is the user's logon ID).  If either of
  2001.  these files exists on more than one disk, it will be read and executed from the
  2002.  first  copy in the search order.  The file "SYSTEM KERMINI" should be placed on
  2003.  a publicly accessible disk by a systems programmer, preferably  the  same  disk
  2004.  where  the  Kermit executable module is kept.  The file "userid KERMINI" can be
  2005.  maintained by the user on any convenient disk.
  2006. 0One important distinction between  Kermit-CMS  and  other  Kermits  is  that  a
  2007.  program running under CMS is unable to interrupt a read on its "console".  This
  2008.  means that the CMS variant of Kermit cannot time out after  sending  a  packet.
  2009.  The  only  way to time out is from the other side:  typing a carriage return to
  2010.  the local Kermit causing it to retransmit its  last  packet,  or  an  automatic
  2011.  timeout as provided by most other Kermits.
  2012. 0Five  CP  SET  parameters  (MSG, IMSG, WNG, ACNT, and TIMER) are set OFF during
  2013.  protocol mode (and restored afterwards) to prevent CP from interrupting any I/O
  2014.  in  progress,  LINEDIT  is  set  OFF  to  ensure  that all characters are taken
  2015.  literally, and RUN is set ON to ensure that Kermit can recover from  accidental
  2016.  attention interrupts.  Also, on a TTY line, the TERMINAL LINESIZE is set OFF to
  2017.  prevent CP from inserting carriage return-linefeed pairs into packets, TERMINAL
  2018. 12.2. Program Operation                                                  Page 43
  2019. 0-------------------------------------------------------------------------------
  2020.  SCROLL  is  set  to CONT to prevent CP pauses, and the CMS user terminal trans-
  2021.  lation tables (established via the CMS SET INPUT and OUTPUT commands) are  tem-
  2022.  porarily  suppressed for both short and long packet protocols.  The settings in
  2023.  effect when Kermit starts up are saved as a sort of  "normal"  status  snapshot
  2024.  (as  opposed  to the "protocol" status just described).  The protocol status is
  2025.  selected whenever Kermit enters protocol mode and also after Kermit executes  a
  2026.  CP  command  in  server mode.  Similarly, normal status is selected when Kermit
  2027.  leaves protocol mode and before Kermit executes a CP command  in  server  mode.
  2028.  Note:  if  Kermit  is interrupted in the midst of a transfer or while in server
  2029.  mode, these parameters  will  be  left  with  peculiar  settings  (namely,  the
  2030.  protocol status), and they may need to be restored by hand.
  2031. 0If, at some installation, Kermit can be run only on "TTY" lines, users will of-
  2032.  ten be forced to disconnect or log off ongoing sessions  on  fullscreen  lines.
  2033.  In  general, users may operate through IBM 3270-type terminals and then discon-
  2034.  nect in order to reconnect to a line that supports Kermit.  In cases like this,
  2035.  users should be warned that reconnecting to a session over a "TTY" line is dif-
  2036.  ferent from logging on initially over such a line.  In particular, the CMS  SET
  2037.  parameters AUTOREAD and BLIP and the CP TERMINAL parameter LINESIZE may need to
  2038.  be reset after reconnecting.  AUTOREAD should be ON for "TTY" lines and OFF for
  2039.  fullscreen  lines;  the  other two parameters are a matter of taste.  A similar
  2040.  warning applies to reconnecting in the opposite direction.
  2041. 0CMS is different from some other IBM mainframe systems  in  that  it  allows  a
  2042.  program  to  take  control  of  prompting  and  synchronization on "TTY" lines.
  2043.  Kermit-CMS takes advantage of this option, and it is not, in general, necessary
  2044.  to  enable  handshaking on the micro Kermit before connecting to CMS.  In other
  2045.  words, handshaking should be suppressed for both "TTY"  and  "SERIES1"  devices
  2046.  (the  micro  Kermit  should  have HANDSHAKE set OFF, and Kermit-CMS should have
  2047.  HANDSHAKE set to 0).  Since the generic Kermit-370 default handshake  (XON)  is
  2048.  retained  in  Kermit-CMS,  the subcommand "SET HANDSHAKE 0" is a good candidate
  2049.  for inclusion in SYSTEM KERMINI.
  2050. 0
  2051.  Kermit under VM/XA and beyond
  2052. 0Recent evolution of IBM's VM operating system has been marked by sharp  discon-
  2053.  tinuities  caused  by, among other things, the transition to Extended Architec-
  2054.  ture (XA) mode.  As a result, there are now two CMS variants of Kermit-370, one
  2055.  for  the traditional systems and one for VM/XA.  The former is now XA-cognizant
  2056.  but not, in IBM's terminology, XA-tolerant.  In other words, it will  run  only
  2057.  in  370  mode or under VM/SP.  The latter variant is fully bimodal and will run
  2058.  in 370, XA, or ESA mode under a bimodal (5.5 or 7 or higher) CMS, but will  not
  2059.  assemble or run under pre-5.5 releases of CMS.  The differences between the two
  2060.  variants are essentially invisible to the user, however,  aside  from  the  an-
  2061.  nouncement  of  the  release number when Kermit starts up.  Both variants care-
  2062.  fully determine whether they are running under VM/XA and, if so, avoid  setting
  2063.  the CP parameters ACNT and TIMER, which VM/XA SP 2 does not support.  Also, the
  2064.  traditional variant halts gracefully if it finds itself running in XA mode.
  2065. 12.2. Program Operation                                                  Page 44
  2066. 0-------------------------------------------------------------------------------
  2067.  Interactive Operation:
  2068. 0To run Kermit-CMS interactively, invoke the program from CMS by typing  KERMIT.
  2069.  When you see the prompt,
  2070. 0  Kermit-CMS>
  2071. 0you may type a Kermit subcommand.  When the subcommand completes, Kermit issues
  2072.  another prompt.  The cycle repeats until you exit from the program.    For  ex-
  2073.  ample:
  2074. 0  .KERMIT
  2075. 0  Kermit-CMS Version 4.3.0 (93/9/30)
  2076.    Enter ? for a list of valid commands
  2077. 0  Kermit-CMS>send foo *
  2078. 0    Files with fn FOO are sent
  2079. 0  Kermit-CMS>receive test spss
  2080. 0    File is received and called TEST SPSS A1
  2081. 0  Kermit-CMS>exit
  2082. 0The  prompt  string under CMS is truly interactive.  In other words, the string
  2083.  (without carriage return or linefeed) appears only when fresh input  is  needed
  2084.  from  the  terminal.   If, for example, Kermit is invoked after several subcom-
  2085.  mands have been stacked up, the stack is read and  executed  before  the  first
  2086.  prompt appears.
  2087. 0
  2088.  Command Line Invocation:
  2089. 0Kermit-CMS  may  also be invoked with command line arguments from CMS.  The ar-
  2090.  guments are interpreted as one or more subcommands to  be  executed  by  Kermit
  2091.  after completion of the initialization.  For instance:
  2092. 0  .KERMIT send test fortran
  2093. 0or
  2094. 0  .KERMIT set debug on # set file type binary # server
  2095. 0Kermit will exit and return to CMS after completing the specified subcommand or
  2096.  subcommands.  Several subcommands may be given on the command line as  long  as
  2097.  they  are separated by the LINEND character, which is number sign in this case.
  2098.  Note that the LINEND delimiter is a function of CP, rather than Kermit, and ap-
  2099.  plies only to commands entered from the terminal and only when LINEDIT is on or
  2100.  when talking to CP itself.  A command line may contain up to 130 characters.
  2101. 12.2. Program Operation                                                  Page 45
  2102. 0-------------------------------------------------------------------------------
  2103.  EXEC Operation:
  2104. 0Like other CMS programs, Kermit-CMS may be invoked from a CMS  EXEC.    Subcom-
  2105.  mands  can  be passed to Kermit using the program stack and/or command line ar-
  2106.  guments.  For example, to start up Kermit-CMS and have it act as a server,  in-
  2107.  clude the line:
  2108. 0  KERMIT server
  2109. 0To  pass  more  than one subcommand, they must be stacked in the order in which
  2110.  they are to be executed.  To start up a Kermit-CMS server with a three  charac-
  2111.  ter CRC, include:
  2112. 0  &STACK set block 3
  2113.    &STACK server
  2114.    KERMIT
  2115. 0Another  way of setting up multiple subcommands would be to collect the subcom-
  2116.  mands into a TAKE file and then issue the TAKE subcommand via the command  line
  2117.  or  program stack.  EXEC's may be executed from Kermit, either directly or from
  2118.  a TAKE file, and Kermit subcommands, in turn, may be issued from EXEC's as long
  2119.  as Kermit is active.  See the TAKE subcommand for more details.
  2120. 0
  2121.  Server mode:
  2122. 0Command  execution  in server mode is different in several respects from normal
  2123.  operation.  First of all, some Kermit subcommands are not allowed (see the list
  2124.  of  subcommands  in  the  Kermit-370 chapter).  Moreover, command errors always
  2125.  terminate any active TAKE file.  Also, commands other than CP commands run in a
  2126.  special  environment  with RUN ON, TIMER OFF, and so forth.  Another difference
  2127.  is that Kermit intercepts all SVC instructions in order to  catch  console  I/O
  2128.  and  transmit  the data to the local Kermit as text packets.  However, some CMS
  2129.  system or user commands may issue console I/O directly to CP, so that some mes-
  2130.  sages  never appear to the local Kermit (except, perhaps, as bad packets).  For
  2131.  non-TTY terminals, such messages are stacked up in the console output queue and
  2132.  appear  all at once when Kermit returns from server mode.  However, some system
  2133.  configurations, especially those including VTAM, are incapable of resuming Ker-
  2134.  mit  protocol  transmission  after  interruption by direct console I/O, so such
  2135.  commands should generally be avoided.
  2136. 0
  2137.  2.3. Kermit-CMS Subcommands
  2138. 0Kermit-CMS supports all the subcommands described in  the  Kermit-370  chapter.
  2139.  In  addition,  there are two more, both of which can be issued as remote Kermit
  2140.  commands when Kermit-CMS is in server mode.  The first is "CMS", which is  just
  2141.  a  synonym  for  the  generic  subcommand  "HOST".    The second is "CP", which
  2142.  specifically issues a command to CP.  In most circumstances, the latter is  not
  2143.  needed, since CMS will pass along CP commands to CP.
  2144. 0This  section concentrates on the subcommands that have special form or meaning
  2145.  for Kermit-CMS.   These  are  ordered  alphabetically.    See  the  chapter  on
  2146.  Kermit-370 for further details.
  2147. 12.3. Kermit-CMS Subcommands                                             Page 46
  2148. 0-------------------------------------------------------------------------------
  2149.                            THE CP AND CMS SUBCOMMANDS
  2150. 0Syntax: CP or CMS text of command
  2151. 0Although  Kermit-CMS does not have a full set of its own subcommands for manag-
  2152.  ing local files, it provides those services through the operating system.   You
  2153.  can issue any CP or CMS command, but if Kermit-CMS has been invoked as a normal
  2154.  user-area program, rather than as a high-memory "resident" program  or  nucleus
  2155.  extension,  other  user-area CMS commands (such as COPYFILE) are illegal.  Even
  2156.  then, you can list, type, rename or delete files, send  messages,  and  so  on.
  2157.  The CMS subcommand under Kermit is synonymous with the HOST subcommand.
  2158. 0
  2159.                                THE CWD SUBCOMMAND
  2160. 0Syntax: CWD letter
  2161. 0The  CWD  (Change  Working  Directory)  subcommand  establishes  a  new default
  2162.  ("home") CMS disk.  letter may be the mode letter of any accessed disk.    Sub-
  2163.  sequent  file transfers take place preferentially to and from the default disk.
  2164.  The initial home disk is "A".  Note: setting the home disk in Kermit has no ef-
  2165.  fect on the CMS search order.
  2166. 0
  2167.                             THE DIRECTORY SUBCOMMAND
  2168. 0Syntax: DIRECTORY [filespec]
  2169. 0Under  Kermit-CMS,  the  DIRECTORY  subcommand is identical to the CMS LISTFILE
  2170.  command.
  2171. 0
  2172.                                THE GET SUBCOMMAND
  2173. 0Syntax: GET [foreign-filespec [filespec]]
  2174. 0The GET subcommand tells Kermit to request a file or file group from the  other
  2175.  system, which must have a Kermit running in server mode.  The syntax is compli-
  2176.  cated by the allowance of two forms for the foreign-filespec, just  as  in  the
  2177.  SEND  subcommand.    Here  the  parsing  is  based  on  the  number  of "words"
  2178.  (blank-delimited strings) in the subcommand argument,  which  can  be  anything
  2179.  from  one  to  five.  If the number is anything but four, the interpretation is
  2180.  unambiguous, but when there are four words, the first word plays the key  role.
  2181.  If it has more than eight characters or contains a "." or "/", it is assumed to
  2182.  be the whole foreign-filespec; otherwise, it is assumed to be the first of  two
  2183.  words that, when joined by a ".", make up the filespec on the other system.  If
  2184.  this subcommand is issued without any arguments at all, Kermit-CMS will  prompt
  2185.  the user for both foreign and native filespecs.
  2186. 12.3. Kermit-CMS Subcommands                                             Page 47
  2187. 0-------------------------------------------------------------------------------
  2188.                                THE GIVE SUBCOMMAND
  2189. 0Syntax: GIVE table-name filespec
  2190. 0This  subcommand  compares  the named translation table with its default values
  2191.  and saves the differences in a  TAKE  file  named  filespec.    The  format  of
  2192.  filespec  is  fn  [ft  [fm]].   The default filetype is "TAKE", and the default
  2193.  filemode is that of the "home" disk.  See the CWD subcommand.
  2194. 0
  2195.                                THE HELP SUBCOMMAND
  2196. 0Syntax: HELP subcom
  2197. 0This subcommand displays the relevant part of the Kermit  help  file  when  the
  2198.  latter is a partitioned data set.  Kermit verifies that the argument is a valid
  2199.  Kermit subcommand (or a non-ambiguous abbreviation) and then displays the  cor-
  2200.  responding  member  of  the PDS.  For the SET subcommand, individual parameters
  2201.  may also be specified, as in
  2202. 0  HELP SET BLOCK-CHECK
  2203. 0If no subcommand name is included, Kermit displays the  member  that  gives  an
  2204.  overview  of  Kermit  operation.   Kermit looks for a help file with a filename
  2205.  matching the Kermit command itself, but will settle for one with a filename  of
  2206.  KERMIT if necessary.  Thus, the response to the HELP subcommand may depend upon
  2207.  which Kermit module is invoked.  The choice of whether to format the help  file
  2208.  as  a  PDS  is  an option at installation time.  If the installer has chosen to
  2209.  leave it as an ordinary sequential file, or if no help file has been  installed
  2210.  recently,  Kermit will fall back on the old behavior of the HELP subcommand: it
  2211.  will issue the CMS HELP command for Kermit and  therefore  display  the  entire
  2212.  file.    Since the help file is rather long, this subcommand is not recommended
  2213.  for users with line-mode terminals, unless the help file is installed as a PDS.
  2214.  See the installation guide for more details about the help files.
  2215. 0
  2216.                              THE RECEIVE SUBCOMMAND
  2217. 0Syntax: RECEIVE [filespec]
  2218. 0The  RECEIVE  subcommand  tells Kermit to receive a file or file group from the
  2219.  other system.  You must issue the corresponding SEND subcommand  to  the  other
  2220.  Kermit.
  2221. 0The format of filespec is:
  2222. 0  filename filetype [filemode]
  2223. 0If  the  optional filespec is omitted, Kermit-CMS will use the name(s) provided
  2224.  by the other Kermit.  If that name is not a legal  CMS  file  name,  Kermit-CMS
  2225.  will  delete  excess  characters  and  will change illegal characters to under-
  2226.  scores.  A filespec in the subcommand indicates what  name  the  incoming  file
  2227.  should be given.  The filespec may include a filemode to designate the destina-
  2228.  tion disk.  If none is provided, the file will be saved on the "home" disk with
  2229.  filemode  number  "1".    If  you  want  to  use  the same name but a different
  2230.  filemode, specify "= = FM".  Wildcards may  not  be  used.    If  the  optional
  2231. 12.3. Kermit-CMS Subcommands                                             Page 48
  2232. 0-------------------------------------------------------------------------------
  2233.  filespec  is  provided,  but more than one file arrives, the first file will be
  2234.  stored under the given filespec, and the remainder will be stored  under  their
  2235.  own names on the "home" disk.  If, however, "= = FM" is used, all files will be
  2236.  placed onto the specified disk.
  2237. 0For purposes of truncation  and  folding,  the  maximum  record  length  for  a
  2238.  received file is 65535 if RECFM is V and "LRECL" if RECFM is F.
  2239. 0If  the  incoming  file has the same name as an existing file, the action taken
  2240.  depends on the FILE COLLISION setting.  The possible settings and  their  mean-
  2241.  ings  are  given  in  the  Kermit-370 chapter.  Two of the settings (BACKUP and
  2242.  RENAME) require  that  Kermit-CMS  change  the  incoming  name  so  as  not  to
  2243.  obliterate  a  pre-existing file.  It attempts to find a unique name by succes-
  2244.  sively modifying the original and checking for the existence of such a file  at
  2245.  each  step.   The procedure begins by truncating the filetype to six characters
  2246.  if necessary and then appending "$0".  If a file by that  name  exists,  Kermit
  2247.  then  replaces  the "0" with a "1".  It continues in this manner up to "9", and
  2248.  if an unused name cannot be found, the transfer fails.
  2249. 0
  2250.                                THE SEND SUBCOMMAND
  2251. 0Syntax: SEND [filespec[<options>] [foreign-filespec]][, ...]
  2252. 0The SEND subcommand causes a file or file group to be sent from CMS to the Ker-
  2253.  mit on the other system.  filespec takes the form:
  2254. 0  filename filetype [filemode]
  2255. 0or
  2256. 0  fn.ft.[fm]
  2257. 0but  the  filemode  is  optional  only if the foreign-filespec is omitted.  The
  2258.  "dotted" notation is interpreted by changing up to two  dots  into  spaces,  so
  2259.  only  the  normal  CMS-style form is "real" as far as Kermit is concerned.  For
  2260.  details on the options, see the description of SEND in the Kermit-370  chapter.
  2261.  Note  that  no  blanks  may intervene between the CMS filespec and the options,
  2262.  even though the filespec itself has imbedded blanks (either explicitly  or  im-
  2263.  plicitly through the "dotted" notation).
  2264. 0The  filespec may contain the wildcard characters "*" or "%".  If it does, then
  2265.  all matching files will be sent.  If, however, a file exists by the  same  name
  2266.  on  more  than one disk, only the first one Kermit-CMS encounters, according to
  2267.  the disk search order, is sent.  See also the CWD subcommand.
  2268. 0The foreign-filespec, if any, is used for the file header of the outgoing file,
  2269.  replacing  the  usual  filename.filetype  copied from the CMS filespec.  It may
  2270.  take one of two forms:
  2271. 0  filename filetype
  2272. 0or
  2273. 0  arbitrary-string
  2274. 12.3. Kermit-CMS Subcommands                                             Page 49
  2275. 0-------------------------------------------------------------------------------
  2276.  Normally, this form of the SEND subcommand is used only for  single  files  be-
  2277.  cause  the  foreign-filespec  is  used only for the first file of a group (sub-
  2278.  sequent files having default headers).  However, in the two-token form  of  the
  2279.  foreign-filespec  either  the name or type may be an Equals sign "=" to signify
  2280.  that the corresponding CMS name or type is to be retained in the  file  header.
  2281.  In  that  case,  the partial renaming carries through an entire group of files.
  2282.  It is the user's responsibility to prevent such partial renaming  from  sending
  2283.  duplicate  file headers within a file group.  If both filespecs are omitted for
  2284.  this subcommand, Kermit will prompt separately for  each,  and  the  respective
  2285.  syntaxes  are  exactly as described above, except the filemode is optional even
  2286.  if a foreign-filespec is to be supplied.  This  prompting  mode  is  especially
  2287.  useful when more than one file (or file group) is to be sent, since the command
  2288.  line is limited to 130 characters.
  2289. 0Trailing blanks in a text file with RECFM F  are  deemed  superfluous  and  are
  2290.  stripped off when Kermit-CMS downloads the file.  In order to treat such blanks
  2291.  as significant, you must convert the record format to V, for example, by  using
  2292.  COPYFILE  with  the  "RECFM V" option.  Note: you must not use XEDIT for such a
  2293.  conversion, since it also strips trailing blanks from files with RECFM V.
  2294. 0
  2295.                                THE SET SUBCOMMAND
  2296. 0Syntax: SET parameter [value]
  2297. 0The SET subcommand establishes or modifies various parameters controlling  file
  2298.  transfers.    The following SET parameters are available in Kermit-CMS, but not
  2299.  in Kermit-370 in general:
  2300. 0DESTINATION         "Home" disk.
  2301.  FILE
  2302.    LRECL             Logical Record length for incoming file.
  2303.    RECFM             Record format for incoming files.
  2304.  SEARCH-ALL          Determine the default disk search scope.
  2305. 0
  2306.  SET DESTINATION
  2307. 0Syntax: SET DESTINATION letter
  2308. 0This subcommand is equivalent to the CWD subcommand (q.v.).
  2309. 0
  2310.  SET FILE LRECL
  2311. 0Syntax: SET FILE LRECL number
  2312. 0This sets the logical record length for incoming files to a number  from  1  to
  2313.  65535  (64K-1).   This variable is used only for fixed-format and binary files.
  2314.  The default is 80.
  2315. 12.3. Kermit-CMS Subcommands                                             Page 50
  2316. 0-------------------------------------------------------------------------------
  2317.  SET FILE RECFM
  2318. 0Syntax: SET FILE RECFM option
  2319. 0This sets the record format to use for  incoming  files.    Valid  options  are
  2320.  "Fixed" and "Variable" (the default).  Fixed-format records are padded, folded,
  2321.  or truncated, as needed, to the current LRECL.
  2322. 0
  2323.  SET PROMPT
  2324. 0Syntax: SET PROMPT [string]
  2325. 0This sets the prompt string, just as in other variants  of  Kermit-370,  except
  2326.  that  the string is padded with the current HANDSHAKE character, if any, unless
  2327.  the string is empty or already ends with that character.
  2328. 0
  2329.  SET SEARCH-ALL
  2330. 0Syntax: SET SEARCH-ALL ON or OFF
  2331. 0ON      If the user omits the filemode from a SEND subcommand (or a GET request
  2332.          via  the  other  Kermit), Kermit-CMS will search all accessed disks for
  2333.          the named file or files.  The search follows the usual search order.
  2334. 0OFF     If the filemode  is  not  specified,  only  the  "home"  disk  and  its
  2335.          read-only extensions will be searched for matching files.  (Default.)
  2336. 0
  2337.                               THE SPACE SUBCOMMAND
  2338. 0Syntax: SPACE [letter]
  2339. 0This  subcommand displays the storage allocation on the specified CMS mini-disk
  2340.  or SFS directory.  If letter is omitted, the default disk specified by the  CWD
  2341.  subcommand  is displayed.  Aside from this default, the subcommand is identical
  2342.  with CMS QUERY DISK.
  2343. 0
  2344.                                THE TAKE SUBCOMMAND
  2345. 0Syntax: TAKE filespec
  2346. 0Execute Kermit subcommands from the specified file, where filespec has the for-
  2347.  mat  fn [ft [fm]].  The default filetype is "TAKE", and the default filemode is
  2348.  "*".
  2349. 0Kermit subcommands may also be executed from CMS EXEC's, so that the TAKE  sub-
  2350.  command  is, in a sense, superfluous under CMS.  In CMS terminology, Kermit es-
  2351.  tablishes a Kermit subcommand environment, and EXEC's written in EXEC 2 or REXX
  2352.  may  invoke  subcommands  within that environment.  For example, to display the
  2353.  current packet checksum type, an EXEC 2 would issue
  2354. 0  &SUBCOMMAND KERMIT SHOW BLOCK-CHECK
  2355. 12.3. Kermit-CMS Subcommands                                             Page 51
  2356. 0-------------------------------------------------------------------------------
  2357.  and a REXX macro would issue
  2358. 0  Address KERMIT 'SHOW BLOCK-CHECK'
  2359. 0There is one important difference between executing a TAKE file  and  an  EXEC:
  2360.  the  former may issue a QUIT or EXIT subcommand, but the latter may not.  Also,
  2361.  a Kermit subcommand issued from an EXEC returns a completion code according  to
  2362.  the current error status (see the table under "After Returning from Kermit-370"
  2363.  in the Kermit-370 chapter).  An EXEC could therefore be set  up  to  react  ap-
  2364.  propriately to file transmission errors or other unpredictable events.  A third
  2365.  difference is that, although an EXEC may issue a TAKE  subcommand,  the  latter
  2366.  will not be executed until after the EXEC processor returns to Kermit.
  2367. 0
  2368.  2.4. How to build an executable Kermit-CMS
  2369. 0Before  attempting  to  build Kermit-CMS, look in the Kermit distribution under
  2370.  IKCKER for an installation document, as well  as  "beware",  help,  and  update
  2371.  files,  and  read  them  first.  They will probably contain information that is
  2372.  more current than what you see here.  In fact, IKCKER INS contains an EXEC  for
  2373.  installing Kermit nearly automatically.
  2374. 0Kermit-CMS  consists  at  present of a large assembly and a small optional one.
  2375.  The large assembly (KERMIT ASSEMBLE) contains the Kermit program, and the small
  2376.  one  (KERMBOOT  ASSEMBLE)  is  a bootstrap program for loading Kermit into high
  2377.  memory and running it.  KERMBOOT can be  useful  under  CMS/SP  Release  3  and
  2378.  below,  but  is  not  needed  under  Release  4 and cannot be used at all under
  2379.  Release 5 and above.  Although KERMBOOT is all in one file in the  Kermit  dis-
  2380.  tribution,  the  source  for  Kermit itself is in many pieces, some generic for
  2381.  Kermit-370 and some specific to CMS.  All the necessary pieces are sequenced in
  2382.  columns  73-80 so that the numbers form a strictly increasing sequence when the
  2383.  pieces are correctly "pasted" together.    It  is  important  to  preserve  the
  2384.  original  sequence  numbers  so  that  updates,  if  any, can be applied to the
  2385.  source.
  2386. 0To create a runnable version (the hard way):
  2387. 0   1. Combine the following "ASM" files from the Kermit distribution  into
  2388.        a single file with "RECFM F" and "LRECL 80": IK0DOC, IK0MAC, IKCMAC,
  2389.        IK0DEF, IK0MAI, IK0COM,  IK0CMD,  (optional:  IK0KAN),  IKCUTL,  and
  2390.        IK0PRO.   The resulting file is the composite source for Kermit-CMS,
  2391.        called KERMIT ASSEMBLE.  This source must retain  the  original  se-
  2392.        quence  numbers  in  columns  73-80  (in other words, be sure not to
  2393.        resequence the source accidentally using the editor!)
  2394. 0   2. Copy or rename IKCBOO ASM from the Kermit distribution (if  desired)
  2395.        to a file called KERMBOOT ASSEMBLE with "RECFM F" and "LRECL 80".
  2396. 0   3. GLOBAL the necessary MACLIBs.  Under VM/SP and VM/XA SP 2, these are
  2397.        DMSSP, CMSLIB, TSOMAC, and OSMACRO.  Under VM/XA SP  2.1,  they  are
  2398.        DMSOM, DMSGPI, and OSMACRO.
  2399. 0   4. Assemble the source file(s).
  2400. 0   5. Load one file into memory via: "LOAD KERMIT" or "LOAD KERMBOOT".  In
  2401.        the former case, the entire Kermit program is  now  loaded;  in  the
  2402. 12.4. How to build an executable Kermit-CMS                              Page 52
  2403. 0-------------------------------------------------------------------------------
  2404.        latter,  only  a  bootstrap program which expects to find the object
  2405.        file "KERMIT TEXT" at run time.  Under CMS/SP Release 4  and  above,
  2406.        there is a third and better option, namely, "LOAD KERMIT (RLDSAVE)".
  2407. 0   6. Create  the  executable called "KERMIT MODULE" via: "GENMOD KERMIT".
  2408.        Alternatively (under CMS/SP Release 3 and below), create both KERMIT
  2409.        and  KERMBOOT  modules  to  give  the  user a choice of user-area or
  2410.        high-memory execution.  Since Kermit-CMS is  serially  reusable,  it
  2411.        can  be  reinvoked  in the user area with the START command, but the
  2412.        high-memory version must be reloaded each time.  If Kermit is loaded
  2413.        using  the  RLDSAVE option (Release 4 and above), the module can, in
  2414.        fact, be run either way; the command  "NUCXLOAD  KERMIT"  will  load
  2415.        Kermit  "permanently" as a nucleus extension for invocation at need.
  2416.        Note: the nucleus extension can be removed by the command  "NUCXDROP
  2417.        KERMIT".
  2418. 0To  create a runnable version the easy way, extract IKCINS EXEC from IKCKER INS
  2419.  and run it.  When it is finished, you may perform any desired  tests  and  then
  2420.  move  the MODULE and HELP files to their permanent locations.  It is useful for
  2421.  the Kermit module and help file to have the same filename  and  reside  on  the
  2422.  same mini-disk.
  2423. 0If your site's ASCII/EBCDIC translation table for TTY lines does not conform to
  2424.  the one listed in the appendix (which in turn conforms to the one given in  the
  2425.  IBM   System/370   Reference   Summary),   then   enter   the  appropriate  SET
  2426.  ATOE/ETOA/TATOE/TETOA subcommands in the  SYSTEM  KERMINI  file,  which  should
  2427.  reside  on  the  same  disk  as  KERMIT MODULE (and KERMIT TEXT).  NOTE: If the
  2428.  ASCII/EBCDIC translation is not invertible, Kermit will not and cannot work.
  2429. 0
  2430.  2.5. What's New
  2431. 0Below is a list of the CMS-specific features in  Version  4.3.0  of  Kermit-CMS
  2432.  added since the previous major release, Version 4.2, in March of 1990.  For the
  2433.  list of generic additions, see the chapter on Kermit-370.
  2434. 0   1. New, automated installation procedure collected as an EXEC contained
  2435.        in  the  installation  guide.  This includes selection of XA support
  2436.        and SFS support as appropriate.
  2437. 0   2. Help for individual Kermit subcommands from the HELP subcommand.
  2438. 0   3. Improved recovery from I/O errors during file transfer.
  2439. 0   4. Improved execution of CMS commands under Kermit with SYSCMD ON.
  2440. 0   5. File names no longer considered to "collide" with files existing  on
  2441.        read-only extensions.
  2442. 0   6. Support for disk space check in advance of receiving a file into SFS
  2443.        and more accurate space check for ordinary mini-disks.
  2444. 0   7. Improved SFS wildcard sending.
  2445. 0   8. Small bug fixes.
  2446. 1IBM System/370 Kermit                                                   Page 53
  2447. 0-------------------------------------------------------------------------------
  2448.  2.6. What's Missing
  2449. 0Work on Kermit-CMS will continue.  Features that need to be improved  or  added
  2450.  include:
  2451. 0   - Allow  timeouts  so Kermit-CMS does not wait forever if a packet does
  2452.       not arrive in a timely fashion.  This is not possible  under  CMS  at
  2453.       present.
  2454. 0   - Implement file archiving.
  2455. 0   - Add a SET REPEAT subcommand.
  2456. 0   - Implement public server mode, allowing a disconnected virtual machine
  2457.       to provide Kermit services via CP DIAL.
  2458. 0   - Add a CONNECT subcommand.  This may be impossible.
  2459. 0   - Intercept CP messages during protocol mode,  rather  than  just  sup-
  2460.       pressing  them.    Display  the messages later or log them or send in
  2461.       packets as appropriate.
  2462. 0   - Define EXEC variables from Kermit by analogy with the  XEDIT  EXTRACT
  2463.       subcommand.
  2464. 0   - Set file date/time on received files from the information sent by the
  2465.       other Kermit.
  2466. 0Anyone interested in working on these or other improvements should first get in
  2467.  touch  with  the Center for Computing Activities at Columbia University to find
  2468.  out if someone else has already begun a similar project (and, if so, who).
  2469. 1IBM System/370 Kermit                                                   Page 54
  2470. 0-------------------------------------------------------------------------------
  2471.  Index
  2472. 0          3174   1, 16                    Electronic mail   9
  2473.            3708   17                       End of file   20
  2474.                                            Error codes   36, 42
  2475.            Alternate lines   23            EXEC   50
  2476.            Appending   21                  EXEC operation   45
  2477.            Arabic   3, 26                  Extended ASCII   16
  2478.            ASCII-to-EBCDIC   15
  2479.            Attributes.   See   File   at-  File attributes   2, 16, 30
  2480.                    tributes                File disposition   9
  2481.                                            File management   46
  2482.            Batch jobs   9                  File renaming   21
  2483.            Binary files   1, 12, 21, 22    File truncation   20
  2484.            Blanks                          Filename collision   21, 48
  2485.               preserving  trailing    22,  Flow control   32
  2486.                    49                      Folding   12, 21, 48
  2487.               stripping   2, 22, 24        Foreign   10, 23
  2488.               trailing   2, 24             Front end   1
  2489.            BLKSIZE   2                     Full screen   11, 32
  2490.            Block check   16
  2491.                                            GET   11, 46
  2492.            Cancelling  a  file   transfer  GIVE   11, 47
  2493.                    13                      Greek   3, 26
  2494.            Character sets   3, 20, 26
  2495.            CICS   19, 21                   Handshake   23, 32, 43
  2496.            CMS   19, 21, 40                Hebrew   3, 26
  2497.            Code pages   3                  HELP   47
  2498.                 See also   Character sets  Home disk   41, 46, 49
  2499.            Collision.  See  Filename col-  Host commands   11, 25
  2500.                    lision
  2501.            Command echoing   25, 31        IBM   1, 40
  2502.            Command prefix   10, 12, 25     Incomplete files   12, 23
  2503.            Completion codes   36           Initialization  files    2, 8,
  2504.                 See also   Error codes             21, 26,  28,  40,  42,
  2505.            Control characters   17, 31             43, 52
  2506.            Controller   16
  2507.            CRLF   2, 22                    Kanji   3, 20, 26
  2508.            CSW   19                        Katakana   3, 26
  2509.            CWD   46                        KERMBOOT   46, 52
  2510.            Cyrillic   3, 20, 26
  2511.                                            Languages   3
  2512.            Debugging   17                  Local   10
  2513.            Delimiter   44                  LOCAL-ECHO   32
  2514.            DIRECTORY   46                  Log files   40
  2515.            Discarding files   21, 23, 38   Long packets   12, 28, 31, 43
  2516.                 See also   DELETE          LRECL   2, 22, 40
  2517.            DOS-4   2
  2518.            Dumping storage   18            MACLIB   51
  2519.                                            Mail   9
  2520.            EBCDIC-to-ASCII   15                 See  also      Electronic
  2521.            ECHO   10                               mail
  2522.                 See also   Command  echo-  Margins   24
  2523.                    ing                     MTS   2
  2524.            Eighth-bit prefix   27, 29      MUSIC   19, 21
  2525. 1IBM System/370 Kermit                                                   Page 55
  2526. 0-------------------------------------------------------------------------------
  2527.            Optimum packet size   13, 24    Translation   1, 3, 27
  2528.            Overwriting files   22          Translation  tables     3, 11,
  2529.                 See also   Filename  col-          26, 42, 47, 52
  2530.                    lision                  Transparent mode   10, 32
  2531.                                            Truncation   12, 21, 48
  2532.            Packet size   13, 28                 See also      File  trun-
  2533.            Parity   29, 32                         cation
  2534.            Prefix.      See      Command,  TSO   19, 21
  2535.                    Eighth-bit, Foreign     TTY   1, 16, 32, 40, 43
  2536.            Prefixing   17                  Type   13, 14
  2537.            Printing files   9
  2538.            Prompt   24                     User area   46, 52
  2539. 0          Quote. See Prefix               VM/XA   43
  2540. 0          Raw transmission   10, 32       Warning   21
  2541.            RDBUF   42                      Wildcard   42
  2542.            RECEIVE   11, 12, 47            Wildcards   48
  2543.            RECFM   2                       WRBUF   42
  2544.            Reconnecting   43
  2545.            Records   2                     XECHO   10
  2546.            Remote   10
  2547.            RENAME   21
  2548.            Renaming files   21
  2549.                 See also   File renaming
  2550.            ROSCOE   19, 21
  2551. 0          Screen refresh   32
  2552.            Search order   41, 46, 48, 50
  2553.            SEND   11, 12, 48
  2554.            SEND delay   20
  2555.            Series/1   1, 16, 40, 43
  2556.            SERVER   13
  2557.            SET   14, 49
  2558.            SHOW   30
  2559.            SNA   1, 16
  2560.            SPACE   50
  2561.            STATUS   30
  2562.            STOP   31
  2563.            Stripping blanks. See Blanks
  2564.            Subcommand prefix. See Command
  2565.                    prefix
  2566.            Submitting jobs   9
  2567.                 See also   Batch jobs
  2568. 0          Tabs   25
  2569.            TAKE   31, 50
  2570.            TDUMP   31
  2571.            TEST   26
  2572.            TGET   19
  2573.            Thai   3
  2574.            Timeout   24, 29, 32
  2575.            TPUT   19
  2576.            Tracing execution   18, 31
  2577.            Trailing blanks. See Blanks
  2578.            Transaction log   12, 31
  2579.