home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / cpm86 / c86ker.txt < prev    next >
Text File  |  2020-01-01  |  24KB  |  508 lines

  1.  
  2.  
  3.  
  4. 1. CP/M-86 KERMIT
  5.  
  6. Authors:    Bill  Catchings,  Columbia  University; Ron Blanford, University of
  7.             Washington; Richard Garland, Columbia University.
  8. Language:   Digital Research ASM86
  9. Version:    2.9
  10. Date:       December 1984
  11. Documentation:
  12.             Frank da Cruz, Columbia
  13.  
  14. This  version  of  KERMIT is designed to support any CP/M-86 system.  So far it
  15. supports the DEC Rainbow-100 and the NEC Advanced Personal Computer (APC).   It
  16. is very similar to CP/M-80 and MS DOS KERMIT.
  17.  
  18.  
  19. CP/M-86 KERMIT-86 Capabilities At A Glance:
  20.  
  21.   Local operation:                   Yes
  22.   Remote operation:                  No
  23.   Transfers text files:              Yes
  24.   Transfers binary files:            Yes
  25.   Wildcard send:                     Yes
  26.   ^X/^Y interruption:                Yes
  27.   Filename collision avoidance:      Yes
  28.   Can time out:                      Yes
  29.   8th-bit prefixing:                 Yes
  30.   Repeat count prefixing:            No
  31.   Alternate block checks:            No
  32.   Terminal emulation:                Yes, uses PC firmware (VT100)
  33.   Communication settings:            Yes; duplex, parity
  34.   Transmit BREAK:                    Yes
  35.   IBM communication:                 Yes
  36.   Transaction logging:               No
  37.   Session logging (raw download):    Yes
  38.   Raw upload:                        No
  39.   Act as server:                     No
  40.   Talk to server:                    Yes; SEND, GET, FIN, BYE
  41.   Advanced commands for servers:     No
  42.   Local file management:             Yes
  43.   Handle file attributes:            No
  44.   Command/init files:                Yes
  45.   Printer control:                   No
  46.  
  47.  
  48.                           CP/M-86 KERMIT DESCRIPTION
  49.  
  50. Since  Kermit-86  runs  on  a  standalone micro, it is always in control of the
  51. screen -- it is always local.  Thus, it always keeps the  screen  updated  with
  52. the  file  name and the packet number, whether sending or receiving.  Kermit-86
  53. is capable of timing out  an  input  request,  and  can  thus  break  deadlocks
  54. automatically.   In most cases, however, this is not desirable because the KER-
  55. MIT on the other side is most likely better able to handle the timeouts; there-
  56. fore, Kermit-86's timer is normally not used.
  57.  
  58. If  despite  the  timeout capability, the transmission appears to be stuck (and
  59. you can tell that this has happened if the screen fails to change  for  a  long
  60.  
  61.  
  62.  
  63. while)  you  can  type  carriage return to have the micro do what it would have
  64. done on a  timeout, namely NAK the expected packet to cause to foreign host  to
  65. send  it  again  (or,  if the micro is sending, to retransmit the last packet).
  66. Micro/micro or micro/IBM-mainframe transfers could require this kind of  manual
  67. intervention.
  68.  
  69. File transfers may be interrupted in several ways.
  70.  
  71. Control-C       This will return you to Kermit-86 command level immediately, so
  72.                 that you can connect back to the remote  system,  or  take  any
  73.                 other desired action.
  74.  
  75. Control-X       When  sending  a  file,  this will terminate the sending of the
  76.                 current file with a signal to the KERMIT on the other  side  to
  77.                 discard  what  it  got  so  far.  If there are more files to be
  78.                 sent, KERMIT-86 will go on to the next one.  When  receiving  a
  79.                 file, KERMIT-86 will send a signal to the remote KERMIT to stop
  80.                 sending this file.  If the remote KERMIT understands this  sig-
  81.                 nal  (not  all  implementations  of KERMIT do), it will comply,
  82.                 otherwise the file will keep  coming.    In  either  case,  the
  83.                 remote KERMIT will go on to the next file in the group, if any.
  84.  
  85. Control-Z       Like  Control-X,  except  if a file group is being transmitted,
  86.                 this will stop the transmission of the entire group.  If only a
  87.                 single  file  is  being  transmitted,  it  works  exactly  like
  88.                 Control-X.
  89.  
  90. Carriage Returns
  91.                 If you type carriage return repeatedly Kermit-86 will retry the
  92.                 current packet up to its retry limit (somewhere between  5  and
  93.                 16  times)  and then, if no valid response was received, return
  94.                 to Kermit-86 command level.
  95.  
  96. When KERMIT-86 is started, it looks for the file KERMIT.INI.  If found, it  ex-
  97. ecutes  KERMIT-86  commands  from  it  before  prompting you for commands.  The
  98. KERMIT-86 prompt looks like this:  
  99.  
  100.   Kermit-86 B3>
  101.  
  102. in which "B" is your current default disk and "3" is the current  default  user
  103. number.
  104.  
  105.  
  106. 1.1. Kermit-86 Commands
  107.  
  108. KERMIT-86  uses  the DECSYSTEM-20 keyword style command language.  Each keyword
  109. may be abbreviated to its minumum unique length.  "?" may be typed to request a
  110. menu  of the available options for the current field at any point in a command.
  111. ESC may be typed at any point in a command to fill out the current  keyword  or
  112. filename;  if sufficient characters have not been typed to identify the current
  113. field uniquely, KERMIT-86 will sound a beep and allow you to continue from that
  114. point.
  115.  
  116. CONNECT Establish  a "virtual terminal" connection to any host that may be con-
  117.         nected to the serial port, i.e. pass all typein to the serial port  and
  118.         display  all  input  from  the  serial  port  on  the screen, using the
  119.  
  120.  
  121.  
  122.         system's own built-in support for  ANSI  (VT100-like)  screen  control.
  123.         When you issue the CONNECT command, the PC will print a message telling
  124.         you how to get back by typing an an escape sequence, an uncommonly-used
  125.         control character, normally CTRL-backslash, followed by a single letter
  126.         "command".
  127.  
  128.         C   Close Connection, return to Kermit-86> command level.
  129.         ?   List available single-character commands.
  130.         B   Send a BREAK signal.
  131.         Q   Quit logging the remote session.
  132.         R   Resume logging the remote session.
  133.         L   Toggle logging.
  134.         ^\  (or whatever - a second copy of the escape character) Send the  es-
  135.             cape character itself to the remote host.
  136.  
  137. SEND filespec
  138.         Send file(s) specified by filespec to  the  remote  Kermit,  using  the
  139.         prevailing file mode (ASCII or BINARY; see SET).  The filespec may con-
  140.         tain CP/M wildcards.
  141.  
  142. RECEIVE Receive file(s) from the remote Kermit.  Store  them  under  the  names
  143.         provided in the file headers supplied by the remote host.  If the names
  144.         aren't legal, use as many legal characters from the  name  as  possible
  145.         (see  the  description  of  SET FILE-WARNING below).  If there's a con-
  146.         flict, and FILE-WARNING is ON, warn the user and try to build a  unique
  147.         name  for  the file by adding "&" characters to the name.  You may also
  148.         provide an optional file name in the RECEIVE command; if  you  do,  the
  149.         incoming  file will be stored under the name you specify.  If more than
  150.         one file arrives, only the first will be stored under the  given  name,
  151.         unless  you  included  wildcard  characters in the RECEIVE filespec; in
  152.         that case, the filespec will be used as a mask for incoming  filenames.
  153.         For  instance, you told the remote Kermit to send *.ASM, you could tell
  154.         KERMIT-86 to "receive *.A86", thereby changing the filetype of all  the
  155.         incoming files.
  156.  
  157. GET filespec
  158.         When Kermit-86 is talking to a Kermit Server on the  host,  you  should
  159.         use the GET command to request the server to send files to you, for ex-
  160.         ample: get hlp:k*.hlp
  161.  
  162. BYE     When talking to a remote Kermit Server, this  command  shuts  down  the
  163.         server  and  logs it out, and also exits from Kermit-86 to CP/M command
  164.         level.
  165.  
  166. LOGOUT  Like BYE, but leaves you at Kermit-86 command level.
  167.  
  168. FINISH  Like LOGOUT, but shuts down the remote server without logging  it  out.
  169.         Leaves  you  at  Kermit-86  command level; a subsequent CONNECT command
  170.         should put you back at host system command level.
  171.  
  172. EXIT    Exit from KERMIT-86 back to CP/M.
  173.  
  174. QUIT    Synonym for EXIT.
  175.  
  176. SET parameter [value]
  177.         Set the specified parameter to the specified value.  Possible settings:
  178.  
  179.  
  180.  
  181.         BAUD    Change  the baud rate of the communications port.  This command
  182.                 only works on some systems, and its actual operation  can  vary
  183.                 from  system  to  system.  Type SET BAUD followed by a question
  184.                 mark, and follow the directions.  On systems that do  not  sup-
  185.                 port this command, you must set the port baud rate from CP/M or
  186.                 other setup mechanism outside of KERMIT-86.
  187.  
  188.         DEBUG   ON or OFF.  If  ON,  displays  incoming  and  outbound  packets
  189.                 during file transfer.  OFF by default.
  190.  
  191.         DEFAULT-DISK disk/user
  192.                 Specify default disk and user number for subsequent file recep-
  193.                 tion and transmission.  The specification following the command
  194.                 must be in one of the following forms:
  195.  
  196.                     d:  = go to drive d (A through P) without changing user
  197.                     u:  = go to user u (0 through 15) without changing drive
  198.                     du: = go to drive d and user u
  199.                     :   = go to the defaults when Kermit was loaded
  200.  
  201.                 Whenever a drive is specified, even if it is the  same  as  the
  202.                 current default drive, the drive is logged in so that disks can
  203.                 be swapped without exiting Kermit to type  control-C.    Kermit
  204.                 restores the original drive and user upon termination.
  205.  
  206.         ESCAPE  Change  the  escape character for virtual terminal connections.
  207.                 Select a character in the control range that you  will  not  be
  208.                 likely  to  need  at  the  remote  host; type the new character
  209.                 literally.   Certain  characters,  like  Control-X,  cannot  be
  210.                 specified.
  211.  
  212.         FILE-TYPE
  213.                 Tells KERMIT-86 what kind of file it is sending, so that KERMIT
  214.                 can  correctly  determine the end of the file.  SET FILE BINARY
  215.                 means to send all the 128-byte blocks of  the  file,  including
  216.                 the last block in its entirety; SET FILE ASCII is used for text
  217.                 files, and transmission stops when the first Control-Z  is  en-
  218.                 countered anywhere in the file (this is the CP/M convention for
  219.                 marking the end of a text file).   If  binary  transmission  is
  220.                 used  on  a text file, some extraneous characters (up to 127 of
  221.                 them) may appear at the end of the file on the  target  system.
  222.                 If ASCII transmission is used on a binary file, the entire file
  223.                 will not be sent if it happens to contain any data  bytes  that
  224.                 correspond to Control-Z.  ASCII is the default.
  225.  
  226.         FLOW-CONTROL
  227.                 Select the desired type of flow control to be used on the  com-
  228.                 munication  line.  The choices are NONE and XON/XOFF.  XON/XOFF
  229.                 is the default.  If the remote system is  not  full  duplex  or
  230.                 cannot do XON/XOFF, you should use NONE.
  231.  
  232.         IBM ON (or OFF)
  233.                 Allow the transfer of files to and from an IBM  mainframe  com-
  234.                 puter.    This  makes  Kermit-86  wait  for  the IBM turnaround
  235.                 character (XON), ignore parity on input, add appropriate parity
  236.                 to  output,  and  use  local  echoing  during CONNECT.  As dis-
  237.  
  238.  
  239.  
  240.                 tributed, KERMIT-86 uses MARK parity for IBM communication.  If
  241.                 you don't give this command, IBM mode is OFF.  Since IBM VM/CMS
  242.                 KERMIT does not have timeout capability, SET IBM ON also  turns
  243.                 on the timeout facility automatically, as if you had typed "SET
  244.                 TIMER ON".
  245.  
  246.         LOCAL-ECHO ON (or OFF)
  247.                 When  you  CONNECT to a remote host, you must set LOCAL-ECHO ON
  248.                 if the host is half  duplex,  OFF  if  full  duplex.    OFF  by
  249.                 default.
  250.  
  251.         LOG     Specify  a  log  file  on  the  current CP/M disk into which to
  252.                 record incoming characters during CONNECT.  If the remote  host
  253.                 can  do XON/XOFF, then the log file will normally capture every
  254.                 character shown on the screen.  When connected  to  the  remote
  255.                 system,  several  single-character arguments to the connect es-
  256.                 cape character can be used to control logging --  Q  (quit),  R
  257.                 (resume), L (toggle).  If you use R or L during connect without
  258.                 having previously specified a log file name, then KERMIT.LOG is
  259.                 used.  An open log is closed when you escape back to the PC.
  260.  
  261.         PARITY  Sets  parity  for  outgoing characters to one of the following:
  262.                 NONE, SPACE, MARK, EVEN, or ODD.  On input, if parity is  NONE,
  263.                 then  the  8th  bit is kept (as data), otherwise it is stripped
  264.                 and ignored.  The parity setting applies to both terminal  con-
  265.                 nection and file transfer.  If you set parity to anything other
  266.                 than NONE, Kermit-86 will attempt to use "8th bit prefixing" to
  267.                 transfer  binary files.  If the other KERMIT is also capable of
  268.                 8th bit prefixing, then binary files can  be  transferred  suc-
  269.                 cessfully;  if  not, the 8th bit of each data byte will be lost
  270.                 (you will see a warning on your screen if this happens).
  271.  
  272.         PORT    Allows you to switch between different communication  ports  on
  273.                 the PC.  This command is not available on all systems.
  274.  
  275.         TIMER ON (or OFF)
  276.                 Enable or disable the timeout facility.  The timer  is  off  by
  277.                 default,  because in the normal case KERMIT-86 is communicating
  278.                 with a mainframe KERMIT that has its own timer.  Mainframe KER-
  279.                 MIT  timers  tend  to  be more precise or adaptable to changing
  280.                 conditions.  You should SET TIMER ON if you  are  communicating
  281.                 with another KERMIT that does not have a timer.  You should SET
  282.                 TIMER OFF if you are communicating over  a  network  with  long
  283.                 delays.
  284.  
  285.         WARNING ON (or OFF)
  286.                 Warn user of  filename  conflicts  when  receiving  files  from
  287.                 remote  host,  and  attempt to generate a unique name by adding
  288.                 "&" characters to the given name.  OFF by default.
  289.  
  290. SHOW    Show the current settings of the SET parameters.
  291.  
  292. TAKE    Take KERMIT-86 commands from the specified file.  The file  should  not
  293.         contain any TAKE commands; nested command files do not work.
  294.  
  295. LOCAL   This  is  a  prefix  for local file management commands, to distinguish
  296.  
  297.  
  298.  
  299.         them from remote file management  commands  (which  aren't  implemented
  300.         yet).   The LOCAL prefix is optional; if left off, the commands will be
  301.         performed locally.
  302.  
  303.         SPACE           Show how much space is used and remaining on  the  cur-
  304.                         rent disk.
  305.  
  306.         DIRECTORY       Provide a directory listing for the current disk, show-
  307.                         ing the name and size of each file.  A filespec may  be
  308.                         given  to  select  only a certain file or wildcard file
  309.                         group.
  310.  
  311.         DELETE          Delete the specified files from the current disk.
  312.  
  313.         TYPE            A wildcard filespec is accepted and files displayed al-
  314.                         phabetically.    The  display  is paged in Unix fashion
  315.                         with "--more--" displayed on the last line.  Typein op-
  316.                         tions at that point can be obtained by hitting a '?'.
  317.  
  318.  
  319. 1.2. Installation:
  320.  
  321. CP/M-86 KERMIT is broken up into several source modules:
  322.  
  323.       86KERCMD.A86        Command parser
  324.       86KERFIL.A86        File handler
  325.       86KERIO.xxx         System Dependent I/O
  326.       86KERMIT.A86        Main Program
  327.       86KERPRO.A86        Protocol Module
  328.       86KERTRM.A86        Terminal Emulation
  329.       86KERUTL.A86        Utilities
  330.  
  331. The  main  program  module,  86KERMIT.A86,  contains INCLUDE directives for the
  332. other files.  The 86KERIO module  is  stored  with  suffixes  that  denote  the
  333. machine  for  which  the  program is being built -- RB for Rainbow, APC for NEC
  334. APC.  The program may be built on the  CP/M-86  system  by  obtaining  all  the
  335. source  files listed above, storing them on the current disk with the names in-
  336. dicated, renaming the appropriate 86KERIO.xxx file to be 86KERIO.A86, and  then
  337. doing:
  338.  
  339.       ASM86 86KERMIT $PZ  (takes about 6 minutes on the Rainbow)
  340.       GENCMD 86KERMIT     (takes less than a minute)
  341.  
  342. and, if desired,
  343.  
  344.       REN KERMIT.CMD=86KERMIT.CMD
  345.  
  346.  
  347. 1.3. DEC Rainbow 100 Support
  348.  
  349. KERMIT-86 runs on the DEC Rainbow 100 or 100+ under CP/M-86/80, version 1 or 2,
  350. on the 8088 side.  It uses the built-in firmware to emulate a VT102  ANSI  ter-
  351. minal during CONNECT, and runs well at speeds up to 9600 baud.
  352.  
  353. You should be able to download the program using the old KERMIT on the Z80 side
  354. (Rainbow Kermit, VT180 Kermit, or generic CP/M-80 Kermit will do the  job,  but
  355.  
  356.  
  357.  
  358. only under DEC CP/M-86/80 version 1.0), or an earlier version of KERMIT-86.
  359.  
  360. If  you don't have an earlier version of KERMIT, then follow the directions for
  361. installing KERMIT-80 (yes, KERMIT-80) in the KERMIT-80 section  of  the  KERMIT
  362. User  Guide,  but  send the KERMIT-86 hex file instead.  This works because the
  363. Rainbow can run CP/M-80 programs like DDT.
  364.  
  365. Another way to get KERMIT onto your Rainbow for the first time would be from  a
  366. DEC VT-180 diskette.  A VT-180 can use its own KERMIT to load RBKERMIT onto its
  367. disk, which can then be read directly by a Rainbow.   Also,  note  that  VT-180
  368. KERMIT-80  can actually run on the Rainbow on the Z80 side under DEC CP/M-86/80
  369. version 1 (but not version 2 or higher), at speeds of 1800 baud or lower.
  370.  
  371.  
  372. 1.4. NEC Advanced Personal Computer Support
  373.  
  374. (Contributed by Ron Blanford, University of Washington)
  375.  
  376. Currently only the standard serial port is supported, and not the H14 auxiliary
  377. port.  The SET PORT command is not implemented.
  378.  
  379. While  in  Kermit's  terminal emulation mode, local commands are initiated by a
  380. two-character sequence consisting of the "escape  character"  followed  by  one
  381. other  character  identifying the command.  (Make the second character a '?' to
  382. see a list of the valid commands.)  As distributed, the standard Kermit-86 uses
  383. the  control-backslash character as the escape character in terminal mode.  The
  384. trouble is that the CP/M-86 BIOS  in  the  APC  ignores  a  keyboard  entry  of
  385. Control-\  (i.e.  holding down the CTRL key while striking the '\' key), making
  386. it difficult (impossible) to use this method to get out of terminal mode.
  387.  
  388. One solution is to perform a "SET ESCAPE ^" command  before  entering  terminal
  389. mode  to change the escape character to a caret (or any other character the APC
  390. keyboard will generate).  This command could be placed in your KERMIT.INI  file
  391. for automatic execution every time Kermit is started.
  392.  
  393. The simpler solution is to realize that the character code for a Control-\ is a
  394. hexadecimal 1C, and that this is the code generated  by  the  INS  key  on  the
  395. numeric keypad.  Once you can remember that every reference to Control-\ should
  396. be interpreted as a reference to the INS key, this is actually  easier  to  use
  397. than the two-key Control-\ sequence.
  398.  
  399. In  the  standard  CP/M-86  BIOS,  the  unshifted DEL key generates a Control-X
  400. character (hexadecimal 18).  This is the CP/M command to erase the current  in-
  401. put  line, and is very useful for local processing.  Most mainframes do not use
  402. the Control-X character at all, so it becomes much less useful during  terminal
  403. emulation.    The  DEL  character (hexadecimal 7F), on the other hand, is often
  404. used by mainframes and can only be generated on the APC  by  holding  down  the
  405. SHIFT key while striking the DEL key (this capability is not mentioned anywhere
  406. in the documentation).
  407.  
  408. Because the Control-X character is so seldom used while the  DEL  character  is
  409. commonly  used,  the initialization procedure in Kermit-86 modifies the CP/M-86
  410. BIOS so that the DEL key generates the DEL character whether  shifted  or  not.
  411. Control-X  can  still  be  generated  if necessary by holding down the CTRL key
  412. while striking the 'X' key.  The CP/M-86 BIOS is returned to its original state
  413. when Kermit terminates.
  414.  
  415.  
  416.  
  417. The  APC uses escape sequences which have been standardized by the American Na-
  418. tional Standards Institute (ANSI) to control cursor movement,  screen  erasing,
  419. and  character  attribute  manipulation.  Perhaps the best-known other terminal
  420. which follows ANSI guidelines is the DEC VT100.  The APC only recognizes a  few
  421. of  the  more important ANSI commands, and not the complete set which the VT100
  422. supports.
  423.  
  424. The ANSI/VT100 features that the NEC APC supports are:
  425.  
  426.    - direct cursor addressing (by row and column)
  427.    - relative cursor addressing (up, down, left, right)
  428.    - line erasing (cursor to end, beginning to cursor, entire line)
  429.    - screen erasing (cursor to end, beginning to cursor, entire screen)
  430.    - character attributes (underline, reverse video, blink, but not bold)
  431.  
  432. In addition, the first four grey function keys (unshifted) generate the  escape
  433. sequences  associated  with  PF1  through PF4 on the VT100 keyboard.  The arrow
  434. keys and numeric keypad DO NOT generate the corresponding VT100 sequences.
  435.  
  436. These functions are enough to support simple command line editing on most  sys-
  437. tems,  and allow mailers or paged file display programs to clear the screen be-
  438. fore each display.  Underlining and reverse video are also useful in  some  ap-
  439. plications.    This is not enough to support the more sophisticated screen con-
  440. trol required by screen editors such as EMACS or KED.  In addition,  due  to  a
  441. bug  in the implementation of the CP/M-86 BIOS, the sequence ordinarily used to
  442. home the cursor (esc [ H) does not work correctly; a patch for CP/M to  correct
  443. this problem is distributed with APC Kermit-86.
  444.  
  445.  
  446.  
  447. Index
  448.  
  449.           APC   6
  450.  
  451.           Baud   2
  452.           BYE   2
  453.  
  454.           Connect   1
  455.  
  456.           Debugging   3
  457.           DEC Rainbow   5
  458.  
  459.           Eighth-Bit Prefix   4
  460.           Escape Character   1, 3
  461.  
  462.           File-Warning   2
  463.           FINISH   2
  464.           Flow Control   3
  465.  
  466.           GET   2
  467.  
  468.           IBM   3
  469.  
  470.           Local   0
  471.           Local-Echo   4
  472.           LOG   4
  473.           LOGOUT   2
  474.  
  475.           NAK   1
  476.           NEC Advanced Personal Computer
  477.                   6
  478.  
  479.           Parity   4
  480.  
  481.           Rainbow 100   5
  482.           RECEIVE   2
  483.  
  484.           SEND   2
  485.           SET   2
  486.           SHOW   4
  487.  
  488.           TAKE   4
  489.           Timeout   0, 1
  490.           TIMER   4
  491.  
  492.           Virtual Terminal   1
  493.  
  494.           Warning   4
  495.  
  496.  
  497.  
  498.                                Table of Contents
  499.  
  500. 1. CP/M-86 KERMIT                                                             0
  501.  
  502.    1.1. Kermit-86 Commands                                                    1
  503.    1.2. Installation:                                                         5
  504.    1.3. DEC Rainbow 100 Support                                               5
  505.    1.4. NEC Advanced Personal Computer Support                                6
  506.  
  507. Index                                                                         i
  508.